# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview **TestDrive-JSUI is a JavaScript-first markdown editor library.** This is a pure JavaScript library for interactive markdown editing that works standalone in any browser. Language adapters (Python, Ruby, Java) are **optional integration helpers** - they do NOT provide core functionality. **Key Facts**: - **Core:** Complete JavaScript library (`js/testdrive-jsui.js`) - **Dependencies:** Only marked.js for markdown parsing - **Standalone:** Works without any backend (can run from file://) - **Optional Adapters:** Python/Ruby/Java adapters help with asset serving and backend integration - **Architecture:** JavaScript-first design (see `ARCHITECTURE.md`) ## JavaScript Library ### Quick Start ```html

``` ### API **Constructor Options:** - `container` (required): CSS selector or DOM element - `markdown`: Initial content - `mode`: 'edit' or 'view' (default: 'edit') - `theme`: Theme name (default: 'github') - `autosave`: Auto-save enabled (default: false) - `shortcuts`: Keyboard shortcuts (default: true) - `sections`: Section-based editing (default: true) - `debug`: Debug mode (default: false) **Methods:** - `getMarkdown()`: Get current content - `setMarkdown(markdown)`: Set content - `getStatus()`: Get editor status - `save()`: Trigger save event - `download(filename)`: Download as .md file - `on(event, callback)`: Listen to events - `destroy()`: Clean up **Events:** `initialized`, `save`, `content-changed`, `autosave`, `download`, `reset`, `destroyed` ### Examples See `/examples`: - `standalone.html` - Minimal proof of concept - `full-editor.html` - Complete demo with all features ## 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/ ├── js/ # JavaScript library (Core functionality) │ ├── testdrive-jsui.js # 🎯 Main library entry point │ ├── core/ # Core JS: debug-system, section-manager │ ├── components/ # UI components: dom-renderer, debug-panel, document-controls │ ├── controls/ # Control panels: edit, debug, status, contents │ ├── plugins/ # JS plugins │ ├── widgets/ # UI widgets │ ├── utils/ # JS utilities │ ├── tests/ # JavaScript tests (Jest) │ ├── config-loader.js # Configuration loader │ ├── main.js # Legacy main entry point │ └── main-updated.js # Refactored main entry ├── examples/ # 📚 Working examples │ ├── standalone.html # Minimal proof of concept │ └── full-editor.html # Complete demo ├── src/testdrive_jsui/ # Python adapter (optional) │ ├── core/ # Adapter core │ ├── components/ # Adapter helpers │ ├── utils/ # Utilities │ └── testing/ # Python-JS bridge │ ├── js_test_runner.py # JavaScript test execution │ └── integration.py # Pytest integration ├── static/ # Static assets │ ├── css/ # Stylesheets (editor, controls, themes) │ ├── images/ # Image assets and icons │ └── templates/ # HTML templates ├── tests/ # Python tests ├── docs/ # Documentation │ ├── prototypes/ # Archived HTML prototypes │ └── migration/ # Migration records ├── ARCHITECTURE.md # JavaScript-first architecture details └── README.md # Main documentation ``` ### Key Design Principles **JavaScript-First Architecture** (NEW in v1.0.0) - **Core functionality in JavaScript**: All UI logic, rendering, and editing in JS - **Standalone capable**: Works without any backend (can run from file://) - **marked.js only dependency**: For markdown parsing - **Language adapters optional**: Python/Ruby/Java are integration helpers, not functionality providers - **Event-driven API**: Clean event system for integration - **See `ARCHITECTURE.md`** for complete architectural documentation **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 adapters and JavaScript - **No code mixing**: JavaScript stays in `.js` files, never embedded in 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) ```