---
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):
    def show(self, buf: list[str]) -> None:
        """Display the buffer"""
        ...
    
    def clear(self) -> None:
        """Clear the display"""
        ...
    
    def size(self) -> tuple[int, int]:
        """Return (width, height)"""
        ...
```

### DisplayRegistry

Discovers and manages backends:

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

### Available Backends

| Backend | File | Description |
|---------|------|-------------|
| terminal | backends/terminal.py | ANSI terminal output |
| websocket | backends/websocket.py | Web browser via WebSocket |
| sixel | backends/sixel.py | Sixel graphics (pure Python) |
| null | backends/null.py | Headless for testing |
| multi | backends/multi.py | Forwards to multiple displays |

### 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:
- `show(buf: list[str])` - Display buffer
- `clear()` - Clear screen
- `size() -> tuple[int, int]` - 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 sixel
python mainline.py --display both      # terminal + websocket
```