Compare commits

4 Commits

3 changed files with 46 additions and 6 deletions

View File

@@ -207,12 +207,13 @@ When sending code to the REPL, use the correct `(in-package ...)` form first.
|---------|-------------|
| `:cl-tty.backend` | Backend protocol — terminal init, draw-text, read-event |
| `:cl-tty.rendering` | Framebuffer — make-framebuffer, flush-framebuffer |
| `:cl-tty.input` | Input — key-event, defkeymap, dispatch-key-event |
| `:cl-tty.input` | Input — key-event, defkeymap, dispatch-key-event, text-input, textarea |
| `:cl-tty.layout` | Layout — vbox, hbox, spacer, layout-calculate |
| `:cl-tty.dialog` | Dialog system — dialog stack, select-dialog |
| `:cl-tty.select` | Select widget — filter, handle-key |
| `:cl-tty.box` | Components — box, text, word-wrap, char-width, dirty-mixin, render protocol |
| `:cl-tty.theme` | Theme — theme class, define-preset, load-preset, theme-color |
| `:cl-tty.dialog` | Dialog — dialog stack, select, select-dialog, alert-dialog, toast |
| `:cl-tty.slot` | Slot/plugin system |
| `:cl-tty.markdown` | Markdown rendering |
| `:cl-tty.markdown` | Markdown — parse-blocks, parse-inline, highlight-code, render-md |
## Setup
@@ -286,3 +287,42 @@ when the runtime itself cannot start.
- **YOU MAY NOT** push a version tag (e.g., `v0.5.0`), create a GitHub release,
or run `git push` that triggers CI/CD version workflows without explicit
permission. Ask first.
## Library/Application Boundary (passepartout + cl-tty)
The line between cl-tty and passepartout must be clear. Violations produce
duplicated code, inconsistent UX, and maintenance burden across both projects.
**The rule: before writing any UI code in passepartout, check cl-tty first.**
If the abstraction already exists in cl-tty, use it. If it doesn't exist, add it
to cl-tty first, then consume it in passepartout.
| This belongs in **cl-tty** (library) | This belongs in **passepartout** (application) |
|---------------------------------------|------------------------------------------------|
| Widget rendering, layout computation, dirty tracking | Which widgets to show and when |
| Theme system (presets, role→hex resolution, load/switch) | Theme choice and application-specific semantic keys |
| Markdown parser, renderer, syntax highlighter | What markdown content to render |
| Input handling (keymaps, text-input, textarea, event dispatch) | What keybindings to register and what actions they trigger |
| Dialog, select, toast rendering and keyboard navigation | Dialog content and on-submit/on-select callbacks |
| Word-wrap, char-width, cursor rendering | Cursor position and text content |
| Box, scrollbox, tabbar, panel containers | Data displayed inside containers |
**Concrete checklist before writing any UI function in a passepartout .org file:**
1. Run `(do-external-symbols (s :cl-tty.box) ...)` or check this table
2. If the function exists in cl-tty, call it — do not reimplement
3. If the function doesn't exist but belongs in a library (generic widget, theme
mechanism, layout primitive, input handler), add it to cl-tty first
4. If the function is passepartout-specific business logic (command dispatch,
daemon communication, gate trace data model), write it in passepartout
Common violations found in the codebase (do not repeat):
- Writing a parallel theme system (`*tui-theme*`, `*tui-theme-presets*`,
`theme-switch`) — use `cl-tty.theme` instead
- Writing a custom word-wrap — use `cl-tty.box:word-wrap` instead
- Writing a custom markdown parser or syntax highlighter — use
`cl-tty.markdown` instead
- Bypassing `select-handle-key` with manual dialog key dispatch — use
`select-handle-key` and `render-dialog` instead
- Hardcoding inline hex colors — use `(theme-color :role)` instead
- Manual framebuffer coordinate arithmetic — use `vbox`/`hbox`/`spacer` layout
from `cl-tty.layout` instead