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 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

# Complete setup (Python + JavaScript dependencies)
make testdrive-jsui-setup

# Check environment status
make testdrive-jsui-status

Testing

# 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

# 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

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:

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

# JavaScript
npm test -- --testNamePattern="specific test name"

# Python
pytest tests/test_specific.py -v

Debugging Tests

# Verbose JavaScript output
npm run test:verbose

# Python with debug output
pytest tests/ -v -s

Checking Test Coverage

# 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

# 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:

if engine.validate_mode('edit'):
    html = engine.render_document(content, 'edit', config)