amr/cl-tty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07c29290d4879c5083bba0e6529981e340f65745
cl-tty/docs/ROADMAP.org
Hermes Agent 3cbcfd2d75 v1.0.0 release 
Bug fixes:
- Fix OSC8 format strings (backslash escape layering) in modern-backend.org
  - Test format string had single backslash instead of double, causing
    unclosed CL string that cascaded through 3 subsequent test forms
  - Implementation format string had leading escaped quote (not a string
    opener) and triple-backslash ending (also not a string terminator)
- Fix missing closing parens in border-char-rounded and border-char-double tests
- Fix ASDF input-tests pathname (file lives in tests/, not src/components/)

New features:
- Implement suspend-backend / resume-backend protocol methods
  - modern-backend: exit/enter alt screen, re-enable mouse/kitty/bracketed-paste
  - simple-backend: no-ops (no terminal state to preserve)

Infrastructure:
- Update test suite to cover suspend/resume (backend + modern-backend suites)
- 454 checks, 100% pass across 14 test suites
2026-05-12 20:00:27 +00:00

9.4 KiB
Raw Blame History

cl-tty 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

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: v1.0.0 (current)

Known gaps from earlier phases:

  • (none — all protocol spec items implemented)

v1.0.0: Release

DONE. 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: 454 checks, 100% passing across 14 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)
  • 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
Reference in New Issue View Git Blame Copy Permalink