@@ -0,0 +1,120 @@
1+# cel-tui — TODO
2+
3+What's implemented, what's missing, and what needs hardening. Reference `spec.md` for full design.
4+
5+## Legend
6+
7+- ✅ Implemented and tested
8+- 🔧 Partially implemented (basic version exists, needs work)
9+- ❌ Not yet implemented
10+
11+---
12+
13+## Layout Engine
14+
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` — positions are computed but alignment offsets not applied (`"start"`, `"end"`, `"center"`, `"space-between"`)
23+- ❌ `alignItems` — cross-axis alignment not applied (`"start"`, `"end"`, `"center"`, `"stretch"`)
24+
25+## Rendering
26+
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 — `CellBuffer.diff()` exists but `cel.ts` always does full redraws (doesn't use diff to skip unchanged cells)
32+- ❌ Full clear + re-render on terminal resize (currently re-renders but doesn't clear scrollback)
33+
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 `string.length` for width — should use `visibleWidth()` for correct CJK/emoji handling
42+- ❌ Overflow clipping (`overflow: "hidden"`) — children aren't clipped to parent bounds
43+- ❌ Scroll rendering (`overflow: "scroll"`) — content offset not applied during painting
44+- ❌ Scrollbar rendering (`scrollbar: true`)
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 — currently only checks the root container, should walk 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 should fire `onFocus`)
61+- ❌ `onFocus`/`onBlur` callbacks not 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 uses `WeakMap` keyed on props — works for single render but may lose cursor position across re-renders since props objects are recreated each frame
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)
88+- ❌ Bracketed paste mode support
89+- ❌ Kitty keyboard protocol detection
90+
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:
110+
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