amr/cl-tty

Files

Hermes b7df68c436 v0.12.0: Terminal capability detection, GPL 3.0 license, roadmap rewrite

LICENSE:
- Added GNU General Public License v3.0
- Updated README.org to reflect GPL 3.0

ROADMAP:
- Complete rewrite to reflect actual project state
- Removed croatoan/ncurses/Yoga FFI references
- Marked all 11 existing versions DONE
- Added v0.12.0-0.14.0 for new features (detection, pipeline, mouse)

DETECTION (v0.12.0):
- detect-backend: auto-detect modern vs simple backend
- detect-backend-by-env: check COLORTERM env var
- detect-backend-by-tty: check interactive-stream-p
- detect-backend-by-da1: query terminal via ESC[c (best-effort)
- *detected-backend* cache for zero-cost subsequent calls
- Added detection.lisp to ASDF and package exports
- Added 2 new tests (360 total, all passing)
- demo.lisp updated to use detect-backend

ORG BACKPORT (pre-existing fixes synced):
- dialog.org: render-dialog/render-toast fixes, class initforms
- scrollbox-tabbar.org: background-element -> bright-black, remove duplicate render
- select.org: remove duplicate render export
- text-input.org: remove duplicate %split-string, undo overflow fix
- layout-engine.org: quoted-literal -> list constructors, normalize-box rewrite
- mouse.org: add missing exports, fix test

2026-05-11 22:25:42 +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

TODO. 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

TODO. 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

TODO. 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: 358 checks, 100% passing across 11 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	TODO
11	Rendering pipeline (framebuffer diff)	~250	v0.13.0	TODO
12	Mouse improvements (selection, links)	~80	v0.14.0	TODO
	Total	~2800

7.4 KiB Raw Blame History