---
name: mainline-display
description: Display backend implementation and the Display protocol
compatibility: opencode
metadata:
  audience: developers
  source_type: codebase
---

## What This Skill Covers

This skill covers Mainline's display backend system - how to implement new display backends and how the Display protocol works.

## Key Concepts

### Display Protocol

All backends implement a common Display protocol (in `engine/display/__init__.py`):

```python
class Display(Protocol):
    width: int
    height: int
    
    def init(self, width: int, height: int, reuse: bool = False) -> None:
        """Initialize the display"""
        ...
    
    def show(self, buf: list[str], border: bool = False) -> None:
        """Display the buffer"""
        ...
    
    def clear(self) -> None:
        """Clear the display"""
        ...
    
    def cleanup(self) -> None:
        """Clean up resources"""
        ...
    
    def get_dimensions(self) -> tuple[int, int]:
        """Return (width, height)"""
        ...
```

### DisplayRegistry

Discovers and manages backends:

```python
from engine.display import DisplayRegistry
display = DisplayRegistry.create("terminal")  # or "websocket", "null", "multi"
```

### Available Backends

| Backend | File | Description |
|---------|------|-------------|
| terminal | backends/terminal.py | ANSI terminal output |
| websocket | backends/websocket.py | Web browser via WebSocket |
| null | backends/null.py | Headless for testing |
| multi | backends/multi.py | Forwards to multiple displays |
| moderngl | backends/moderngl.py | GPU-accelerated OpenGL rendering (optional) |

### WebSocket Backend

- WebSocket server: port 8765
- HTTP server: port 8766 (serves client/index.html)
- Client has ANSI color parsing and fullscreen support

### Multi Backend

Forwards to multiple displays simultaneously - useful for `terminal + websocket`.

## Adding a New Backend

1. Create `engine/display/backends/my_backend.py`
2. Implement the Display protocol methods
3. Register in `engine/display/__init__.py`'s `DisplayRegistry`

Required methods:
- `init(width: int, height: int, reuse: bool = False)` - Initialize display
- `show(buf: list[str], border: bool = False)` - Display buffer
- `clear()` - Clear screen
- `cleanup()` - Clean up resources
- `get_dimensions() -> tuple[int, int]` - Get terminal dimensions

Optional methods:
- `title(text: str)` - Set window title
- `cursor(show: bool)` - Control cursor

## Usage

```bash
python mainline.py --display terminal  # default
python mainline.py --display websocket
python mainline.py --display moderngl  # GPU-accelerated (requires moderngl)
```