xonecas.io
70160
Ce

cel-tui / commit 6d974fb

docs: update TODO, AGENTS, SKILL, and JSDoc to match implementation

TODO.md: Replaced completed checklist with focused list of remaining
work — 2 spec violations (Tab key in TextInput, mouse wheel scroll
in TextInput), 2 not-yet-implemented features (bracketed paste,
Kitty keyboard), and future enhancements.

AGENTS.md: Added implementation status summary covering all core
systems (232 tests). Added architecture notes section describing
each source file's responsibility.

SKILL.md: Updated key rules to reflect full focus system (Tab
traversal, Enter activation, click focusing, crash cleanup,
differential rendering).

JSDoc: Fixed examples in cel.ts and index.ts to use correct
import path (ProcessTerminal from @cel-tui/core, not subpath)
and include cel.init() call.

xonecas2026-04-04 6d974fbe64b1fa838b6c95fd293c667335b50abc parent 66b707a

5 files changed

AGENTS.md+25−0
@@ -32,6 +32,20 @@ Dependency chain: `components → core → types`
3232 - **Key bubbling:** Unconsumed keys bubble up from focused element through ancestors. Root `onKeyPress` = global handler.
3333 - **Hit detection:** Topmost layer first, deepest node at (x,y), walk up to find handler. Innermost wins for scroll, click, keys.
3434
35+## Implementation Status
36+
37+All core systems from the spec are implemented and tested (232 tests):
38+
39+- **Layout engine** — flexbox sizing (fixed, intrinsic, flex, percentage), constraints, gap, padding, justifyContent, alignItems, largest-remainder rounding
40+- **Rendering** — cell buffer, ANSI emitter with SGR styling, synchronized output (CSI 2026), differential rendering (emitDiff), full clear on resize
41+- **Painting** — grapheme-aware text rendering (CJK/emoji via visibleWidth), overflow clipping via clip rect propagation, scroll content offsetting, scrollbar indicators
42+- **Input** — key parsing/normalization, SGR mouse events, hit detection, click/scroll routing, focus traversal (Tab/Shift+Tab/Escape/Enter), onKeyPress bubbling from focused element through ancestors
43+- **TextInput** — text editing, cursor movement, cursor persistence across re-renders (keyed on onChange), auto-scroll to keep cursor visible, placeholder rendering
44+- **Layering** — multi-layer compositing, transparency, topmost-layer input priority
45+- **Terminal** — crash cleanup (SIGINT/SIGTERM/uncaughtException), resize clear
46+
47+See `TODO.md` for remaining spec violations and future work.
48+
3549 ## Runtime
3650
3751 - **Bun** for package management and running TypeScript
@@ -123,6 +137,17 @@ chore: scaffold monorepo with types, core, components packages
123137
124138 **Always use `bun` and `bunx` instead of `node`, `npm`, `npx`, or `yarn`.** This is a Bun monorepo — all scripts, package management, and execution should go through Bun.
125139
140+## Architecture Notes
141+
142+- `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal)` starts, `cel.viewport(fn)` sets render function, `cel.render()` requests re-render, `cel.stop()` restores terminal.
143+- `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
144+- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets, scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state.
145+- `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both wrap in CSI 2026 synchronized output.
146+- `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `findKeyPressHandler`, `collectFocusable` walk paths.
147+- `keys.ts` — `parseKey(data)` normalizes terminal input to canonical key strings. `isEditingKey()` identifies keys consumed by TextInput.
148+- `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
149+- `terminal.ts` — `ProcessTerminal` (real I/O, raw mode, SGR mouse, crash cleanup) and `MockTerminal` (testing).
150+
126151 ## Conventions
127152
128153 - All code is TypeScript with strict mode
TODO.md+10−103
@@ -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)
docs/skill/cel-tui/SKILL.md+7−2
@@ -284,9 +284,14 @@ All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`
284284 - **Text is a leaf** — no sizing props, no children. Parent controls the box.
285285 - **TextInput is a container** — accepts sizing props but no children.
286286 - **No style inheritance** — every node sets its own styles explicitly.
287-- **Escape unfocuses**, Tab/Shift+Tab traverses focusable elements.
288-- **TextInput consumes editing keys** when focused. Modifier combos (ctrl+s) bubble up.
287+- **Escape unfocuses** the current element.
288+- **Tab/Shift+Tab** traverses focusable elements in document order (wraps around).
289+- **Enter** activates a focused clickable container (fires onClick).
290+- **TextInput consumes editing keys** when focused (printable chars, arrows, backspace, delete). Modifier combos (ctrl+s) bubble up through ancestors via onKeyPress.
291+- **Mouse click** on a focusable element fires onFocus (and onBlur on previous).
289292 - **Innermost wins** — for click, scroll, and key handlers.
293+- **Differential rendering** — only changed cells are emitted after the first render.
294+- **Crash cleanup** — terminal state is restored on SIGINT, SIGTERM, uncaughtException.
290295
291296 ## Pre-made Components
292297
packages/core/src/cel.ts+1−2
@@ -442,8 +442,7 @@ function findFocusedInTree(ln: LayoutNode): LayoutNode | null {
442442 *
443443 * @example
444444 * ```ts
445- * import { cel, VStack, Text } from "@cel-tui/core";
446- * import { ProcessTerminal } from "@cel-tui/core/terminal";
445+ * import { cel, VStack, Text, ProcessTerminal } from "@cel-tui/core";
447446 *
448447 * cel.init(new ProcessTerminal());
449448 * cel.viewport(() =>
packages/core/src/index.ts+2−1
@@ -9,10 +9,11 @@
99 *
1010 * @example
1111 * ```ts
12- * import { cel, VStack, HStack, Text, TextInput } from "@cel-tui/core";
12+ * import { cel, VStack, HStack, Text, TextInput, ProcessTerminal } from "@cel-tui/core";
1313 *
1414 * let name = "";
1515 *
16+ * cel.init(new ProcessTerminal());
1617 * cel.viewport(() =>
1718 * VStack({ height: "100%" }, [
1819 * Text("What is your name?", { bold: true }),