generated from coulomb/repo-seed
tegwick
7759f9e427
Created full-editor-standalone.html that embeds all JavaScript inline. This file can be copied anywhere and opened directly without needing any other files or dependencies (except marked.js from CDN). Perfect for distribution and testing. 🤖 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.