markitect-main/testdrive-jsui/README.md

TestDrive JSUI Plugin

Independent JavaScript UI plugin for Markitect markdown editing. Designed for standalone development and testing of JavaScript components without requiring the full Python Markitect environment.

Features

• Independent Development: Work on UI components without Python setup
• Clean Architecture: JSON-based configuration interface
• Modular Components: Compass-positioned control panels
• Real-time Editing: Click any section to edit inline
• Asset Management: Proper separation of JS/CSS/image assets

Directory Structure

testdrive-jsui/
├── static/
│   ├── js/           # JavaScript components
│   │   ├── core/     # Core systems (debug, sections)
│   │   ├── components/  # UI components (panels, controls)
│   │   └── controls/ # Control panels (contents, status, edit, debug)
│   └── css/          # Stylesheets
├── images/           # Icons and images
├── templates/        # HTML templates
├── test-documents/   # Sample markdown files
└── package.json      # Node.js configuration

Development Setup

Standalone Development (No Python Required)

1. Start Development Server:

   cd testdrive-jsui
   npm run dev
   # or use Python's built-in server:
   python -m http.server 8080
   

2. Open Test Document: Navigate to http://localhost:8080/test.html to see the UI in action.

3. Edit JavaScript:

   • Modify files in static/js/
   • Refresh browser to see changes
   • Use browser DevTools for debugging

Integration with Markitect

The plugin integrates with Markitect through the rendering engine system:

# Use with Markitect (when integrated)
markitect md-render --engine testdrive-jsui --mode edit document.md

JavaScript Architecture

Core Components

• main.js: Application entry point and initialization
• config-loader.js: Configuration interface (Python ↔ JavaScript)
• section-manager.js: Document section management
• dom-renderer.js: DOM manipulation and rendering

Control Panels (Compass Positioning)

• Northwest: Contents/Navigation control
• Northeast: Edit actions control
• East: Status display control
• Southeast: Debug information control

Configuration Interface

All Python data passes through a clean JSON interface:

<script id="markitect-config" type="application/json">
{
  "markdownContent": "# Document content...",
  "mode": "edit",
  "theme": "github",
  ...
}
</script>

Testing

Manual Testing

1. Load test.html in browser
2. Verify all controls load and position correctly
3. Test editing functionality
4. Check browser console for errors

Automated Testing (Future)

• Unit tests for JavaScript components
• Integration tests for HTML rendering
• Browser automation tests

Asset Management

Development Mode

• Assets served directly from static/ directory
• Hot reloading with development server
• No build process required

Production Mode

• Assets copied to _markitect/plugins/testdrive-jsui/
• Integrated with Markitect deployment
• Configurable asset URLs

Configuration

The plugin supports various configuration options:

{
  "pluginName": "testdrive-jsui",
  "assetBaseUrl": "_markitect",
  "developmentMode": true,
  "pluginAssetDir": "_markitect/plugins/testdrive-jsui"
}

Extending the Plugin

Adding New Controls

1. Create new control in ../capabilities/testdrive-jsui/js/controls/
2. Extend ControlBase class
3. Register in main.js initialization
4. Add compass position (nw, ne, e, se, s, sw, w, nw)

Adding New Themes

1. Create CSS file in static/css/themes/
2. Update theme selection logic
3. Test with different markdown content

Adding New Assets

1. Add files to appropriate static/ subdirectory
2. Update get_required_assets() in plugin class
3. Reference in templates or JavaScript

Integration Points

The plugin interfaces with Markitect through:

1. Plugin Registry: Auto-discovery of rendering engines
2. Asset Management: Deployment and URL generation
3. Configuration: JSON-based data transfer
4. Templates: HTML template system

License

MIT License - see LICENSE file for details.