generated from coulomb/repo-seed
tegwick
796c04709a
Completed Phase 1 refactoring to JavaScript-first architecture: Core Library Implementation: - Created js/testdrive-jsui.js main library class - Integrated all existing components (SectionManager, DOMRenderer, DocumentControls) - Added marked.js integration for markdown rendering - Implemented event-driven API (on/off/emit) - Support for edit/view modes and themes - LocalStorage save/load functionality - Download as markdown file - Keyboard shortcuts (Ctrl+S, Escape) - Auto-save capability (optional) Examples: - examples/full-editor.html - Complete demo with all features - Updated examples/README.md with full documentation Documentation: - Updated README.md with JavaScript-first architecture section - Added complete API reference (constructor, methods, events) - Updated CLAUDE.md with library quick start and API - Emphasized JavaScript-first design principles Architecture: - JavaScript provides ALL functionality - Language adapters are optional integration helpers - Works standalone in browser (no backend required) - Clean separation: JS (functionality) vs Adapters (integration) This completes the architectural shift documented in ARCHITECTURE.md and JS_FIRST_REFACTORING.md Phase 1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
TestDrive-JSUI
A JavaScript-first markdown editor and UI library.
TestDrive-JSUI is a pure JavaScript library for interactive markdown editing with section-based management. Language adapters (Python, Ruby, Java) are optional integration helpers for serving assets and backend integration - they do not provide core functionality.
🎯 Purpose
TestDrive-JSUI is designed to:
- 📝 Provide a complete JavaScript library for interactive markdown editing
- 🌐 Work standalone in any browser without backend requirements
- 🔌 Offer optional language adapters for Python, Ruby, Java, etc.
- ✂️ Enable section-based editing with independent section management
- 🎨 Support multiple modes (edit/view) and themes
- 💾 Handle content persistence (localStorage, download, custom backends)
- 🧪 Include comprehensive testing for JavaScript and integrations
- 🚀 Support extensibility through events and configuration
🏛️ Architecture: JavaScript-First Design
TestDrive-JSUI follows a JavaScript-first architecture:
┌─────────────────────────────────────┐
│ Core: JavaScript Library │
│ - All functionality in JS │
│ - Works standalone in browser │
│ - No backend required │
│ - Uses marked.js for markdown │
└─────────────────────────────────────┘
↑ ↑ ↑
│ │ │
┌──────────┴──┐ ┌───┴────┐ ┌──┴──────┐
│ Python │ │ Ruby │ │ Java │
│ Adapter │ │ Adapter│ │ Adapter │
│ (optional) │ │(future)│ │(future) │
└─────────────┘ └────────┘ └─────────┘
Key Principle: JavaScript provides ALL functionality. Language adapters only help with:
- Asset serving
- Configuration injection
- Backend integration (storage, auth, etc.)
- Testing infrastructure
Quick Start: JavaScript Library
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script src="testdrive-jsui.js"></script>
</head>
<body>
<div id="editor"></div>
<script>
const editor = new TestDriveJSUI({
container: '#editor',
markdown: '# Hello World\n\nEdit me!',
mode: 'edit',
theme: 'github'
});
// Listen to events
editor.on('save', (data) => {
console.log('Saved:', data.markdown);
});
</script>
</body>
</html>
API Reference
Constructor Options
new TestDriveJSUI({
container: '#editor', // CSS selector or DOM element (required)
markdown: '# Content', // Initial markdown content
mode: 'edit', // 'edit' or 'view' (default: 'edit')
theme: 'github', // Theme name (default: 'github')
autosave: false, // Auto-save to localStorage (default: false)
shortcuts: true, // Keyboard shortcuts (default: true)
sections: true, // Section-based editing (default: true)
debug: false // Debug mode (default: false)
})
Methods
| Method | Description |
|---|---|
getMarkdown() |
Get current document content |
setMarkdown(markdown) |
Set document content |
getStatus() |
Get editor status (sections, words, etc.) |
save() |
Trigger save event |
download(filename) |
Download as markdown file |
loadFromLocalStorage() |
Load from browser storage |
saveToLocalStorage() |
Save to browser storage |
resetAll() |
Reset all sections to original content |
destroy() |
Clean up and destroy editor |
on(event, callback) |
Listen to events |
off(event, callback) |
Remove event listener |
Events
| Event | Data | Description |
|---|---|---|
initialized |
{mode, theme, sections} |
Editor finished initializing |
save |
{markdown} |
Save triggered |
content-changed |
{markdown} |
Content modified |
autosave |
{markdown} |
Auto-save occurred |
download |
{filename, markdown} |
Document downloaded |
reset |
{} |
Document reset |
destroyed |
{} |
Editor destroyed |
Examples
See the /examples directory for:
standalone.html- Minimal proof of concept (works from file://)full-editor.html- Complete demo with all features
🐍 Python Adapter (Optional)
For Python projects, TestDrive-JSUI provides an optional adapter for integration:
🏗️ Architecture
capabilities/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 # Main entry point
│ └── main-updated.js # Updated main (refactored)
├── static/ # Static assets
│ ├── css/ # Stylesheets
│ │ ├── editor.css # Editor styles
│ │ ├── controls.css # Control panel styles
│ │ └── themes/ # Theme files
│ ├── images/ # Image assets
│ │ └── icons/ # UI icons
│ └── templates/ # HTML templates
│ └── index.html # Main template
├── tests/ # Python tests
├── Makefile # Capability commands
├── pyproject.toml # Python package config
├── package.json # JavaScript dependencies
└── README.md # This file
Key Design Principles:
- Single Source of Truth: All assets in one capability directory
- Self-Declaration: Plugin declares its own paths (no hardcoded discovery)
- Clean Boundaries: JSON config interface between Python and JavaScript
- No Code Mixing: JavaScript stays in
.jsfiles, never embedded in Python - Plugin Independence: Can be moved/installed anywhere
🚀 Quick Start
Prerequisites
- Python 3.8+ with pip
- Node.js 16+ with npm (optional, for JavaScript testing)
Standalone Installation
TestDrive-JSUI can be used completely independently of MarkiTect:
# Clone or copy this directory
git clone <repo-url> testdrive-jsui
cd testdrive-jsui
# Install Python package in development mode
pip install -e .
# (Optional) Install JavaScript dependencies for testing
npm install
Integration with MarkiTect
If using within the MarkiTect project:
# Navigate to the capability directory
cd capabilities/testdrive-jsui
# Quick setup (installs everything)
make testdrive-jsui-quickstart
# Or step by step:
make testdrive-jsui-setup # Install all dependencies
make testdrive-jsui-status # Check environment
make testdrive-jsui-test-all # Run all tests
📦 Standalone Usage
As a Rendering Engine Plugin
TestDrive-JSUI implements a plugin interface that allows it to be used independently:
from pathlib import Path
from testdrive_jsui import TestDriveJSUIEngine
# Create engine instance
engine = TestDriveJSUIEngine()
# The engine declares its own location - no hardcoded paths!
source_dir = engine.get_plugin_source_dir()
print(f"Plugin located at: {source_dir}")
# Get organized asset paths
asset_paths = engine.get_asset_paths()
# Returns: {'js': Path(...), 'css': Path(...), 'images': Path(...), 'templates': Path(...)}
# Get required assets list
assets = engine.get_required_assets()
# Returns: {'js': [...], 'css': [...], 'images': [...], 'external': [...]}
Rendering Documents
Use the engine to render markdown content with an interactive JavaScript UI:
from testdrive_jsui import TestDriveJSUIEngine
from markitect.plugins.rendering import RenderingConfig
from pathlib import Path
# Create engine
engine = TestDriveJSUIEngine()
# Configure for development (serves from source)
config = RenderingConfig(
asset_base_url='.',
development_mode=True,
plugin_source_dirs={'testdrive-jsui': engine.get_plugin_source_dir()}
)
# Render markdown content
markdown_content = """
# My Document
This is a test of the **TestDrive-JSUI** rendering engine.
## Features
- Interactive editing
- Section management
- Debug controls
"""
html = engine.render_document(markdown_content, 'edit', config)
# Save to file
Path('output.html').write_text(html)
print("✅ Rendered to output.html")
Production Deployment
For production, deploy assets to a static directory:
from testdrive_jsui import TestDriveJSUIEngine
from markitect.plugins.rendering import RenderingConfig
from pathlib import Path
engine = TestDriveJSUIEngine()
# Configure for production
config = RenderingConfig(
asset_base_url='/_static',
development_mode=False,
output_directory=Path('./dist')
)
# Assets will be copied to: dist/_static/plugins/testdrive-jsui/
html = engine.render_document(content, 'view', config)
Plugin Independence
TestDrive-JSUI is designed to be fully independent:
- ✅ Self-contained: All assets in one directory
- ✅ Self-declaring: Plugin declares its own location
- ✅ No hardcoded paths: Works regardless of installation location
- ✅ Clean interface: Pure JSON configuration boundary
- ✅ No JavaScript in Python: All JS in separate files
- ✅ Reusable: Can be used in any Python project
Supported Modes
# Check supported rendering modes
modes = engine.get_supported_modes()
# Returns: ['edit', 'view']
# Validate a mode
if engine.validate_mode('edit'):
html = engine.render_document(content, 'edit', config)
🧪 Testing
JavaScript Tests
# Run JavaScript tests only
make testdrive-jsui-test-js
# Run with coverage
npm run test:coverage
# Watch mode for development
make testdrive-jsui-watch
Python Integration Tests
# Run Python tests only
make testdrive-jsui-test-python
# Run integration tests
make testdrive-jsui-test-integration
# Run all tests
make testdrive-jsui-test-all
Main Project Integration
From the main MarkiTect project:
# Run capability tests
make testdrive-jsui-test-all
# Include in main test suite
make test-all # (when integrated)
📋 Available Commands
| Command | Description |
|---|---|
make testdrive-jsui-help |
Show all available commands |
make testdrive-jsui-status |
Check environment status |
make testdrive-jsui-setup |
Install all dependencies |
make testdrive-jsui-test-all |
Run all tests |
make testdrive-jsui-watch |
Development watch mode |
make testdrive-jsui-clean |
Clean build artifacts |
🔧 Development
Adding JavaScript Tests
-
Create test files in
js/tests/:// js/tests/test-my-component.js describe('MyComponent', () => { test('should do something', () => { // Your test here }); }); -
Run tests:
make testdrive-jsui-test-js
Adding Python Integration Tests
-
Create test files in
tests/:# tests/test_my_integration.py import pytest from testdrive_jsui.testing import JavaScriptTestRunner @pytest.mark.javascript def test_my_js_component(): runner = JavaScriptTestRunner() result = runner.run_specific_test('test-my-component.js') assert result.success -
Run tests:
make testdrive-jsui-test-integration
Code Quality
# Lint JavaScript
make testdrive-jsui-lint-js
# Lint Python
make testdrive-jsui-lint-python
# Format Python code
make testdrive-jsui-format-python
🔗 Integration with Main Project
Python Test Suite Integration
The capability provides pytest integration to run JavaScript tests from Python:
# In main project tests
from testdrive_jsui.testing import JavaScriptTestRunner
def test_javascript_ui_components():
runner = JavaScriptTestRunner()
result = runner.run_js_tests()
assert result.success
assert result.tests_passed > 0
Capability System Integration
The capability integrates with MarkiTect's capability discovery system:
# From main project
make capabilities-list # Shows testdrive-jsui
make testdrive-jsui-test-all # Direct delegation
make capabilities-test # Includes JS tests
📊 Testing Framework Features
JavaScript Test Runner
- Jest integration with JSDOM environment
- Coverage reporting with detailed metrics
- Test isolation with proper setup/teardown
- Mock support for DOM APIs and browser features
- Async testing support for modern JavaScript
Python-JavaScript Bridge
- Subprocess execution of JavaScript tests
- Result parsing with structured output
- Error handling with detailed failure information
- Test discovery for pytest integration
- Coverage integration between Python and JavaScript
Safety Mechanisms
- Copy-first migration (never move, always copy)
- Dual-track testing during migration
- Gradual integration with rollback options
- Test verification at each step
- Environment validation before execution
🔄 Migration Strategy
When migrating JavaScript UI code to this capability:
- Copy (don't move) JavaScript files to
js/directory - Verify tests work in new location
- Create Python integration tests
- Run dual-track testing to compare results
- Gradually switch to capability-based testing
- Remove original files only after full verification
📚 Examples
Running Specific Tests
# Run a specific JavaScript test
npm test -- --testNamePattern="SectionManager"
# Run specific Python integration test
pytest tests/test_section_manager_integration.py -v
# Run tests with coverage
npm run test:coverage
Environment Information
# Get detailed environment info
make testdrive-jsui-info
# Check what tests are available
make testdrive-jsui-status
Development Workflow
# Start development session
make testdrive-jsui-watch # Terminal 1: Watch JS tests
make testdrive-jsui-test-python # Terminal 2: Run Python tests
# Before committing
make testdrive-jsui-lint-js # Lint JavaScript
make testdrive-jsui-format-python # Format Python
make testdrive-jsui-test-all # Run all tests
🎯 Future Enhancements
- Visual regression testing with screenshot comparison
- Performance benchmarking for JavaScript components
- Browser automation with Selenium/Playwright
- Component documentation auto-generation
- Real browser testing in CI/CD pipelines
📋 Troubleshooting
Common Issues
Node.js not found:
# Install Node.js first
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
Tests failing:
# Check environment
make testdrive-jsui-status
# Reinstall dependencies
make testdrive-jsui-clean
make testdrive-jsui-setup
Integration issues:
# Verify Python package is installed
pip list | grep testdrive-jsui
# Check JavaScript dependencies
npm list
📄 License
MIT License - See main MarkiTect project for details.
Version: 1.0.0 Status: Full JavaScript Library Implementation Complete ✅ Architecture: JavaScript-First with Optional Language Adapters Last Updated: 2025-12-16
See /examples for working demos and ARCHITECTURE.md for detailed design documentation.