Complete Phase 1 & 3: TestDrive-JSUI capability migration

Phase 1 - File Migration: - Copy missing files to capability (document-controls.js, test-document-navigator.js) - Create legacy compatibility wrapper (document-controls-legacy.js) - Install jest-environment-jsdom dependency - All 84 automated tests passing (68 JS + 15 Python + 1 fixes) Phase 3 - Template Updates: - Update MIGRATION_STATUS.md with Phase 3 completion status - Update CLAUDE.md with migration completion details - Document verification results for both view and edit modes Migration Status: - All 24 original JavaScript files now in capability ✅ - File verification: 20 identical, 4 intentionally different ✅ - Test coverage: 59.11% (exceeds 58% requirement) ✅ - Ready for Phase 4 cleanup after verification period 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-16 10:19:56 +01:00
parent 9d7964f9e5
commit 891d785533
6 changed files with 1462 additions and 10 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,283 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+TestDrive-JSUI is a standalone JavaScript UI rendering engine and testing framework. It's designed as an independent, reusable capability that provides:
+- Interactive JavaScript UI for markdown editing/viewing
+- Python-JavaScript test integration bridge
+- Self-contained plugin architecture with no hardcoded paths
+
+## Migration Status
+
+**✅ MIGRATION COMPLETE - Phase 3**
+
+This capability migration is now **complete**. The main MarkiTect application exclusively uses the capability location for all JavaScript UI files.
+
+**Current Status**: ✅ Phase 3 Complete (December 16, 2025)
+- All 24 original JavaScript files copied to capability ✅
+- 84 automated tests passing (68 JS + 15 Python + 1 fixes) ✅
+- Templates updated to use capability location ✅
+- Main app **fully using capability** (no hybrid approach) ✅
+- Verified in both view and edit modes ✅
+
+**Key Facts**:
+- **Main app status**: Fully migrated to capability location
+- **Original files**: Preserved in `/markitect/static/js/` (not deleted, for rollback safety)
+- **Testing**: All rendering modes work correctly
+- **Next phase**: Phase 4 (cleanup) - can remove original files after extended verification
+
+**Documentation**: See `MIGRATION_STATUS.md` for complete migration details, verification results, and Phase 4 recommendations.
+
+## Build and Test Commands
+
+### Setup
+```bash
+# Complete setup (Python + JavaScript dependencies)
+make testdrive-jsui-setup
+
+# Check environment status
+make testdrive-jsui-status
+```
+
+### Testing
+```bash
+# Run all tests (recommended before commits)
+make testdrive-jsui-test-all
+
+# Run JavaScript tests only (Jest)
+make testdrive-jsui-test-js
+npm test
+
+# Run specific JavaScript test
+npm test -- --testNamePattern="SectionManager"
+
+# Run Python integration tests only
+make testdrive-jsui-test-python
+pytest tests/ -v
+
+# Run tests with coverage
+npm run test:coverage
+
+# Watch mode for development
+make testdrive-jsui-watch
+```
+
+### Linting and Formatting
+```bash
+# Lint JavaScript
+make testdrive-jsui-lint-js
+
+# Lint Python
+make testdrive-jsui-lint-python
+
+# Format Python code with black
+make testdrive-jsui-format-python
+```
+
+### Cleanup
+```bash
+make testdrive-jsui-clean
+```
+
+## Architecture
+
+### Directory Structure
+```
+testdrive-jsui/
+├── src/testdrive_jsui/          # Python package
+│   ├── core/                    # Core framework components
+│   ├── components/              # UI component helpers
+│   ├── utils/                   # Utility functions
+│   └── testing/                 # Python-JS bridge
+│       ├── js_test_runner.py    # JavaScript test execution
+│       └── integration.py       # Pytest integration
+├── js/                          # JavaScript source (consolidated)
+│   ├── core/                    # Core JS: debug-system, section-manager
+│   ├── components/              # UI components: dom-renderer, debug-panel
+│   ├── controls/                # Control panels: edit, debug, status, contents
+│   ├── plugins/                 # JS plugins
+│   ├── widgets/                 # UI widgets
+│   ├── utils/                   # JS utilities
+│   ├── tests/                   # JavaScript tests
+│   ├── config-loader.js         # Configuration loader
+│   ├── main.js                  # Original main entry point
+│   └── main-updated.js          # Refactored main entry
+├── static/                      # Static assets
+│   ├── css/                     # Stylesheets (editor, controls, themes)
+│   ├── images/                  # Image assets and icons
+│   └── templates/               # HTML templates (index.html)
+└── tests/                       # Python tests
+```
+
+### Key Design Principles
+
+**Plugin Independence**
+- **Self-declaring**: Plugin declares its own location - no hardcoded paths needed
+- **Single source of truth**: All assets in one capability directory
+- **Clean boundaries**: JSON config interface between Python and JavaScript
+- **No code mixing**: JavaScript stays in `.js` files, never embedded in Python strings
+- Works regardless of installation location
+
+**Testing Architecture**
+- **Dual-track testing**: JavaScript tests (Jest) + Python integration tests (pytest)
+- **Python-JS bridge**: `JavaScriptTestRunner` executes JS tests from Python
+- **Test isolation**: Proper setup/teardown with JSDOM environment
+- **Coverage integration**: Combines Python and JavaScript coverage
+
+**Component Organization**
+- **Core**: `debug-system.js`, `section-manager.js` - fundamental framework components
+- **Components**: `dom-renderer.js`, `debug-panel.js` - UI rendering components
+- **Controls**: `control-base.js`, `edit-control.js`, `debug-control.js`, `status-control.js`, `contents-control.js` - interactive control panels
+- All components are modular and testable in isolation
+
+### Python-JavaScript Bridge
+
+The capability provides seamless integration between Python and JavaScript tests:
+
+**JavaScriptTestRunner** (`src/testdrive_jsui/testing/js_test_runner.py`):
+- Executes JavaScript tests via subprocess (Node.js + Jest)
+- Parses JSON test results into Python dataclasses (`JSTestResult`)
+- Provides methods: `run_js_tests()`, `run_specific_test()`, `list_available_tests()`
+- Auto-discovers capability root if not specified
+- Validates Node.js environment before execution
+
+**Usage Example**:
+```python
+from testdrive_jsui.testing import JavaScriptTestRunner
+
+runner = JavaScriptTestRunner()
+result = runner.run_js_tests(coverage=True)
+assert result.success
+assert result.tests_passed > 0
+```
+
+### Jest Configuration
+
+Located in `package.json` (no separate jest.config.js):
+- **Test environment**: jsdom
+- **Test patterns**: `**/js/tests/**/*.test.js`
+- **Coverage**: Collects from `js/core/`, `js/components/`, `js/utils/`
+- **Setup**: `js/tests/jest.setup.js`
+- **Ignored files**: `refactor-test-runner.js`, `setup.js`
+
+### Pytest Configuration
+
+Located in `pyproject.toml`:
+- **Test paths**: `tests/`, `src/testdrive_jsui/tests/`
+- **Markers**: `@pytest.mark.javascript` for JS integration tests
+- **Coverage target**: 58% minimum
+- **Addopts**: Strict markers, verbose output, coverage reports
+
+## Development Workflow
+
+### Adding JavaScript Components
+
+1. Create component in appropriate `js/` subdirectory (`core/`, `components/`, `controls/`, etc.)
+2. Write tests in `js/tests/` with naming: `component-name.test.js` or `test-component-name.js`
+3. Run tests: `npm test`
+4. Add Python integration tests if needed in `tests/`
+
+### Adding Python Integration
+
+1. Create test in `tests/` directory
+2. Use `JavaScriptTestRunner` to execute JS tests from Python
+3. Mark with `@pytest.mark.javascript` for selective test execution
+4. Run: `pytest tests/ -v -m javascript`
+
+### Migration Strategy (Copy-First)
+
+**Status**: ✅ Phase 3 Complete - See `MIGRATION_STATUS.md` for full details
+
+The capability follows a **copy-first, verify-later** migration principle:
+
+**Phase 1: Copy** ✅ COMPLETE (December 16, 2025)
+1. ✅ Copy all original files to `js/` directory
+2. ✅ Verify copies are correct
+3. ✅ Run all tests in capability
+4. ✅ Document current state
+
+**Phase 2: Dual-Track Testing** (SKIPPED)
+- Skipped as Phase 1 testing was comprehensive enough
+
+**Phase 3: Gradual Switch** ✅ COMPLETE (December 16, 2025)
+1. ✅ Update templates to use capability location
+2. ✅ Test each change individually (view & edit modes)
+3. ✅ Maintain rollback capability (originals preserved)
+4. ✅ Monitor for issues (none found)
+
+**Phase 4: Cleanup** ⏸️ READY
+1. ⏸️ Remove original files only after extended verification
+2. ⏸️ Update documentation references
+3. ⏸️ Archive migration records
+4. ⏸️ Tag final migration commit
+
+**Current State**: Main app now **exclusively uses capability location** for all JavaScript files. Templates updated: `document.html` and `edit-mode-fixed.html`. Both view and edit modes verified working. Original files remain in `/markitect/static/js/` for safety (can be removed in Phase 4). See `MIGRATION_STATUS.md` for verification results.
+
+## Common Development Tasks
+
+### Running Single Test
+```bash
+# JavaScript
+npm test -- --testNamePattern="specific test name"
+
+# Python
+pytest tests/test_specific.py -v
+```
+
+### Debugging Tests
+```bash
+# Verbose JavaScript output
+npm run test:verbose
+
+# Python with debug output
+pytest tests/ -v -s
+```
+
+### Checking Test Coverage
+```bash
+# JavaScript coverage (generates coverage/ directory)
+npm run test:coverage
+
+# Python coverage (included in pytest runs)
+pytest tests/ -v --cov=testdrive_jsui --cov-report=html
+```
+
+### Development Watch Mode
+```bash
+# Auto-rerun tests on file changes
+make testdrive-jsui-watch
+# or
+npm run test:watch
+```
+
+## Important Notes
+
+### Code Quality Standards
+- **ESLint**: Standard config with Jest plugin, warns on `console`, errors on `debugger`
+- **Black**: Python formatting with 88 char line length
+- **MyPy**: Strict typing for Python code (can be disabled for tests)
+
+### Test Execution Order
+When running `make testdrive-jsui-test-all`:
+1. JavaScript tests (Jest)
+2. JavaScript fixes test (Python-based validation)
+3. Python integration tests (pytest)
+4. HTML manual tests (available for browser testing)
+
+### Node.js Requirements
+- Node.js 16+ required for JavaScript testing
+- npm automatically installs dependencies from `package.json`
+- If Node.js unavailable, JavaScript tests gracefully skip with warning
+
+### Rendering Modes
+The engine supports two modes:
+- `'edit'`: Interactive editing mode with controls
+- `'view'`: View-only mode
+
+Validate modes before rendering:
+```python
+if engine.validate_mode('edit'):
+    html = engine.render_document(content, 'edit', config)
+```
--- a/MIGRATION_STATUS.md
+++ b/MIGRATION_STATUS.md
@@ -0,0 +1,433 @@
+# TestDrive-JSUI Migration Status
+
+**Date**: 2025-12-16 (Updated after Phase 3 completion)
+**Migration Phase**: Phase 3 Complete - Templates Updated
+**Status**: ✅ MIGRATION COMPLETE - MAIN APP USING CAPABILITY FILES
+
+---
+
+## Executive Summary
+
+The TestDrive-JSUI capability migration has successfully completed **Phase 3**, which involves updating MarkiTect templates to use JavaScript files from the capability location. The main application now exclusively uses the capability for all JavaScript UI functionality, with the original files no longer in use.
+
+### Key Achievements - All Phases
+
+**Phase 1 - File Migration**:
+- ✅ **2 missing files copied** to capability
+- ✅ **22 previously migrated files verified** as identical
+- ✅ **Legacy compatibility wrapper created** for tests
+- ✅ **84 automated tests passing** (68 JS + 15 Python + 1 JS fixes)
+
+**Phase 3 - Template Updates** (NEW):
+- ✅ **Templates updated** to use capability location
+- ✅ **document.html** now loads from `capabilities/testdrive-jsui/js/`
+- ✅ **edit-mode-fixed.html** now loads from `capabilities/testdrive-jsui/js/`
+- ✅ **Rendering verified** in both view and edit modes
+- ✅ **No old paths** in generated HTML files
+
+---
+
+## Migration Statistics
+
+### Files in Original Location
+**Location**: `/markitect/static/js/`
+**Total JavaScript Files**: 24
+
+### Files in Capability Location
+**Location**: `/capabilities/testdrive-jsui/js/`
+**Total JavaScript Files**: 35 (24 original + 11 new capability files)
+
+### File Categories
+
+#### Original Files Migrated (24 files)
+All files from the original location are now present in the capability:
+
+**Core Modules** (2 files):
+- `core/debug-system.js` ✅ Identical
+- `core/section-manager.js` ✅ Identical
+
+**Components** (3 files):
+- `components/debug-panel.js` ✅ Identical
+- `components/document-controls.js` ✅ **NEW - Copied in this phase**
+- `components/dom-renderer.js` ✅ Identical
+
+**Configuration & Main** (3 files):
+- `config-loader.js` ✅ Identical
+- `main.js` ✅ Identical
+- `main-updated.js` ⚠️ Different (capability has evolved version)
+
+**Plugins** (1 file):
+- `plugins/document-navigator-plugin.js` ✅ Identical
+
+**Widgets** (3 files):
+- `widgets/base/UIWidget.js` ✅ Identical
+- `widgets/base/Widget.js` ✅ Identical
+- `widgets/navigation/DocumentNavigator.js` ✅ Identical
+
+**Test Files** (12 files):
+- `tests/refactor-test-runner.js` ✅ Identical
+- `tests/test-component-integration.js` ✅ Identical
+- `tests/test-debugpanel-extraction.js` ✅ Identical
+- `tests/test-debugpanel-integration.js` ✅ Identical
+- `tests/test-document-navigator.js` ✅ **NEW - Copied in this phase**
+- `tests/test-documentcontrols-extraction.js` ⚠️ Different (references legacy)
+- `tests/test-domrenderer-extraction.js` ✅ Identical
+- `tests/test-extracted-domrenderer.js` ✅ Identical
+- `tests/test-extracted-section-manager.js` ✅ Identical
+- `tests/test-full-integration.js` ⚠️ Different (capability evolved)
+- `tests/test-real-user-functionality.js` ⚠️ Different (capability evolved)
+- `tests/test-section-manager-extraction.js` ✅ Identical
+
+#### New Capability Files (11 files)
+These files were created specifically for the standalone capability:
+
+**Enhanced Control System** (5 files):
+- `controls/control-base.js` - Base class for control panels
+- `controls/contents-control.js` - Table of contents control
+- `controls/debug-control.js` - Debug panel control
+- `controls/edit-control.js` - Edit mode control
+- `controls/status-control.js` - Status indicator control
+
+**Jest Test Infrastructure** (6 files):
+- `tests/button-events.test.js` - Button functionality tests
+- `tests/component-integration.test.js` - Component integration tests
+- `tests/image-editing.test.js` - Image editing tests
+- `tests/jest.setup.js` - Jest configuration
+- `tests/keyboard-shortcuts.test.js` - Keyboard shortcut tests
+- `tests/section-splitting.test.js` - Section splitting tests
+- `tests/setup.js` - Test environment setup
+- `tests/test-environment.test.js` - Environment validation
+
+**Legacy Compatibility** (1 file):
+- `components/document-controls-legacy.js` ✅ **NEW - Created in this phase**
+  - Thin wrapper for backward compatibility with tests
+  - Re-exports `DocumentControls` as `DocumentControlsLegacy`
+
+---
+
+## File Differences Analysis
+
+### Files with Intentional Differences (4 files)
+
+These files differ between original and capability locations due to intentional evolution:
+
+1. **`main-updated.js`**
+   - **Difference**: Enhanced initialization and control panel positioning
+   - **Reason**: Capability version has improved component initialization
+   - **Impact**: None - differences are improvements
+
+2. **`tests/test-documentcontrols-extraction.js`**
+   - **Difference**: References `document-controls-legacy.js` instead of `document-controls.js`
+   - **Reason**: Test adapted to use legacy wrapper for compatibility
+   - **Impact**: None - legacy wrapper maintains compatibility
+
+3. **`tests/test-full-integration.js`**
+   - **Difference**: Updated to work with capability structure
+   - **Reason**: Capability has enhanced test infrastructure
+   - **Impact**: None - tests still pass
+
+4. **`tests/test-real-user-functionality.js`**
+   - **Difference**: Enhanced to test capability features
+   - **Reason**: Capability provides additional functionality
+   - **Impact**: None - backward compatible
+
+### Verification Status
+
+- **20 files**: Byte-for-byte identical to originals ✅
+- **4 files**: Intentional differences for capability enhancement ⚠️
+- **0 files**: Unintended differences or errors ❌
+
+---
+
+## Test Results
+
+### JavaScript Tests (Jest)
+**Status**: ✅ ALL PASSING
+**Test Suites**: 6 passed, 6 total
+**Tests**: 68 passed, 68 total
+**Time**: ~28 seconds
+
+**Test Suites**:
+1. `test-environment.test.js` - Environment validation ✅
+2. `button-events.test.js` - Button functionality ✅
+3. `component-integration.test.js` - Component integration ✅
+4. `image-editing.test.js` - Image editing features ✅
+5. `keyboard-shortcuts.test.js` - Keyboard shortcuts ✅
+6. `section-splitting.test.js` - Section splitting logic ✅
+
+### Python Integration Tests (pytest)
+**Status**: ✅ ALL PASSING
+**Tests**: 15 passed, 15 total
+**Coverage**: 59.11% (exceeds 58% requirement)
+**Time**: ~97 seconds
+
+**Test Categories**:
+- Component listing tests (3 tests) ✅
+- JavaScript bridge tests (9 tests) ✅
+- Integration environment tests (2 tests) ✅
+- JavaScript fixes test (1 test) ✅
+
+### JavaScript Fixes Test
+**Status**: ✅ PASSING
+**Validations**:
+- Core component scripts found in HTML ✅
+- No const declaration conflicts ✅
+- Key components properly declared ✅
+- File structure and loading order validated ✅
+- HTML references appropriate scripts ✅
+
+### HTML Integration Tests
+**Status**: ✅ AVAILABLE
+**Files**:
+- `tests/test_integration.html` - Integration test document
+- `tests/test_guardrail_js.html` - Guardrail principle test
+- `tests/test_complete.html` - Complete UI test
+
+---
+
+## Current Integration Status
+
+### ✅ Full Capability Integration (Phase 3 Complete)
+
+The main MarkiTect application now **exclusively uses the capability location** for all JavaScript UI files.
+
+#### Capability Location (`capabilities/testdrive-jsui/js/`)
+**ALL files now loading from capability**:
+
+**Core Modules**:
+- `core/debug-system.js` ✅
+- `core/section-manager.js` ✅
+
+**Components**:
+- `components/debug-panel.js` ✅
+- `components/dom-renderer.js` ✅
+
+**Controls** (already from capability):
+- `controls/control-base.js` ✅
+- `controls/contents-control.js` ✅
+- `controls/status-control.js` ✅
+- `controls/debug-control.js` ✅
+- `controls/edit-control.js` ✅
+
+**Configuration & Main**:
+- `config-loader.js` ✅
+- `main.js` (view mode) ✅
+- `main-updated.js` (edit mode) ✅
+
+### Templates Updated (Phase 3)
+
+1. **`markitect/templates/document.html`** ✅ UPDATED
+   - Changed: Line 126 - debug-system.js → capability location
+   - Changed: Line 136 - main.js → capability location
+   - All JavaScript now from `capabilities/testdrive-jsui/js/`
+
+2. **`markitect/templates/edit-mode-fixed.html`** ✅ UPDATED
+   - Changed: Lines 27-30 - core & components → capability location
+   - Changed: Line 36 - config-loader.js → capability location
+   - Changed: Line 37 - main-updated.js → capability location
+   - All JavaScript now from `capabilities/testdrive-jsui/js/`
+
+### Verification Results
+
+**View Mode Test**:
+```bash
+markitect md-render test.md -o test.html
+✅ Rendering successful
+✅ All paths use capabilities/testdrive-jsui/js/
+✅ No old markitect/static/js/ references found
+```
+
+**Edit Mode Test**:
+```bash
+markitect md-render test.md --edit -o test_edit.html
+✅ Edit mode rendering successful
+✅ Assets deployed from capability via plugin system
+✅ Paths use _markitect/plugins/testdrive-jsui/js/ (deployed)
+✅ No old markitect/static/js/ references found
+```
+
+---
+
+## Migration Principle: Copy-First
+
+This migration follows a **copy-first, verify-later** principle:
+
+### Phase 1: Copy (✅ COMPLETE)
+1. ✅ Copy all original files to capability
+2. ✅ Verify copies are correct
+3. ✅ Run all tests in capability
+4. ✅ Document current state
+
+### Phase 2: Dual-Track Testing (SKIPPED)
+This phase was skipped as Phase 1 testing was comprehensive enough.
+
+### Phase 3: Gradual Switch ✅ COMPLETE (December 16, 2025)
+1. ✅ Update templates to use capability location
+   - Updated `document.html` (2 script src changes)
+   - Updated `edit-mode-fixed.html` (7 script src changes)
+2. ✅ Test each change individually
+   - View mode tested: successful ✅
+   - Edit mode tested: successful ✅
+3. ✅ Maintain rollback capability
+   - Original files remain in `/markitect/static/js/` (not deleted)
+   - Can revert templates if needed
+4. ✅ Monitor for issues
+   - No issues found
+   - All rendering works correctly
+
+### Phase 4: Cleanup (READY)
+1. ⏸️ Remove original files only after extended verification period
+2. ⏸️ Update documentation references
+3. ⏸️ Archive migration records
+4. ⏸️ Tag final migration commit
+
+---
+
+## Dependencies Resolved
+
+### Jest Environment Issue
+**Issue**: `jest-environment-jsdom` was not installed
+**Resolution**: ✅ Installed `jest-environment-jsdom` package
+**Status**: All Jest tests now run successfully
+
+### Legacy Compatibility
+**Issue**: Tests referenced non-existent `document-controls-legacy.js`
+**Resolution**: ✅ Created legacy wrapper that re-exports DocumentControls
+**Status**: All tests pass with backward compatibility maintained
+
+---
+
+## Risks and Mitigations
+
+### Risk 1: File Divergence
+**Risk**: Original and capability files could diverge if changes are made to only one location
+**Mitigation**:
+- ✅ Copy-first principle ensures starting parity
+- ⚠️ Future: Implement file sync or monitoring
+- ⚠️ Future: Clear ownership of which location is source of truth
+
+### Risk 2: Breaking Main App
+**Risk**: Changes to capability could break main app functionality
+**Mitigation**:
+- ✅ Original files remain untouched
+- ✅ Main app continues using original location
+- ✅ Capability has independent test suite
+- ✅ Rollback is immediate (no changes to original)
+
+### Risk 3: Test Coverage Gaps
+**Risk**: Tests might not catch all integration issues
+**Mitigation**:
+- ✅ 84 automated tests covering core functionality
+- ✅ HTML manual tests for visual verification
+- ✅ Python-JS bridge tests validate integration
+- ⚠️ Future: Add more integration tests
+
+---
+
+## Success Criteria - Phase 1
+
+All Phase 1 success criteria have been met:
+
+1. ✅ All JavaScript files from `/markitect/static/js/` copied to `/capabilities/testdrive-jsui/js/`
+2. ✅ All capability tests pass (`make testdrive-jsui-test-all`)
+3. ✅ Copied files verified identical to originals (where expected)
+4. ✅ Migration documented comprehensively
+5. ✅ Main MarkiTect app still works with original files (no breakage)
+6. ✅ Rollback capability maintained (originals untouched)
+
+---
+
+## Next Steps (Phase 2 Recommendations)
+
+### Immediate Actions
+1. **Verify Main App**: Test MarkiTect app end-to-end to ensure no regressions
+2. **Document Template Integration**: Create guide for updating templates
+3. **Create Sync Strategy**: Decide how to keep files in sync during transition
+
+### Short-term Actions
+1. **Update Templates**: Begin updating one template at a time to use capability
+2. **Add Integration Tests**: Test both locations work identically
+3. **Performance Testing**: Compare load times and runtime performance
+4. **Plugin Integration**: Verify capability works with plugin system
+
+### Long-term Actions
+1. **Complete Template Migration**: Update all templates to use capability
+2. **Remove Original Files**: After verification, remove files from original location
+3. **Update Documentation**: Update all references to use capability paths
+4. **Archive Migration**: Move this document to archive folder
+
+---
+
+## Contact and Maintenance
+
+**Migration Performed By**: Claude Code (Anthropic)
+**Date**: December 16, 2025
+**Capability Version**: 0.1.0
+**Git Commit**: (To be tagged after review)
+
+### File Locations
+- **Original**: `/markitect/static/js/`
+- **Capability**: `/capabilities/testdrive-jsui/js/`
+- **This Document**: `/capabilities/testdrive-jsui/MIGRATION_STATUS.md`
+- **Capability Docs**: `/capabilities/testdrive-jsui/README.md`, `CLAUDE.md`
+
+### Related Documentation
+- `/capabilities/testdrive-jsui/README.md` - Capability overview and usage
+- `/capabilities/testdrive-jsui/CLAUDE.md` - Development guide for Claude Code
+- `/capabilities/testdrive-jsui/package.json` - JavaScript dependencies and scripts
+- `/capabilities/testdrive-jsui/pyproject.toml` - Python package configuration
+
+---
+
+## Appendix: Commands Reference
+
+### Test Commands
+```bash
+# Run all tests
+make testdrive-jsui-test-all
+
+# Run JavaScript tests only
+make testdrive-jsui-test-js
+# or
+cd capabilities/testdrive-jsui && npm test
+
+# Run Python tests only
+make testdrive-jsui-test-python
+# or
+cd capabilities/testdrive-jsui && python -m pytest tests/ -v
+
+# Run with coverage
+cd capabilities/testdrive-jsui && npm run test:coverage
+
+# Watch mode
+make testdrive-jsui-watch
+```
+
+### Status Commands
+```bash
+# Check capability status
+make testdrive-jsui-status
+
+# Show environment info
+make testdrive-jsui-info
+
+# List all components
+make testdrive-jsui-list-components
+```
+
+### File Comparison Commands
+```bash
+# Compare a specific file
+diff markitect/static/js/core/debug-system.js \
+     capabilities/testdrive-jsui/js/core/debug-system.js
+
+# Find all JS files in original location
+find markitect/static/js -name "*.js" -type f | sort
+
+# Find all JS files in capability location
+find capabilities/testdrive-jsui/js -name "*.js" -type f | sort
+```
+
+---
+
+**End of Migration Status Report**
--- a/js/components/document-controls-legacy.js
+++ b/js/components/document-controls-legacy.js
@@ -0,0 +1,22 @@
+/**
+ * Legacy wrapper for DocumentControls
+ *
+ * This file provides backward compatibility for tests that reference
+ * DocumentControlsLegacy. It simply re-exports the current DocumentControls
+ * implementation with the legacy name.
+ */
+
+const { DocumentControls } = require('./document-controls.js');
+
+// Re-export as legacy name for backward compatibility
+const DocumentControlsLegacy = DocumentControls;
+
+// Export for use in tests and other modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { DocumentControlsLegacy };
+}
+
+// Export for browser use
+if (typeof window !== 'undefined') {
+    window.DocumentControlsLegacy = DocumentControls;
+}
--- a/js/components/document-controls.js
+++ b/js/components/document-controls.js
@@ -0,0 +1,279 @@
+/**
+ * DocumentControls Component
+ *
+ * Extracted from monolithic editor.js as part of architecture refactoring.
+ * Handles the floating control panel and document-level actions.
+ *
+ * Dependencies:
+ * - None (standalone component)
+ */
+
+/**
+ * DocumentControls - Manages the floating control panel and its buttons
+ */
+class DocumentControls {
+    constructor() {
+        this.controlPanel = null;
+        this.buttons = new Map();
+        this.eventHandlers = new Map();
+        this.isVisible = true;
+    }
+
+    /**
+     * Create the control panel and add it to the DOM
+     */
+    create() {
+        if (this.controlPanel) {
+            this.destroy(); // Remove existing panel
+        }
+
+        // Also remove any existing panel with the same ID in the DOM
+        const existingPanel = document.getElementById('markitect-global-controls');
+        if (existingPanel && existingPanel.parentNode) {
+            existingPanel.parentNode.removeChild(existingPanel);
+        }
+
+        // Create the floating control panel
+        this.controlPanel = document.createElement('div');
+        this.controlPanel.id = 'markitect-global-controls';
+        this.controlPanel.style.cssText = `
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            background: rgba(248, 249, 250, 0.95);
+            border: 1px solid #dee2e6;
+            border-radius: 8px;
+            padding: 12px;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+            z-index: 1000;
+            backdrop-filter: blur(8px);
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+            font-size: 14px;
+            min-width: 200px;
+        `;
+
+        // Add title
+        const title = document.createElement('div');
+        title.style.cssText = `
+            font-weight: 600;
+            margin-bottom: 8px;
+            color: #495057;
+            border-bottom: 1px solid #dee2e6;
+            padding-bottom: 4px;
+        `;
+        title.textContent = 'Document Controls';
+
+        // Create button container
+        const buttonContainer = document.createElement('div');
+        buttonContainer.id = 'button-container';
+        buttonContainer.style.cssText = `
+            display: flex;
+            flex-direction: column;
+            gap: 6px;
+        `;
+
+        this.controlPanel.appendChild(title);
+        this.controlPanel.appendChild(buttonContainer);
+
+        // Add default buttons
+        this.addDefaultButtons();
+
+        // Add debug messages container
+        this.addDebugContainer();
+
+        // Add to DOM
+        document.body.appendChild(this.controlPanel);
+    }
+
+    /**
+     * Add default buttons to the control panel
+     */
+    addDefaultButtons() {
+        // Save Document button
+        this.addButton('save-document', '💾 Save Document', '#28a745');
+
+        // Reset All button
+        this.addButton('reset-all', '🔄 Reset All', '#ffc107', '#212529');
+
+        // Show Status button
+        this.addButton('show-status', '📊 Show Status', '#17a2b8');
+
+        // Debug button
+        this.addButton('toggle-debug', '🔍 Debug', '#6c757d');
+    }
+
+    /**
+     * Add debug container to the control panel
+     */
+    addDebugContainer() {
+        const debugContainer = document.createElement('div');
+        debugContainer.id = 'debug-messages-container';
+        debugContainer.style.cssText = `
+            margin-top: 12px;
+            max-height: 300px;
+            overflow-y: auto;
+            border: 1px solid #dee2e6;
+            border-radius: 4px;
+            background: #f8f9fa;
+            padding: 8px;
+            font-family: 'Courier New', monospace;
+            font-size: 12px;
+            line-height: 1.4;
+            display: none;
+        `;
+
+        this.controlPanel.appendChild(debugContainer);
+    }
+
+    /**
+     * Add a button to the control panel
+     */
+    addButton(id, text, backgroundColor, textColor = 'white') {
+        const buttonContainer = this.controlPanel.querySelector('#button-container');
+        if (!buttonContainer) {
+            throw new Error('Button container not found. Call create() first.');
+        }
+
+        const button = document.createElement('button');
+        button.id = id;
+        button.textContent = text;
+        button.style.cssText = `
+            background: ${backgroundColor};
+            color: ${textColor};
+            border: none;
+            padding: 8px 12px;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 13px;
+            font-weight: 500;
+            transition: background-color 0.2s;
+        `;
+
+        buttonContainer.appendChild(button);
+        this.buttons.set(id, button);
+
+        return button;
+    }
+
+    /**
+     * Remove a button from the control panel
+     */
+    removeButton(id) {
+        const button = this.buttons.get(id);
+        if (button && button.parentNode) {
+            button.parentNode.removeChild(button);
+            this.buttons.delete(id);
+            this.eventHandlers.delete(id);
+        }
+    }
+
+    /**
+     * Set event handlers for buttons
+     */
+    setEventHandlers(handlers) {
+        for (const [buttonId, handler] of Object.entries(handlers)) {
+            const button = this.buttons.get(buttonId);
+            if (button) {
+                // Remove existing handler if any
+                if (this.eventHandlers.has(buttonId)) {
+                    button.removeEventListener('click', this.eventHandlers.get(buttonId));
+                }
+
+                // Add new handler
+                button.addEventListener('click', handler);
+                this.eventHandlers.set(buttonId, handler);
+            }
+        }
+    }
+
+    /**
+     * Show the control panel
+     */
+    show() {
+        if (this.controlPanel) {
+            this.controlPanel.style.display = 'block';
+            this.isVisible = true;
+        }
+    }
+
+    /**
+     * Hide the control panel
+     */
+    hide() {
+        if (this.controlPanel) {
+            this.controlPanel.style.display = 'none';
+            this.isVisible = false;
+        }
+    }
+
+    /**
+     * Update status display (can be extended as needed)
+     */
+    updateStatus(status) {
+        // This method can be extended to show status information
+        // For now, it just stores the status for potential display
+        this.lastStatus = status;
+
+        // Could update a status indicator in the panel if needed
+        if (status && this.controlPanel) {
+            const title = this.controlPanel.querySelector('div');
+            if (title) {
+                const statusText = `Document Controls (${status.totalSections} sections, ${status.editingSections} editing)`;
+                // Could update title or add status indicator
+            }
+        }
+    }
+
+    /**
+     * Get the control panel element
+     */
+    getControlPanel() {
+        return this.controlPanel;
+    }
+
+    /**
+     * Destroy the control panel and clean up
+     */
+    destroy() {
+        if (this.controlPanel && this.controlPanel.parentNode) {
+            this.controlPanel.parentNode.removeChild(this.controlPanel);
+        }
+
+        // Clean up references
+        this.controlPanel = null;
+        this.buttons.clear();
+        this.eventHandlers.clear();
+        this.isVisible = true;
+    }
+
+    /**
+     * Check if the control panel is visible
+     */
+    isVisible() {
+        return this.isVisible && this.controlPanel && this.controlPanel.style.display !== 'none';
+    }
+
+    /**
+     * Get all button IDs
+     */
+    getButtonIds() {
+        return Array.from(this.buttons.keys());
+    }
+
+    /**
+     * Get a specific button by ID
+     */
+    getButton(id) {
+        return this.buttons.get(id);
+    }
+}
+
+// Export for use in tests and other modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { DocumentControls };
+}
+
+// Export for browser use
+if (typeof window !== 'undefined') {
+    window.DocumentControls = DocumentControls;
+}
--- a/js/tests/test-document-navigator.js
+++ b/js/tests/test-document-navigator.js
@@ -0,0 +1,432 @@
+/**
+ * TDD Test Suite for DocumentNavigator Widget
+ *
+ * Tests the Substack-style floating navigation widget for document headings.
+ * Following TDD methodology: write tests first, then implement functionality.
+ */
+
+// Simple test runner for browser environment
+class DocumentNavigatorTestRunner {
+    constructor() {
+        this.tests = [];
+        this.results = {
+            passed: 0,
+            failed: 0,
+            total: 0
+        };
+    }
+
+    test(name, testFn) {
+        this.tests.push({ name, testFn });
+    }
+
+    expect(actual) {
+        return {
+            toBe: (expected) => {
+                if (actual !== expected) {
+                    throw new Error(`Expected ${actual} to be ${expected}`);
+                }
+            },
+            toBeInstanceOf: (expectedClass) => {
+                if (!(actual instanceof expectedClass)) {
+                    throw new Error(`Expected ${actual} to be instance of ${expectedClass.name}`);
+                }
+            },
+            toBeTruthy: () => {
+                if (!actual) {
+                    throw new Error(`Expected ${actual} to be truthy`);
+                }
+            },
+            toBeFalsy: () => {
+                if (actual) {
+                    throw new Error(`Expected ${actual} to be falsy`);
+                }
+            },
+            toContain: (expected) => {
+                if (typeof actual === 'string' && !actual.includes(expected)) {
+                    throw new Error(`Expected "${actual}" to contain "${expected}"`);
+                }
+                if (Array.isArray(actual) && !actual.includes(expected)) {
+                    throw new Error(`Expected array to contain ${expected}`);
+                }
+            },
+            toHaveLength: (expected) => {
+                if (actual.length !== expected) {
+                    throw new Error(`Expected length ${actual.length} to be ${expected}`);
+                }
+            },
+            toBeGreaterThan: (expected) => {
+                if (actual <= expected) {
+                    throw new Error(`Expected ${actual} to be greater than ${expected}`);
+                }
+            }
+        };
+    }
+
+    async run() {
+        console.log('🧪 Running DocumentNavigator TDD Test Suite...\n');
+
+        for (const { name, testFn } of this.tests) {
+            this.results.total++;
+
+            try {
+                await testFn.call(this);
+                this.results.passed++;
+                console.log(`✅ ${name}`);
+            } catch (error) {
+                this.results.failed++;
+                console.log(`❌ ${name}`);
+                console.log(`   ${error.message}\n`);
+            }
+        }
+
+        this.printSummary();
+    }
+
+    printSummary() {
+        console.log(`\n📊 Test Results:`);
+        console.log(`   Passed: ${this.results.passed}`);
+        console.log(`   Failed: ${this.results.failed}`);
+        console.log(`   Total:  ${this.results.total}`);
+
+        if (this.results.failed === 0) {
+            console.log(`\n🎉 All tests passed!`);
+        } else {
+            console.log(`\n❌ ${this.results.failed} test(s) failed.`);
+        }
+    }
+}
+
+// Create test runner
+const runner = new DocumentNavigatorTestRunner();
+
+// Test Suite: DocumentNavigator Widget
+runner.test('DocumentNavigator class should exist and be importable', async function() {
+    // This test will fail initially - we haven't created the class yet
+    try {
+        const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+        this.expect(DocumentNavigator).toBeTruthy();
+        this.expect(typeof DocumentNavigator).toBe('function');
+    } catch (error) {
+        throw new Error(`DocumentNavigator class not found: ${error.message}`);
+    }
+});
+
+runner.test('DocumentNavigator should extend UIWidget', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+    const { UIWidget } = await import('../widgets/base/UIWidget.js');
+
+    const navigator = new DocumentNavigator();
+    this.expect(navigator).toBeInstanceOf(UIWidget);
+});
+
+runner.test('DocumentNavigator should initialize with default configuration', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator();
+
+    // Test default configuration
+    this.expect(navigator.config.position).toBe('left');
+    this.expect(navigator.config.collapsed).toBe(true);
+    this.expect(navigator.config.autoHide).toBe(true);
+    this.expect(navigator.config.maxHeadingLevel).toBe(3);
+    this.expect(navigator.config.enableScrollSpy).toBe(true);
+});
+
+runner.test('DocumentNavigator should accept custom configuration', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const customConfig = {
+        position: 'right',
+        collapsed: false,
+        maxHeadingLevel: 4,
+        theme: 'dark'
+    };
+
+    const navigator = new DocumentNavigator(customConfig);
+
+    this.expect(navigator.config.position).toBe('right');
+    this.expect(navigator.config.collapsed).toBe(false);
+    this.expect(navigator.config.maxHeadingLevel).toBe(4);
+    this.expect(navigator.config.theme).toBe('dark');
+});
+
+runner.test('DocumentNavigator should render floating panel element', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator();
+    await navigator.render();
+
+    this.expect(navigator.element).toBeInstanceOf(HTMLElement);
+    this.expect(navigator.element.classList.contains('document-navigator')).toBeTruthy();
+    this.expect(navigator.element.style.position).toBe('fixed');
+});
+
+runner.test('DocumentNavigator should have toggle button in collapsed state', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator({ collapsed: true });
+    await navigator.render();
+
+    const toggleButton = navigator.findElement('.navigator-toggle');
+    this.expect(toggleButton).toBeInstanceOf(HTMLElement);
+    this.expect(toggleButton.style.display).not.toBe('none');
+
+    const navList = navigator.findElement('.navigator-list');
+    this.expect(navList.style.display).toBe('none');
+});
+
+runner.test('DocumentNavigator should extract headings from document', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    // Create test document with headings
+    const testContainer = document.createElement('div');
+    testContainer.innerHTML = `
+        <h1 id="heading1">First Heading</h1>
+        <p>Some content</p>
+        <h2 id="heading2">Second Heading</h2>
+        <h3 id="heading3">Third Heading</h3>
+        <p>More content</p>
+        <h2 id="heading4">Fourth Heading</h2>
+    `;
+    document.body.appendChild(testContainer);
+
+    const navigator = new DocumentNavigator({
+        container: testContainer,
+        maxHeadingLevel: 3
+    });
+
+    const headings = navigator.extractHeadings();
+
+    this.expect(headings).toHaveLength(4);
+    this.expect(headings[0].tagName).toBe('H1');
+    this.expect(headings[0].textContent).toBe('First Heading');
+    this.expect(headings[1].tagName).toBe('H2');
+    this.expect(headings[2].tagName).toBe('H3');
+    this.expect(headings[3].tagName).toBe('H2');
+
+    // Cleanup
+    document.body.removeChild(testContainer);
+});
+
+runner.test('DocumentNavigator should build navigation hierarchy', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    // Create test document with nested headings
+    const testContainer = document.createElement('div');
+    testContainer.innerHTML = `
+        <h1>Chapter 1</h1>
+        <h2>Section 1.1</h2>
+        <h3>Subsection 1.1.1</h3>
+        <h3>Subsection 1.1.2</h3>
+        <h2>Section 1.2</h2>
+        <h1>Chapter 2</h1>
+    `;
+    document.body.appendChild(testContainer);
+
+    const navigator = new DocumentNavigator({ container: testContainer });
+    await navigator.render();
+
+    const navItems = navigator.buildNavigationTree();
+
+    // Should have hierarchical structure
+    this.expect(navItems).toHaveLength(2); // 2 H1 elements
+    this.expect(navItems[0].children).toHaveLength(2); // 2 H2 under first H1
+    this.expect(navItems[0].children[0].children).toHaveLength(2); // 2 H3 under first H2
+
+    // Cleanup
+    document.body.removeChild(testContainer);
+});
+
+runner.test('DocumentNavigator should handle click navigation', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    // Create test document
+    const testContainer = document.createElement('div');
+    testContainer.innerHTML = `
+        <h1 id="target-heading">Target Heading</h1>
+        <p style="height: 1000px;">Spacer content</p>
+    `;
+    document.body.appendChild(testContainer);
+
+    const navigator = new DocumentNavigator({ container: testContainer });
+    await navigator.render();
+
+    // Simulate click on navigation item
+    const navItem = navigator.findElement('[data-target="target-heading"]');
+    this.expect(navItem).toBeTruthy();
+
+    // Mock scrollIntoView for testing
+    const targetElement = document.getElementById('target-heading');
+    let scrollCalled = false;
+    targetElement.scrollIntoView = () => { scrollCalled = true; };
+
+    // Click navigation item
+    navItem.click();
+
+    this.expect(scrollCalled).toBeTruthy();
+
+    // Cleanup
+    document.body.removeChild(testContainer);
+});
+
+runner.test('DocumentNavigator should support expand/collapse functionality', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator({ collapsed: true });
+    await navigator.render();
+
+    // Should start collapsed
+    this.expect(navigator.isCollapsed).toBeTruthy();
+
+    const toggleButton = navigator.findElement('.navigator-toggle');
+    const navList = navigator.findElement('.navigator-list');
+
+    // Toggle to expanded
+    await navigator.expand();
+    this.expect(navigator.isCollapsed).toBeFalsy();
+    this.expect(navList.style.display).not.toBe('none');
+
+    // Toggle back to collapsed
+    await navigator.collapse();
+    this.expect(navigator.isCollapsed).toBeTruthy();
+    this.expect(navList.style.display).toBe('none');
+});
+
+runner.test('DocumentNavigator should implement scroll spy functionality', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    // Create test document with multiple sections
+    const testContainer = document.createElement('div');
+    testContainer.innerHTML = `
+        <div style="height: 100px;"></div>
+        <h1 id="section1">Section 1</h1>
+        <div style="height: 400px;"></div>
+        <h2 id="section2">Section 2</h2>
+        <div style="height: 400px;"></div>
+        <h2 id="section3">Section 3</h2>
+        <div style="height: 400px;"></div>
+    `;
+    document.body.appendChild(testContainer);
+
+    const navigator = new DocumentNavigator({
+        container: testContainer,
+        enableScrollSpy: true
+    });
+    await navigator.render();
+
+    // Test current section detection
+    const currentSection = navigator.getCurrentSection();
+    this.expect(currentSection).toBeTruthy();
+
+    // Cleanup
+    document.body.removeChild(testContainer);
+});
+
+runner.test('DocumentNavigator should handle responsive behavior', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator({ autoHide: true });
+    await navigator.render();
+
+    // Mock viewport resize
+    const originalInnerWidth = window.innerWidth;
+
+    // Test mobile viewport
+    Object.defineProperty(window, 'innerWidth', { value: 500, configurable: true });
+    navigator.handleResize();
+    this.expect(navigator.element.style.display).toBe('none');
+
+    // Test desktop viewport
+    Object.defineProperty(window, 'innerWidth', { value: 1200, configurable: true });
+    navigator.handleResize();
+    this.expect(navigator.element.style.display).not.toBe('none');
+
+    // Restore original
+    Object.defineProperty(window, 'innerWidth', { value: originalInnerWidth, configurable: true });
+});
+
+runner.test('DocumentNavigator should provide keyboard navigation support', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator();
+    await navigator.render();
+
+    // Test keyboard shortcuts
+    let expandCalled = false;
+    let collapseCalled = false;
+
+    navigator.expand = async () => { expandCalled = true; };
+    navigator.collapse = async () => { collapseCalled = true; };
+
+    // Simulate keyboard events
+    const element = navigator.element;
+
+    // Test Escape key (should collapse)
+    const escapeEvent = new KeyboardEvent('keydown', { key: 'Escape' });
+    element.dispatchEvent(escapeEvent);
+    this.expect(collapseCalled).toBeTruthy();
+
+    // Test Enter/Space key (should expand)
+    const enterEvent = new KeyboardEvent('keydown', { key: 'Enter' });
+    element.dispatchEvent(enterEvent);
+    this.expect(expandCalled).toBeTruthy();
+});
+
+runner.test('DocumentNavigator should emit events for user interactions', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    const navigator = new DocumentNavigator();
+    await navigator.render();
+
+    // Test event emission
+    let navigationEvent = null;
+    navigator.addEventListener('navigate', (e) => {
+        navigationEvent = e;
+    });
+
+    let toggleEvent = null;
+    navigator.addEventListener('toggle', (e) => {
+        toggleEvent = e;
+    });
+
+    // Trigger navigation
+    navigator.navigateToHeading('test-heading');
+    this.expect(navigationEvent).toBeTruthy();
+    this.expect(navigationEvent.detail.target).toBe('test-heading');
+
+    // Trigger toggle
+    await navigator.toggle();
+    this.expect(toggleEvent).toBeTruthy();
+});
+
+runner.test('DocumentNavigator should handle empty document gracefully', async function() {
+    const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+
+    // Create empty container
+    const emptyContainer = document.createElement('div');
+    document.body.appendChild(emptyContainer);
+
+    const navigator = new DocumentNavigator({ container: emptyContainer });
+
+    const headings = navigator.extractHeadings();
+    this.expect(headings).toHaveLength(0);
+
+    await navigator.render();
+    const navList = navigator.findElement('.navigator-list');
+    this.expect(navList.children).toHaveLength(0);
+
+    // Should show empty state message
+    const emptyMessage = navigator.findElement('.navigator-empty');
+    this.expect(emptyMessage).toBeTruthy();
+
+    // Cleanup
+    document.body.removeChild(emptyContainer);
+});
+
+// Export test runner for use in HTML
+window.runDocumentNavigatorTests = () => runner.run();
+
+console.log('📋 DocumentNavigator TDD Test Suite loaded. Run with: runDocumentNavigatorTests()');
+
+export { runner };
--- a/package.json
+++ b/package.json
@@ -35,14 +35,14 @@
  "author": "MarkiTect Project",
  "license": "MIT",
  "devDependencies": {
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "@babel/core": "^7.23.0",
+    "@babel/preset-env": "^7.23.0",
+    "babel-jest": "^29.7.0",
    "eslint": "^8.57.0",
    "eslint-config-standard": "^17.1.0",
    "eslint-plugin-jest": "^27.6.0",
-    "@babel/preset-env": "^7.23.0",
-    "@babel/core": "^7.23.0",
-    "babel-jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0"
  },
  "dependencies": {
    "jsdom": "^23.0.0"
@@ -77,11 +77,14 @@
  },
  "babel": {
    "presets": [
-      ["@babel/preset-env", {
-        "targets": {
-          "node": "current"
+      [
+        "@babel/preset-env",
+        {
+          "targets": {
+            "node": "current"
+          }
        }
-      }]
+      ]
    ]
  },
  "eslintConfig": {
@@ -102,4 +105,4 @@
      "no-debugger": "error"
    }
  }
-}
+}