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**:
   ```bash
   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:

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

```html
<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:

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

## Extending the Plugin

### Adding New Controls
1. Create new control in `static/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.