markitect-main/docs/PLUGIN_SYSTEM.md

# Markitect Plugin System Documentation

## Overview

The Markitect plugin system provides a modular architecture for extending rendering capabilities with independent JavaScript UI components. This system enables JavaScript-first development while maintaining clean integration with the Python ecosystem.

## Architecture

### Core Components

1. **RenderingEnginePlugin**: Base class for UI rendering engines
2. **RenderingConfig**: Asset management and deployment configuration
3. **RenderingEngineManager**: Plugin discovery and lifecycle management
4. **PluginManager**: Integration with existing Markitect plugin system

### Key Features

- **Clean Separation**: JSON-based configuration interface (Python ↔ JavaScript)
- **Independent Development**: JavaScript components work standalone
- **Asset Management**: Configurable deployment strategies
- **Multiple Engines**: Support for different UI frameworks
- **Fallback Support**: Graceful degradation to standard rendering

## Plugin Development

### Creating a Rendering Engine Plugin

1. **Extend RenderingEnginePlugin**:

```python
from markitect.plugins.rendering import RenderingEnginePlugin, RenderingConfig
from markitect.plugins.base import PluginMetadata, PluginType

class MyUIEngine(RenderingEnginePlugin):
    def __init__(self):
        super().__init__()
        self._metadata = PluginMetadata(
            name="my-ui-engine",
            version="1.0.0",
            description="Custom UI rendering engine",
            author="Your Name",
            plugin_type=PluginType.RENDERING
        )

    @property
    def metadata(self) -> PluginMetadata:
        return self._metadata

    def get_supported_modes(self) -> List[str]:
        return ["edit", "view"]

    def get_required_assets(self) -> Dict[str, List[str]]:
        return {
            "js": ["static/js/main.js"],
            "css": ["static/css/style.css"]
        }

    def render_document(self, content: str, mode: str, config: RenderingConfig) -> str:
        # Your rendering logic here
        return html_output
```

2. **Directory Structure**:

```
my-ui-engine/
├── static/
│   ├── js/           # JavaScript components
│   └── css/          # Stylesheets
├── templates/        # HTML templates
├── images/           # Icons and images
├── test-documents/   # Sample markdown files
├── package.json      # Node.js configuration
└── README.md         # Plugin documentation
```

3. **Asset Management**:

Assets are automatically deployed based on configuration:
- **Development**: Served from plugin source directory
- **Production**: Copied to `_markitect/plugins/{plugin-name}/`

## TestDrive JSUI Plugin

### Overview

The TestDrive JSUI plugin demonstrates the plugin architecture with a complete JavaScript UI for markdown editing.

### Features

- **Modular Components**: Clean separation of UI components
- **Compass Positioning**: NW, NE, E, SE control panel layout
- **Section Management**: Click-to-edit markdown sections
- **Debug System**: Built-in debugging and logging
- **Asset Pipeline**: Configurable asset deployment

### Directory Structure

```
testdrive-jsui/
├── static/js/
│   ├── core/             # Core systems
│   │   ├── debug-system.js
│   │   └── section-manager.js
│   ├── components/       # UI components
│   │   ├── debug-panel.js
│   │   ├── document-controls.js
│   │   └── dom-renderer.js
│   ├── controls/         # Control panels
│   │   ├── control-base.js
│   │   ├── contents-control.js   # Northwest
│   │   ├── status-control.js     # East
│   │   ├── debug-control.js      # Southeast
│   │   └── edit-control.js       # Northeast
│   ├── config-loader.js  # Configuration interface
│   └── main-updated.js   # Application entry point
├── static/css/           # Stylesheets (future)
├── images/               # Icons and images (future)
├── templates/
│   └── index.html        # Main HTML template
├── test-documents/
│   └── sample.md         # Test content
├── test.html             # Standalone development
├── package.json          # Node.js configuration
└── README.md             # Plugin documentation
```

### JavaScript Architecture

- **Configuration Interface**: Clean JSON data transfer via `markitect-config` script element
- **Modular Components**: Each component has single responsibility
- **Event System**: Pub/sub for component communication
- **Control System**: Abstract base class for UI controls
- **Compass Positioning**: Consistent control panel layout

## CLI Integration

### Command Line Usage

```bash
# Use default engine (testdrive-jsui for edit/insert, standard for view)
markitect md-render --edit document.md

# Specify engine explicitly
markitect md-render --engine testdrive-jsui --edit document.md

# Use standard engine
markitect md-render --engine standard --edit document.md

# View available engines
markitect md-render --help
```

### Engine Selection Logic

1. **Default Selection**:
   - Edit/Insert modes: `testdrive-jsui`
   - View mode: `standard`

2. **Explicit Selection**: Use `--engine` parameter

3. **Fallback Strategy**:
   - Engine not found → fallback to standard
   - Mode not supported → fallback to standard
   - Plugin error → fallback to standard

### Integration Points

The CLI integrates with the plugin system through:

```python
# Engine discovery
plugin_manager = PluginManager()
rendering_manager = RenderingEngineManager(plugin_manager)

# Engine selection
engine = rendering_manager.get_engine(engine_name)

# Configuration
config = RenderingConfig(
    asset_base_url="_markitect",
    development_mode=False,
    output_directory=output_path.parent
)

# Rendering
html_content = engine.render_document(content, mode, config)
```

## Development Workflows

### Standalone JavaScript Development

1. **Setup**:
   ```bash
   cd testdrive-jsui
   python -m http.server 8080
   ```

2. **Development**:
   - Edit JavaScript files in `static/js/`
   - Refresh browser to see changes
   - Use `test.html` for testing
   - Browser DevTools for debugging

3. **Benefits**:
   - No Python environment required
   - Fast iteration cycle
   - Standard web development tools
   - Hot reloading

### Integrated Development

1. **Plugin Testing**:
   ```bash
   python demo_plugin_integration.py
   ```

2. **CLI Testing**:
   ```bash
   markitect md-render --engine testdrive-jsui --edit test.md
   ```

3. **Integration Verification**:
   ```bash
   python test_complete_integration.py
   ```

## Asset Management

### Development Mode

```python
config = RenderingConfig(
    asset_base_url=".",
    development_mode=True,
    plugin_source_dirs={"testdrive-jsui": Path("testdrive-jsui")}
)

# Assets served as: file://testdrive-jsui/static/js/main.js
```

### Production Mode

```python
config = RenderingConfig(
    asset_base_url="_markitect",
    development_mode=False,
    output_directory=Path("/output")
)

# Assets served as: _markitect/plugins/testdrive-jsui/static/js/main.js
```

### Asset Types

- **js**: JavaScript files
- **css**: Stylesheets
- **images**: Icons, graphics
- **external**: CDN resources

### Deployment Strategy

1. **Assets Copying**: Plugin assets copied to `_markitect/plugins/{name}/`
2. **URL Generation**: Automatic URL generation for templates
3. **Cache Management**: Asset versioning and cache control
4. **Error Handling**: Fallback for missing assets

### Asset Deployment Process

When using CLI with plugin engines, assets are automatically deployed:

```bash
# Assets are deployed to output directory when using plugin engines
markitect md-render --edit document.md --output /path/to/output.html

# Output structure:
# /path/to/
# ├── output.html
# └── _markitect/
#     └── plugins/
#         └── testdrive-jsui/
#             ├── static/
#             │   ├── js/          # 12 JavaScript files
#             │   └── css/         # 3 CSS files
#             └── images/          # 3 image files
```

The deployment process:

1. **Plugin Discovery**: Engine identified (default: testdrive-jsui for edit mode)
2. **Asset Analysis**: Required assets determined from `get_required_assets()`
3. **Source Resolution**: Plugin source directory located
4. **File Copying**: Assets copied with directory structure preservation
5. **URL Generation**: HTML references generated with correct paths
6. **Verification**: Asset accessibility validated

Example output:
```
🎯 Using rendering engine: testdrive-jsui (supports: edit, view)
📦 Deploying assets for engine 'testdrive-jsui'...
📄 Deployed 18 asset files
   js: 12 files
   css: 3 files
   images: 3 files
✅ Rendered with INTERACTIVE editing mode to: output.html
```

## Configuration Interface

### Python → JavaScript Data Transfer

All dynamic data passes through a clean JSON interface:

```html
<script id="markitect-config" type="application/json">
{
  "markdownContent": "# Document content...",
  "mode": "edit",
  "theme": "github",
  "keyboardShortcuts": true,
  "originalFilename": "document.md",
  "version": "Markitect v0.8.1"
}
</script>
```

### JavaScript Configuration Loading

```javascript
// Clean configuration loading
class MarkitectConfig {
    constructor() {
        this.loadConfig();
    }

    loadConfig() {
        const configElement = document.getElementById('markitect-config');
        this.config = JSON.parse(configElement.textContent);
    }
}
```

### Benefits

- **No String Interpolation**: Prevents template literal escaping issues
- **Type Safety**: JSON validation and error handling
- **Clean Separation**: No JavaScript code in Python strings
- **Debuggable**: Easy to inspect configuration in browser

## Testing

### Plugin Testing

```bash
# Basic plugin discovery
python test_plugin_discovery.py

# CLI integration logic
python test_cli_simple.py

# Complete scenario testing
python test_complete_integration.py

# Full integration demo
python demo_plugin_integration.py
```

### Browser Testing

1. **Standalone**: Open `testdrive-jsui/test.html`
2. **Generated**: Open CLI-generated HTML files
3. **DevTools**: Use browser debugging tools
4. **Console**: Check for JavaScript errors

### Integration Testing

- **Unit Tests**: Individual component testing
- **Integration Tests**: Component interaction testing
- **E2E Tests**: Full workflow testing
- **Regression Tests**: Ensure stability across changes

## Extension Points

### Adding New Engines

1. Create new plugin extending `RenderingEnginePlugin`
2. Implement required methods (`get_supported_modes`, `render_document`, etc.)
3. Register in `RenderingEngineManager._register_builtin_rendering_engines()`
4. Test with CLI integration

### Adding New Modes

1. Add mode to engine's `get_supported_modes()`
2. Update `render_document()` to handle new mode
3. Test mode validation and rendering
4. Update CLI integration if needed

### Adding New Asset Types

1. Update `get_required_assets()` return format
2. Modify asset deployment logic in `RenderingConfig`
3. Update template system to handle new asset types
4. Test asset URL generation

## Best Practices

### Plugin Development

- **Single Responsibility**: Each component has one clear purpose
- **Clean Interfaces**: Well-defined APIs between components
- **Error Handling**: Graceful degradation on failures
- **Documentation**: Clear README and code comments

### JavaScript Development

- **Modular Architecture**: Avoid monolithic JavaScript files
- **Event-Driven**: Use pub/sub for component communication
- **Configuration-Driven**: Avoid hardcoded values
- **Browser Compatibility**: Test across different browsers

### Asset Management

- **Relative Paths**: Use relative paths in asset definitions
- **Versioning**: Include version info for cache management
- **Optimization**: Minimize asset size for production
- **CDN Integration**: Use CDN for external dependencies

### Testing Strategy

- **Automated Testing**: Comprehensive test coverage
- **Manual Testing**: User workflow validation
- **Cross-Platform**: Test on different environments
- **Performance Testing**: Monitor rendering performance

## Troubleshooting

### Common Issues

1. **Plugin Not Found**:
   - Check plugin registration in `_register_builtin_rendering_engines()`
   - Verify plugin class inheritance from `RenderingEnginePlugin`
   - Check import paths and module availability

2. **Asset Loading Errors**:
   - Verify asset paths in `get_required_assets()`
   - Check file permissions and existence
   - Validate URL generation in different modes

3. **Configuration Errors**:
   - Check JSON syntax in configuration
   - Verify configuration element ID (`markitect-config`)
   - Test configuration loading in JavaScript

4. **Rendering Failures**:
   - Check template file existence and permissions
   - Verify template placeholder replacement
   - Test with minimal content for debugging

### Debug Techniques

- **Console Logging**: Use browser console for debugging
- **Debug Panel**: TestDrive JSUI includes debug information
- **Verbose Mode**: Use CLI `--verbose` flag for detailed output
- **Test Scripts**: Run individual test scripts for isolation

## Future Enhancements

### Planned Features

- **Plugin Package Manager**: npm-like plugin distribution
- **Theme System Integration**: Plugin-aware theme system
- **Performance Monitoring**: Built-in performance tracking
- **Hot Reloading**: Automatic reload on file changes

### Extension Opportunities

- **React Integration**: React-based rendering engine
- **Vue Integration**: Vue.js-based rendering engine
- **TypeScript Support**: TypeScript plugin development
- **Testing Framework**: Automated JavaScript testing

### Community

- **Plugin Registry**: Central repository for community plugins
- **Documentation**: Expanded examples and tutorials
- **Templates**: Starter templates for new plugins
- **Best Practices**: Community guidelines and patterns

---

*This plugin system enables JavaScript-first development while maintaining clean integration with the MarkiTect Python ecosystem, providing the best of both worlds for UI development and backend processing.*