1

ADR 004 Display Protocol Pattern

David Gwilliam edited this page 2026-03-17 23:35:33 -07:00

Table of Contents

• ADR-004: Display Protocol Pattern
• Context
• Decision
• Consequences
• References

ADR-004: Display Protocol Pattern

Date: March 2026 Status: Accepted

Context

Different display targets (terminal, browser, pygame) needed unified interface. Hard to add new backends.

Decision

Display protocol with common interface:

class Display(Protocol):
    def setup(self, width: int, height: int) -> None: ...
    def draw(self, buf: Buffer) -> None: ...
    def refresh(self) -> None: ...
    def cleanup(self) -> None: ...

DisplayRegistry auto-discovers backends from engine/display/backends/:

• terminal.py: ANSI escape sequences
• websocket.py: HTML5 Canvas broadcast
• sixel.py: Sixel graphics
• kitty.py: Kitty protocol
• pygame.py: Pygame window
• null.py: Headless (testing)
• multi.py: Forward to multiple backends

Consequences

• Positive: Add new backend by implementing protocol
• Positive: MultiDisplay enables simultaneous outputs
• Positive: NullDisplay enables headless testing

References

• engine/display/__init__.py: Display, DisplayRegistry
• engine/display/backends/: Backend implementations