#+TITLE: cl-tty Roadmap
#+STARTUP: content
#+FILETAGS: :docs:roadmap:cl-tty:

* The Roadmap

Each phase is one minor release. Phases ship in dependency order — each depends on
the components from prior phases.

** v0.0.1: Backend Protocol

DONE. Two backends implementing a common protocol:

- =modern-backend= — raw escape sequences, truecolor 24-bit, OSC 8 hyperlinks,
  DECICM sync, SGR mouse, kitty keyboard protocol, bold/italic/underline,
  box-drawing chars (rounded/single/double)
- =simple-backend= — ASCII art only, no color, universal compatibility for
  SSH/piped output

~180 lines total. Dependencies: None (pure CL, no FFI).

*** Backend protocol generic functions:
  - =initialize-backend=, =shutdown-backend=, =backend-size=, =backend-write=, =backend-clear=
  - =draw-rect=, =draw-text=, =draw-border=, =draw-ellipsis=, =draw-link=
  - =cursor-move=, =cursor-hide=, =cursor-show=, =cursor-style=
  - =begin-sync=, =end-sync= (DECICM)
  - =read-event=, =enable-mouse=, =enable-bracketed-paste=, =set-keyboard-mode=
  - =capable-p= — query feature support

** Layout Engine (pure CL)

DONE. Pure Common Lisp Flexbox layout engine. No Yoga, no CFFI, no external
dependencies. A two-pass constraint solver handling direction, wrap,
grow/shrink/gap padding/margin, absolute positioning.

~190 lines. Macros: =vbox=, =hbox=, =spacer=.

** v0.2.0: Box, Text, Span, Dirty Tracking

DONE. The first two renderable types. Box draws borders and backgrounds.
Text renders strings with color, word-wrap, and inline style spans.

- =Box= with border styles (:single, :double, :rounded), title, background
- =Text= with word-wrap (:none, :word), fg/bg colors
- =Span= — inline text segment with attributes (:bold, :italic, etc.)
- =Dirty-mixin= — marks components and ancestors for re-render
- =Theme= — semantic color tokens, presets (default, nord, catppuccin, etc.)
- =render= generic function dispatched on component type

** v0.5.0: Text Input + Keybinding System

DONE. Text input widgets with readline-style keybindings.

- =TextInput= — single-line input with cursor, placeholder, max-length, on-submit
- =Textarea= — multi-line input with undo/redo (100-deep stack), cursor nav,
  selection, on-submit
- =Keymap= — layered keybinding system with =defkeymap= macro
- Event handling: key-event, mouse-event structs, raw-byte reader

** v0.6.0: ScrollBox + TabBar

DONE. Container components.

- =ScrollBox= — scrollable viewport with vertical/horizontal scrollbars,
  scroll-by, clamp, sticky-scroll mode
- =TabBar= — horizontal tab navigation with next/prev, active tab tracking

** v0.7.0: Select — Dropdown + Fuzzy Filter

DONE. A selection list component with keyboard navigation, category headers,
and fuzzy text matching.

** v0.8.0: Markdown + Code + Diff Rendering

DONE. Content rendering for agent responses and file diffs.

- Markdown parser: headings, bold/italic/code, links, code blocks,
  blockquotes, lists, thematic breaks
- Syntax highlighting: regex-based for Lisp keywords, comments, strings
- Diff rendering: added/removed/context lines with colored backgrounds
- ANSI rendering via raw escape sequences

** v0.9.0: Dialog System + Toast

DONE. Modal overlays and transient notifications.

- =Dialog= — centered modal with backdrop dimming, size variants
- =push-dialog= / =pop-dialog= — stack-based dialog management
- =alert-dialog=, =confirm-dialog=, =select-dialog=, =prompt-dialog=
- =Toast= — transient notification with variants (:info/:success/:warning/:error),
  auto-dismiss, top-right positioning

** v0.10.0: Mouse Support

DONE (minimal). Mouse event handling via mixin class.

- =mouse-mixin= — event handler slots (:on-mouse-down/up/move/scroll)
- =handle-mouse-event= — dispatch to component handlers
- =hit-test= — find deepest component at (x, y)
- =selection= struct and =copy-to-clipboard=

** v0.11.0: Plugin / Slot System

DONE. Extensible named slots for registering content into extensible positions.

- =defslot=, =slot-render=, =clear-slot=, =list-slots=
- Slot modes planned but not implemented

** v0.12.0: Terminal Capability Detection

DONE. Auto-detect terminal capabilities at startup and return the
appropriate backend.

- Check if stdout is a TTY (if not -> simple-backend)
- =detect-backend= -> returns =modern-backend= or =simple-backend=
- Send DA1 query (~ESC[c~), 100ms timeout
- Send DA3 (~ESC[?c~) for kitty/wezterm identification
- Query DECRPM (~ESC[?2026$p~) for DECICM sync support
- Check =COLORTERM= env var for truecolor support
- Cache detection result for subsequent instant calls
- Add =detect-backend= to backend package API
- ~100 lines

** v0.13.0: Rendering Pipeline

DONE. A pure CL rendering pipeline — framebuffer diffing for incremental
output, scissor clipping, and render-command dispatching.

- =*framebuffer*= — 2D array of (char, fg, bg, attrs) tuples
- =flush-framebuffer= — compares current to previous, writes only changed cells
- =with-scissor= — clips all render operations to a rectangle
- Component =render= methods produce render commands, not direct backend calls
- =diff-output= framework for minimum-escape optimization
- ~250 lines

** v0.14.0: Mouse Improvements

DONE. Enhance mouse support with drag-to-select and link clicking.

- Text selection via mouse drag (highlight region between drag start/end)
- Click on OSC 8 link: extract URL, open via xdg-open
- Copy-to-clipboard via xclip/wl-copy/pbcopy
- ~80 lines

** v0.15.0: Bug fixes, demo rewrite, verification, tangle tooling

DONE. Demo rewrite with interactive tabs, critical bug fixes, and
quality-of-life infrastructure.

- Demo (demo.lisp): full rewrite with Console, Components, Layout,
  Events tabs — tab navigation, scrollbox with hot-reload, layout
  visualization with live row/column swapping, event logging panel
- Demo uses backend-size instead of hardcoded 80x24
- Box title rendering: modern and simple backends now render titles
  with title and title-align parameters
- Cursor rendering: text-input cursor renders as solid block at
  cursor position
- Arrow key fix: demo arrow keys on Widgets tab no longer steal
  focus from tab bar
- read-raw-byte buffer fix: sb-sys:with-pinned-objects + vector-sap
  for proper sb-posix:read buffer (SBCL type error with plain arrays)
- EOF detection: read-raw-byte returns (values nil :eof) on stdin
  EOF, not nil — prevents 100% CPU busy-spin on pipes
- Escape key: 50ms timeout in read-escape-sequence to disambiguate
  lone Escape from escape-prefixed sequences
- confirm-dialog: fix option plist comparison (was comparing
  objects, not keys)
- mouse-event: button slot type changed from keyword to (or keyword
  null)
- tangle tooling: replace Emacs org-babel-tangle with pure-Python
  script (scripts/tangle.py, later moved to Hermes skill)
- Verification: verify-api.py (API smoke tests), verify-demo-pty.py
  (PTY-based demo verification — 17 checks)
- tangle.py fix: write-once-then-append logic (was always-appending,
  triplicating files)
- Org/Lisp sync: verified — 483+57+17 checks pass on fresh tangle
- Project restructure: move backend/ and layout/ into src/
- .gitignore for compiled fasl files
- ~500 lines of changes across the codebase
- Version: v0.15.0 (current)

Known gaps from earlier phases:
- suspend-backend / resume-backend (in ARCHITECTURE.org protocol
  spec but never implemented)
- Slot modes (defslot :mode parameter planned but not implemented)

** v1.0.0: Release (target — not yet released)

All phases integrated and tested. Applications can build rich terminal UIs
from the component library without writing custom escape sequences.

Checklist:
- [X] README.org with overview, architecture, component table, quick start
- [X] demo.lisp — working interactive example
- [X] Full test suite: 483 checks, 100% passing across 13 suites
- [X] ASDF system with test-op
- [X] LICENSE file (GPL 3.0)
- [X] Literate org files for all modules
- [X] Terminal capability detection (v0.12.0)
- [X] Rendering pipeline (v0.13.0)
- [X] Mouse improvements (v0.14.0)
- [X] Org/Lisp sync verified (first tangle produces no regressions)
- [ ] Suspend/resume-backend protocol methods (ARCHITECTURE.org spec)
- [ ] Slot modes (defslot :mode parameter)

** Feature Reference

| Phase | Component                              | Lines  | Release | Status |
|-------+----------------------------------------+--------+---------|--------|
| 0     | Backend protocol (simple + modern)     | ~180   | v0.0.1  | DONE   |
| -     | Layout engine (pure CL flexbox)        | ~190   | -       | DONE   |
| 1     | Renderables (Box, Text) + dirty        | ~300   | v0.2.0  | DONE   |
| 2     | Theme engine (tokens, presets)         | ~120   | v0.4.0  | DONE   |
| 3     | TextInput + Textarea + keybindings     | ~500   | v0.5.0  | DONE   |
| 4     | ScrollBox + TabBar                     | ~200   | v0.6.0  | DONE   |
| 5     | Select (dropdown + fuzzy filter)       | ~150   | v0.7.0  | DONE   |
| 6     | Markdown + Code + Diff                 | ~400   | v0.8.0  | DONE   |
| 7     | Dialog system + Toast                  | ~220   | v0.9.0  | DONE   |
| 8     | Mouse support                          | ~80    | v0.10.0 | DONE   |
| 9     | Plugin / slot system                   | ~50    | v0.11.0 | DONE   |
| 10    | Terminal capability detection          | ~100   | v0.12.0 | DONE   |
| 11    | Rendering pipeline (framebuffer diff)  | ~250   | v0.13.0 | DONE   |
| 12    | Mouse improvements (selection, links)  | ~80    | v0.14.0 | DONE   |
| 13    | Bug fixes, demo rewrite, verification  | ~500   | v0.15.0 | DONE   |
|-------+----------------------------------------+--------+---------|--------|
|       | Total                                  | ~5760  |         |        |