amr/cl-tty

Files

Hermes Agent b21daa99b8 fix: input timeout bugs — read-raw-byte, SS3, parse-csi-params all use sub-second timeouts now (get-internal-real-time replaces get-universal-time which truncated to integer seconds)

2026-05-12 13:42:39 +00:00

7.4 KiB

Raw Blame History

cl-tty Roadmap

The Roadmap

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

v1.0.0: Release

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

Checklist:

README.org with overview, architecture, component table, quick start
demo.lisp — working interactive example
Full test suite: 392 checks, 100% passing across 12 suites
ASDF system with test-op
LICENSE file (GPL 3.0)
Literate org files for all modules
Terminal capability detection (v0.12.0)
Rendering pipeline (v0.13.0)
Mouse improvements (v0.14.0)
Org/Lisp sync verified (first tangle produces no regressions)

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
	Total	~2800

7.4 KiB Raw Blame History