sideline/.opencode/skills/mainline-display/SKILL.md at 6d2c5ba304efb91fb1417c4f23dfb63005f6d34c

Files

David Gwilliam b926b346ad fix: resolve terminal display wobble and effect dimension stability

- Fix TerminalDisplay: add screen clear each frame (cursor home + erase down)
- Fix CameraStage: use set_canvas_size instead of read-only viewport properties
- Fix Glitch effect: preserve visible line lengths, remove cursor positioning
- Fix Fade effect: return original line when fade=0 instead of empty string
- Fix Noise effect: use input line length instead of terminal_width
- Remove HUD effect from all presets (redundant with border FPS display)
- Add regression tests for effect dimension stability
- Add docs/ARCHITECTURE.md with Mermaid diagrams
- Add mise tasks: diagram-ascii, diagram-validate, diagram-check
- Move markdown docs to docs/ (ARCHITECTURE, Refactor, hardware specs)
- Remove redundant requirements files (use pyproject.toml)
- Add *.dot and *.png to .gitignore

Closes #25

2026-03-18 03:37:53 -07:00

2.2 KiB

Raw Blame History

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):
    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:

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

Create engine/display/backends/my_backend.py
Implement the Display protocol methods
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

python mainline.py --display terminal  # default
python mainline.py --display websocket
python mainline.py --display sixel
python mainline.py --display both      # terminal + websocket

2.2 KiB Raw Blame History