sideline/.opencode/skills/mainline-display/SKILL.md

name, description, compatibility, metadata

name	description	compatibility	metadata
mainline-display	Display backend implementation and the Display protocol	opencode	audience source_type developers 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):

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:

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

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