@@ -1,120 +1,27 @@
11 # cel-tui — TODO
22
3-What's implemented, what's missing, and what needs hardening. Reference `spec.md` for full design.
3+Remaining work and known discrepancies vs `spec.md`.
44
55 ## Legend
66
7-- ✅ Implemented and tested
8-- 🔧 Partially implemented (basic version exists, needs work)
7+- 🔧 Needs fix (spec violation or bug)
98 - ❌ Not yet implemented
9+- 💡 Nice-to-have / future enhancement
1010
1111 ---
1212
13-## Layout Engine
13+## Spec Violations
1414
15-- ✅ Fixed sizing (`width: 30, height: 10`)
16-- ✅ Intrinsic sizing (containers fit children, Text height from content)
17-- ✅ Flex distribution with largest remainder rounding
18-- ✅ Percentage sizing (`width: "50%"`)
19-- ✅ Constraints (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`)
20-- ✅ Gap spacing between children
21-- ✅ Padding (`{ x, y }`)
22-- ✅ `justifyContent` — `"start"`, `"end"`, `"center"`, `"space-between"`
23-- ✅ `alignItems` — `"start"`, `"end"`, `"center"`, `"stretch"`
15+- 🔧 **Tab key consumed by TextInput when focused** — The spec says Tab is an editing key consumed by TextInput (inserts `\t`). Currently Tab always triggers focus traversal. The spec requires Escape to leave the input first, then Tab to traverse. Fix: skip Tab/Shift+Tab focus traversal when a TextInput is focused.
2416
25-## Rendering
17+- 🔧 **Mouse wheel scroll inside TextInput** — `findScrollTarget` correctly identifies TextInput as a scroll target, but `cel.ts` scroll handling only updates containers with `overflow: "scroll"`. It should also update TextInput's framework-managed scroll offset when the mouse wheel targets a TextInput.
2618
27-- ✅ Cell buffer (2D grid, get/set/fill/clear/resize/diff/isEmpty)
28-- ✅ ANSI emitter (SGR colors, bold/italic/underline, synchronized output CSI 2026)
29-- ✅ Reactive rendering (`cel.render()` batched via `process.nextTick`)
30-- ✅ Full render on first paint, cursor home positioning
31-- ✅ Differential rendering — `emitDiff()` uses `CellBuffer.diff()` to emit only changed cells
32-- ✅ Full clear + re-render on terminal resize (clears screen before re-render)
19+## Not Yet Implemented
3320
34-## Painting
35-
36-- ✅ Text painting (content, newlines, styling)
37-- ✅ Text `repeat: "fill"` and `repeat: <number>`
38-- ✅ Text `wrap: "word"` (basic word-wrap)
39-- ✅ Hard clipping at rect boundaries
40-- ✅ TextInput painting (value, placeholder, cursor via color inversion)
41-- ✅ Text wrapping and layout use `visibleWidth()` for correct CJK/emoji handling
42-- ✅ Overflow clipping — children clipped to parent bounds via clip rect propagation
43-- ✅ Scroll rendering (`overflow: "scroll"`) — content offset applied during painting
44-- ✅ Scrollbar rendering (`scrollbar: true`) — vertical and horizontal indicators
45-
46-## Input
47-
48-- ✅ Key parsing (ASCII, control chars, CSI sequences, arrow keys, function keys)
49-- ✅ Key normalization (canonical modifier order)
50-- ✅ Mouse event parsing (SGR mode: click, scroll-up, scroll-down)
51-- ✅ Hit detection (point → deepest node path)
52-- ✅ Click routing (innermost `onClick` wins)
53-- ✅ Scroll routing (innermost scrollable, fires `onScroll`)
54-- ✅ Key routing to `onKeyPress` handlers
55-- ✅ TextInput key consumption (editing keys consumed, modifiers bubble)
56-- ✅ `onKeyPress` bubbling — walks up from focused element through all ancestors
57-- ✅ Focus traversal (Tab/Shift+Tab cycling through focusable elements)
58-- ✅ Escape to unfocus
59-- ✅ Enter to activate focused clickable container
60-- ✅ Mouse click focusing (clicking a focusable element fires `onFocus`)
61-- ✅ `onFocus`/`onBlur` callbacks fired by framework
62-
63-## Layer Compositing
64-
65-- ✅ Multiple layers paint bottom-to-top
66-- ✅ Transparency (empty cells in upper layer show lower layer)
67-- ✅ Topmost layer receives input events first
68-- ✅ Conditional layers (show/hide via array inclusion)
69-
70-## TextInput
71-
72-- ✅ Text editing (insert, delete backward/forward)
73-- ✅ Cursor movement (left/right/up/down/home/end)
74-- ✅ Vertical navigation across lines
75-- ✅ `onChange` fires on edits
76-- ✅ `onSubmit` fires on `submitKey`
77-- ✅ Placeholder rendering
78-- ✅ Cursor display (inverted colors)
79-- ✅ Cursor state keyed on `onChange` function reference for stable identity across re-renders
80-- ✅ Framework-managed scroll (auto-scroll to keep cursor visible)
81-- ❌ Mouse wheel scroll inside TextInput
82-
83-## Terminal
84-
85-- ✅ `ProcessTerminal` (raw mode, SGR mouse, cursor hide/show)
86-- ✅ `MockTerminal` (captured output, simulated input/resize)
87-- ✅ Restore terminal state on crash/unhandled exception (cleanup handler)
8821 - ❌ Bracketed paste mode support
8922 - ❌ Kitty keyboard protocol detection
9023
91-## Pre-made Components
92-
93-- ✅ `Spacer` — `VStack({ flex: 1 }, [])`
94-- ✅ `Divider` — `Text(char, { repeat: "fill" })`
95-- ✅ `Button` — `HStack({ onClick }, [Text(label)])`
96-
97-## Developer Experience
98-
99-- ✅ JSDoc on all public types, interfaces, and functions
100-- ✅ TypeDoc generation (HTML + Markdown)
101-- ✅ Agent Skills file (`docs/skill/cel-tui/SKILL.md`)
102-- ✅ AGENTS.md for onboarding
103-- ❌ Example apps that fully work end-to-end (`examples/hello.ts` needs alignment)
104-
105----
106-
107-## Priority Order
108-
109-Suggested order to tackle remaining work:
24+## Future Enhancements
11025
111-1. **`justifyContent` + `alignItems`** — unblocks the hello example and any centered layout
112-2. **`visibleWidth` integration** — text measurement in layout + paint should use grapheme-aware width
113-3. **Overflow clipping** — parent bounds must clip children (`overflow: "hidden"`)
114-4. **Scroll rendering** — `overflow: "scroll"` offsets content, scrollbar indicator
115-5. **Differential rendering** — use `CellBuffer.diff()` to emit only changed cells
116-6. **Focus system** — Tab traversal, Escape unfocus, Enter activate, onFocus/onBlur
117-7. **`onKeyPress` full bubbling** — walk up from focused element, not just root
118-8. **TextInput cursor persistence** — stable identity across re-renders
119-9. **TextInput auto-scroll** — scroll to keep cursor visible
120-10. **Terminal hardening** — crash cleanup, bracketed paste, resize clear
26+- 💡 Additional example apps (chat UI, text editor from spec reference examples)
27+- 💡 `overflow: "hidden"` as explicit prop (currently all containers clip by default, which matches the spec's default behavior, but the prop value is not checked)