@@ -29,7 +29,7 @@ Dependency chain: `components → core → types`
2929 - **Cell buffer rendering:** Layout writes to a 2D grid of styled cells, not raw strings. Clipping and layer compositing are cell writes. Diff against previous buffer for minimal terminal output.
3030 - **Reactive rendering:** `cel.render()` batches via `process.nextTick()`. No fixed FPS.
3131 - **Layers:** `cel.viewport(() => [layer1, layer2])` — array of independent viewport-sized trees, composited bottom-to-top. Conditional inclusion = show/hide.
32-- **Key bubbling:** Unconsumed keys bubble up from focused element through ancestors. Root `onKeyPress` = global handler.
32+- **Key bubbling:** Unconsumed keys bubble up from focused element through ancestors. Root `onKeyPress` = global handler. Escape blur is a fallback default action after bubbling — consuming `escape` prevents blur.
3333 - **Hit detection:** Topmost layer first, deepest node at (x,y), walk up to find handler. Innermost wins for scroll, click, keys.
3434
3535 ## Implementation Status
@@ -39,10 +39,10 @@ All core systems from the spec are implemented and tested:
3939 - **Layout engine** — flexbox sizing (fixed, intrinsic, flex, percentage), constraints (including cross-axis min/max), gap, padding, justifyContent, alignItems, flexWrap, largest-remainder rounding
4040 - **Rendering** — cell buffer, ANSI emitter with SGR styling, synchronized output (CSI 2026), differential rendering (emitDiff), full clear on resize
4141 - **Painting** — grapheme-aware text rendering (CJK/emoji via visibleWidth), overflow clipping via clip rect propagation, scroll content offsetting, scrollbar indicators, container bgColor fill, style inheritance, focusStyle overrides
42-- **Input** — Kitty keyboard protocol (level 1, required), key parsing/normalization for CSI u / CSI letter / CSI tilde formats, SGR mouse events (with batched event support), hit detection, click/scroll routing, focus traversal (Tab/Shift+Tab/Escape/Enter) with uncontrolled and controlled modes, onKeyPress bubbling from focused element through ancestors
43-- **TextInput** — grapheme-aware text editing (Intl.Segmenter for emoji/ZWJ), cursor movement, cursor persistence across re-renders (keyed on onChange, clamped on external value changes), auto-scroll to keep cursor visible, inverted-cell cursor with native terminal cursor positioning (blinking), background fill, placeholder rendering
42+- **Input** — Kitty-first keyboard input (Kitty level 1 enable), mixed-stream decoding for CSI u / CSI letter / CSI tilde / recoverable legacy control bytes / ESC-prefixed Alt combos, batched SGR mouse handling, hit detection, click/scroll routing, focus traversal (Tab/Shift+Tab/Escape/Enter) with uncontrolled and controlled modes, onKeyPress bubbling from focused element through ancestors
43+- **TextInput** — grapheme-aware text editing (Intl.Segmenter for emoji/ZWJ), cursor movement, cursor persistence across re-renders (keyed on onChange, clamped on external value changes), batched key handling with preserved edit state across stdin chunks, auto-scroll to keep cursor visible, inverted-cell cursor with native terminal cursor positioning (blinking), background fill, placeholder rendering
4444 - **Layering** — multi-layer compositing, transparency, topmost-layer input priority
45-- **Terminal** — Kitty keyboard protocol enable/disable, crash cleanup (SIGINT/SIGTERM/uncaughtException), resize clear
45+- **Terminal** — Kitty level 1 enable/disable, mixed keyboard stream compatibility in tmux, crash cleanup (SIGINT/SIGTERM/uncaughtException), resize clear
4646
4747 See `TODO.md` for remaining spec violations and future work.
4848
@@ -71,13 +71,13 @@ Use a tmux session to run examples and visually inspect rendered output.
7171
7272 ### tmux Configuration
7373
74-cel-tui requires the Kitty keyboard protocol. tmux 3.2+ supports it via the `extended-keys` option, but it's **off by default**. The global `~/.tmux.conf` must include:
74+cel-tui is **Kitty-first**, but `tmux` is a supported environment. tmux 3.2+ should have `extended-keys` enabled so it preserves as much modifier information as possible:
7575
7676 ```
7777 set -s extended-keys on
7878 ```
7979
80-Without this, tmux intercepts the protocol negotiation and key events arrive in legacy format that the framework's parser won't recognize.
80+With that setting enabled, common keyboard-driven checks work well through `tmux send-keys`. Without it, cel-tui still accepts many recoverable legacy encodings, but historically ambiguous collisions remain collapsed by the host (`ctrl+i`/`tab`, `ctrl+m`/`enter`, `ctrl+[`/`escape`).
8181
8282 ### Usage
8383
@@ -91,7 +91,8 @@ tmux send-keys -t cel "cd /home/xonecas/src/cel-tui && bun run examples/hello.ts
9191 # Wait for render, then capture the screen contents
9292 sleep 1; tmux capture-pane -t cel -p
9393
94-# Send keystrokes (e.g., Ctrl+Q to quit)
94+# Send common keystrokes directly
95+# (printable chars, Tab/BTab, Enter, Escape, arrows, many Ctrl+letter combos)
9596 tmux send-keys -t cel C-q
9697
9798 # Resize the window to test different terminal sizes
@@ -101,11 +102,25 @@ tmux resize-window -t cel -x 60 -y 20
101102 tmux kill-session -t cel
102103 ```
103104
104-This lets you see exactly what the user sees — rendered cells, alignment, clipping, colors — without needing a real interactive terminal.
105+This lets you see exactly what the user sees — rendered cells, alignment, clipping, and, via `capture-pane -e -p`, style escape sequences — without needing a real interactive terminal.
105106
106-### Sending Keys with the Kitty Protocol
107+### Sending Keys in tmux
107108
108-cel-tui requires the Kitty keyboard protocol. `tmux send-keys` named keys (e.g., `C-q`, `Enter`) inject **legacy** byte sequences that the framework's parser won't recognize. Use the `kittyEncode` test helper with `send-keys -H` (hex mode) instead:
109+For most keyboard-driven manual checks, plain `tmux send-keys` is now sufficient:
110+
111+```bash
112+# Common cases that work well in tmux with extended-keys on
113+tmux send-keys -t cel a
114+tmux send-keys -t cel Enter
115+tmux send-keys -t cel Escape
116+tmux send-keys -t cel Tab
117+tmux send-keys -t cel BTab
118+tmux send-keys -t cel Up
119+tmux send-keys -t cel C-q
120+tmux send-keys -t cel C-r
121+```
122+
123+Use exact Kitty-style injection only when you need to test protocol-specific sequences or combos that tmux named keys do not express reliably (for example `shift+enter`, `ctrl+plus`, or a precise CSI-u path):
109124
110125 ```bash
111126 # Helper: convert a key name to hex bytes via kittyEncode
@@ -120,39 +135,37 @@ send_key() {
120135 }
121136
122137 # Usage:
123-send_key "ctrl+q" # Quit
124-send_key "tab" # Focus traversal
125-send_key "enter" # Activate
126-send_key "escape" # Unfocus
127-send_key "a" # Printable character (lowercase only)
128-send_key "ctrl+s" # Modifier combo
129-send_key "shift+tab" # Reverse focus traversal
138+send_key "ctrl+q"
139+send_key "shift+enter"
140+send_key "ctrl+plus"
141+send_key "shift+tab"
130142 ```
131143
132-**Limitations:** The helper lowercases all input, so uppercase letters aren't testable this way.
144+**Limitations:** the helper lowercases printable input, so uppercase-text insertion is still better tested with plain `tmux send-keys` or in a real terminal.
133145
134-**Caveat:** tmux `send-keys -H` injects raw bytes one event at a time, but real terminals batch multiple mouse events into a single stdin chunk. Always verify mouse/scroll behavior in a real terminal, not just tmux.
146+**Caveat:** `tmux send-keys -H` injects raw bytes one event at a time, while real terminals may batch multiple keyboard or mouse events into a single stdin chunk. Use hex injection to target exact encodings, not to simulate full terminal behavior.
135147
136148 ### Mouse Events Don't Work in tmux
137149
138-SGR mouse events (click, scroll) sent via `tmux send-keys -H` are **unreliable** and should not be used for testing. Even with correctly-formatted SGR press/release byte sequences and `mouse off` in tmux config, the injected bytes may not reach the application's stdin in a form the parser recognizes. This is a known tmux limitation with raw byte injection for mouse protocols.
150+SGR mouse events (click, scroll) sent through tmux remain **unreliable** and should not be used for verification. Even with correctly formatted SGR sequences and `mouse off` in tmux config, the injected bytes may not reach the application's stdin in a form the parser recognizes. This is a tmux limitation around raw mouse protocol injection.
139151
140-**Do not test mouse interactions (click, scroll) through tmux.** Use tmux only for:
152+**Do not treat tmux as authoritative for mouse interactions (click, scroll).** Use tmux for:
141153
142-- Keyboard-driven testing via `send_key` helper
143-- Visual inspection of rendered output via `tmux capture-pane -p`
144-- Verifying layout, alignment, and text content
154+- Keyboard-driven testing via plain `tmux send-keys` for common keys
155+- Exact keyboard-sequence injection via `send_key` when you need protocol precision
156+- Visual inspection via `tmux capture-pane -p` / `tmux capture-pane -e -p`
157+- Verifying layout, alignment, text content, and many keyboard flows
145158
146-Mouse and scroll behavior must be verified in a real interactive terminal.
159+Mouse and scroll behavior still need verification in a real interactive terminal.
147160
148161 ### tmux capture-pane Limitations
149162
150163 `tmux capture-pane -p` captures **plain text only** — no colors or style attributes. This means:
151164
152165 - You can verify text content, alignment, and layout structure
153-- You **cannot** verify `fgColor`, `bgColor`, `bold`, `focusStyle` changes, or any visual styling
166+- You **cannot** verify `fgColor`, `bgColor`, `bold`, or `focusStyle` changes from plain-text capture alone
154167
155-To inspect colors, use `tmux capture-pane -e -p` (includes escape sequences) or verify styling through unit tests against the cell buffer.
168+To inspect styling, use `tmux capture-pane -e -p` (includes escape sequences) or verify style output through unit tests against the cell buffer.
156169
157170 ## Spec
158171
@@ -203,15 +216,15 @@ chore: scaffold monorepo with types, core, components packages
203216
204217 ## Architecture Notes
205218
206-- `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal, options?)` starts (accepts optional `{ theme }` for custom color themes), `cel.viewport(fn)` sets render function, `cel.render()` requests re-render, `cel.stop()` restores terminal. Mouse input handles batched SGR events (terminals often send multiple events in a single data chunk). TextInput key handling: `onKeyPress` fires before built-in editing logic — returning `false` prevents the …
219+- `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal, options?)` starts (accepts optional `{ theme }` for custom color themes), `cel.viewport(fn)` sets render function, `cel.render()` requests re-render, `cel.stop()` restores terminal. Input handling treats stdin as a mixed stream: keyboard chunks may contain multiple decoded key events, mouse input handles batched SGR events, and TextInput batching preserves the latest value/cursor across m …
207220 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
208221 - `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets (clamped to max — apps can pass `Infinity` to mean "scroll to end"), scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state (with cursor screen position export for native cursor), TextInput background fill, container bgColor fill, style inheritance threading, focusStyle resolution.
209222 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both accept an optional `Theme` for color resolution and wrap in CSI 2026 synchronized output. Exports `defaultTheme` (ANSI 16 mapping).
210223 - `hit-test.ts` — `hitTest(root, x, y, getScrollOffset?)` → path from root to deepest node at `(x,y)`, accounting for scroll offsets. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
211-- `keys.ts` — Kitty keyboard protocol parser. `parseKey(data)` handles CSI u sequences (special keys, modifier combos), CSI letter sequences (arrows, Home/End with modifiers), CSI tilde sequences (Delete, PageUp/Down, F-keys with modifiers), and raw printable bytes. Maps `" "` → `"space"`, `"+"` → `"plus"` as named keys. `isEditingKey()` identifies keys consumed by TextInput. `normalizeKey()` reorders modifiers to canonical `ctrl+alt+shift+<key>` order.
224+- `keys.ts` — Kitty-first input decoder. `decodeKeyEvents(data)` splits a raw chunk into ordered key events, accepting CSI u / CSI letter / CSI tilde sequences, recoverable legacy ASCII control bytes, ESC-prefixed Alt combos, and raw printable text. Key events carry a normalized semantic `key` plus optional original insertable `text`. `parseKey(data)` remains as a convenience wrapper for single-event cases. `isEditingKey()` identifies non-text editing/navigation keys consumed by TextInput, and …
212225 - `text-edit.ts` — Pure text editing functions (`insertChar`, `deleteBackward`, `deleteForward`, `moveCursor`). Operates on `EditState` (value + cursor position). Uses `Intl.Segmenter` with grapheme granularity for cursor movement and deletion (handles emoji, ZWJ sequences, combining marks). Used by `cel.ts` to handle TextInput key events.
213226 - `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
214-- `terminal.ts` — `ProcessTerminal` (real I/O, raw mode, Kitty keyboard protocol level 1, SGR mouse, crash cleanup) and `MockTerminal` (testing).
227+- `terminal.ts` — `ProcessTerminal` (real I/O, raw mode, Kitty keyboard protocol level 1 enable, SGR mouse, crash cleanup) and `MockTerminal` (testing). The runtime prefers Kitty semantics but the parser still accepts mixed tmux/legacy keyboard encodings.
215228
216229 ## Updating gh-pages
217230
@@ -323,6 +336,14 @@ bun run typecheck && bun test && bun run check && bun run format
323336 - `get-east-asian-width` is a real dependency of `@cel-tui/core` (installs for consumers)
324337 - `typescript` is a peer dependency (consumers bring their own)
325338
339+## Non-interactive Commands
340+
341+Avoid commands that open an interactive editor or prompt from the agent shell. They can hang the tool.
342+
343+- Always pass messages explicitly for git commands that might invoke `$EDITOR`.
344+- Use `git commit -m "..."` and `git tag -a <tag> -m "..."`.
345+- Do not run bare `git tag <tag>` during release work.
346+
326347 ## Destructive Actions
327348
328349 **Never use `git checkout` or `git restore` on files you have modified.** A single `git checkout <file>` will silently discard all uncommitted changes in that file — including unrelated work. If you need to revert a specific edit, use `edit` to undo just that change. If you must use git to undo something, `git stash` first so the work can be recovered.