testdrive-jsui/CLAUDE.md

# 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 FULLY COMPLETE - ALL PHASES**

This capability migration is now **fully complete** including cleanup. The main MarkiTect application exclusively uses the capability location, and legacy files have been removed.

**Current Status**: ✅ Phase 4 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 ✅
- **Legacy files removed** - cleanup complete ✅

**Key Facts**:
- **Main app status**: Fully migrated to capability location
- **Original files**: **REMOVED** from `/markitect/static/js/` (Phase 4 cleanup)
- **Single source of truth**: All JavaScript in `/capabilities/testdrive-jsui/js/`
- **Testing**: All rendering modes work correctly
- **Migration**: Fully complete - no further phases needed

**Documentation**: See `MIGRATION_STATUS.md` for complete migration details, all phases, and final verification results.

## 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**: ✅ ALL PHASES COMPLETE - See `MIGRATION_STATUS.md` for full details

The capability followed 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** ✅ COMPLETE (December 16, 2025)
1. ✅ Remove original files (29 files deleted)
2. ✅ Update documentation references
3. ✅ Archive migration records
4. ✅ Tag final migration commit

**Final State**: Migration **fully complete**. Main app exclusively uses capability location. Legacy files removed. Single source of truth: `/capabilities/testdrive-jsui/js/`. All tests passing. See `MIGRATION_STATUS.md` for complete history.

## 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)
```