xonecas.io
70160
Ce

cel-tui / commit 2d099e6

Merge branch 'main' into gh-pages

xonecas2026-04-07 2d099e69ab5d50da49ab24db1b048765e3824208 parent 471b179parent 46745b4

34 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

AGENTS.md+57−10
@@ -203,11 +203,11 @@ chore: scaffold monorepo with types, core, components packages
203203
204204 ## Architecture Notes
205205
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).
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 …
207207 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
208208 - `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.
209209 - `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).
210-- `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
210+- `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.
211211 - `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.
212212 - `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.
213213 - `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
@@ -247,6 +247,14 @@ All three packages share the same version. Bump all together:
247247
248248 Follow [semver](https://semver.org/): patch for fixes, minor for features, major for breaking changes. While `0.x`, minor = breaking is acceptable.
249249
250+**⚠️ Critical: After bumping versions, regenerate the lockfile:**
251+
252+```bash
253+rm bun.lock && bun install
254+```
255+
256+`bun publish` resolves `workspace:*` from `bun.lock`, **not** from `package.json`. If you skip this step, the published packages will depend on the old version. `bun install` alone does NOT update workspace versions in an existing lockfile — you must delete and regenerate it.
257+
250258 ### Publish order
251259
252260 Must publish in dependency order — types first, then core, then components:
@@ -259,20 +267,59 @@ cd ../components && bun publish --access public
259267
260268 If 2FA is enabled, add `--otp <code>` to each command.
261269
270+### Pre-release documentation audit
271+
272+Before every release, run a full alignment audit across all documentation surfaces. The goal is to catch stale versions, false capability claims, signature mismatches, and terminology drift between the spec, code, JSDocs, agent docs, and skill files.
273+
274+**What to read** (in this order — each layer should agree with the ones before it):
275+
276+1. `packages/types/src/index.ts` — the canonical type definitions and their JSDocs
277+2. `packages/core/src/*.ts` — implementation (public function signatures, behavior, exports)
278+3. `packages/core/src/index.ts` — what's actually exported to consumers
279+4. `packages/components/src/*.ts` — component implementations and JSDocs
280+5. `spec.md` — design spec (API tables, prop types, behavior descriptions)
281+6. `AGENTS.md` — architecture notes, module descriptions, conventions
282+7. `README.md` — user-facing overview and feature claims
283+8. `docs/skill/cel-tui/SKILL.md` — agent skill (version, compatibility, patterns, gotchas)
284+9. `docs/skill/cel-tui/references/*.md` — API reference and composing guide
285+10. `TODO.md` — verify listed bugs/violations are still present or mark resolved
286+11. `package.json` files — versions, descriptions, dependency declarations
287+
288+**What to check at each layer:**
289+
290+- **Versions** — skill metadata, package.json files, and any version references all match
291+- **Capability claims** — if docs say "supports X", verify the code actually implements X (e.g., color spaces, protocol levels, sizing strategies)
292+- **Function signatures** — parameter names, types, optional params, return types match between code and docs
293+- **Prop tables** — every prop in the type definition appears in the spec table with the correct type and description
294+- **Terminology** — consistent naming across all surfaces (e.g., `TextNode` vs `Text`, "uncontrolled" vs "framework-managed")
295+- **Behavior descriptions** — bubbling semantics, controlled/uncontrolled modes, default values all match the implementation
296+- **Exports** — what `index.ts` exports matches what docs say is available
297+- **Compatibility/requirements** — terminal requirements, runtime requirements are stated accurately
298+- **TODO.md currency** — bugs listed as open are still present in code; any that were fixed should be removed
299+
300+**After making fixes**, always verify nothing broke:
301+
302+```bash
303+bun run typecheck && bun test && bun run check && bun run format
304+```
305+
262306 ### Pre-publish checklist
263307
264-1. All tests pass: `bun test`
265-2. Types clean: `bun run typecheck`
266-3. Lint/format clean: `bun run check && bun run format`
267-4. Version bumped in all three `package.json` files
268-5. Changes committed and pushed
269-6. Dry run looks correct: `cd packages/core && bun publish --dry-run --access public`
308+1. **Documentation audit passes** (see above)
309+2. All tests pass: `bun test`
310+3. Types clean: `bun run typecheck`
311+4. Lint/format clean: `bun run check && bun run format`
312+5. Version bumped in all three `package.json` files
313+6. Lockfile regenerated: `rm bun.lock && bun install`
314+7. **Pre-publish check passes: `bun run prepublish-check`** (verifies lockfile versions match package.json)
315+8. Changes committed and pushed
316+9. After publishing, **verify on npm**: `npm view @cel-tui/core@<version> dependencies --json`
270317
271318 ### How it works
272319
273320 - `"files"` in each `package.json` whitelists what ships (source only, no tests)
274321 - `"exports"` map provides proper module resolution for Bun and bundlers
275-- `workspace:*` dependencies are resolved to actual versions by `bun publish`
322+- `workspace:*` dependencies are resolved to actual versions by `bun publish` **using versions from `bun.lock`** (not package.json — the lockfile must be regenerated after version bumps)
276323 - `get-east-asian-width` is a real dependency of `@cel-tui/core` (installs for consumers)
277324 - `typescript` is a peer dependency (consumers bring their own)
278325
@@ -288,4 +335,4 @@ More generally: before running any command that could destroy uncommitted work (
288335 - Primitives are functions that return typed Node objects (not classes)
289336 - Components in `packages/components/` are plain functions using core primitives
290337 - Key format: all lowercase, modifiers joined by `+` (e.g., `"ctrl+shift+s"`)
291-- Colors: 16 numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default via `defaultTheme`. Custom themes can remap slots to 256-color or true color. Omit `fgColor`/`bgColor` for terminal defaults. Always pair `bgColor` with `fgColor` for contrast.
338+- Colors: 16 numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default via `defaultTheme`. Custom themes can remap slots to different ANSI indices or 24-bit true color. Omit `fgColor`/`bgColor` for terminal defaults. Always pair `bgColor` with `fgColor` for contrast.
README.md+2−1
@@ -63,8 +63,9 @@ cel.viewport(() =>
6363 - **Flexbox layout** — fixed, flex, percentage, and intrinsic sizing with gap, padding, alignment.
6464 - **Layers** — return an array for multi-layer compositing (modals, overlays).
6565 - **Uncontrolled by default** — focus and scroll just work. Opt into controlled mode when needed.
66+- **Adaptive wheel scrolling** — scrollables and TextInput use an adaptive mouse-wheel step by default; override it with `scrollStep` when needed.
6667 - **Style inheritance** — containers propagate styles to descendants. `bgColor` fills the rect.
67-- **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to 256-color or true color.
68+- **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to different ANSI indices or 24-bit true color.
6869 - **Cell buffer rendering** — styled cells, differential updates, synchronized output.
6970 - **Kitty keyboard protocol** — unambiguous key input with full modifier support. Requires a [compatible terminal](https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement) (Kitty, WezTerm, Ghostty, foot, Alacritty, Windows Terminal).
7071
TODO.md+5−3
@@ -12,9 +12,9 @@ Remaining work, known bugs, and planned improvements.
1212
1313 ## Bugs / Spec Violations
1414
15-- 🔧 **Scrollbar thumb position ignores padding** — `paintScrollbar` in `paint.ts` computes `maxOffset = contentHeight - rect.height` without accounting for container padding, while the scroll clamping logic uses `contentHeight + padY - rect.height`. For padded scrollable containers the thumb position is slightly off.
15+- 🔧 **Streaming wrapped Markdown with inline formatting can corrupt until rendering settles** — high priority. The risky behavior is in `packages/components/src/markdown.ts`: plain paragraphs render as a single `Text(..., { wrap: "word" })`, but formatted paragraphs/list items/blockquote content render as `HStack({ flexWrap: "wrap" })` trees built from split inline spans. During streaming, partial markdown can change shape across renders (for example plain text becoming a formatted span onc …
1616
17-- 🔧 **Duplicate max scroll offset calculation** — `getMaxScrollOffset` in `cel.ts` and `computeMaxScrollOffset` in `paint.ts` implement the same logic. Should be extracted to a shared function.
17+- 🔧 **Scrollbar thumb position ignores padding** — `paintScrollbar` in `paint.ts` computes `maxOffset = contentHeight - rect.height` without accounting for container padding, while the scroll clamping logic uses `contentHeight + padY - rect.height`. For padded scrollable containers the thumb position is slightly off.
1818
1919 - 🔧 **Key events leak through layers** — When no element is focused and the topmost layer's root has no `onKeyPress`, `handleKeyEvent` falls through to lower layers. Mouse input stops at the topmost layer with a node at the event position, but keyboard input doesn't follow the same rule. A modal overlay without its own root `onKeyPress` would leak keys to the base layer, breaking the "events target the topmost layer" principle.
2020
@@ -24,6 +24,8 @@ Remaining work, known bugs, and planned improvements.
2424
2525 ## API Improvements
2626
27+- ❌ **Define TextInput scroll semantics for cursor-follow and resize** — After the text layout refactor, the framework now has one canonical visual wrapping model, but the behavior contract around TextInput scrolling still needs to be specified. In particular: when a user has manually scrolled away from the cursor, what actions should re-enable automatic cursor-follow (typing, cursor movement, focus changes, programmatic value changes)? And when a TextInput changes height because of intrinsi …
28+
2729 - ❌ **`repeat: "fill"` should claim flex space in HStack** — `Text(" ", { repeat: "fill" })` inside an HStack gets width 0 because its intrinsic width is 0 and no flex distributes remaining space. The workaround is `VStack({ flex: 1 }, [Text(" ", { repeat: "fill" })])`, which is non-obvious. Fix: either make `repeat: "fill"` imply flex behavior in the layout engine, or document the workaround prominently. The former is preferred.
2830
2931 ## Not Yet Implemented
@@ -42,7 +44,7 @@ Remaining work, known bugs, and planned improvements.
4244
4345 - 💡 **Scrollbar styling** — Scrollbar characters (`┃`/`│` vertical, `━`/`─` horizontal) and colors are hardcoded in `paintScrollbar`. A `scrollbarStyle` prop on containers (or a global theme option) would allow customizing thumb/track characters and colors. Currently the only two visual elements the framework doesn't support styling.
4446
45-- 💡 **Textarea component** (`packages/components`) — A higher-level wrapper around TextInput that handles the autogrowing pattern out of the box. Props like `maxLines`, `minLines`, `submitKey`, and `placeholder` would cover the common chat-input / form-field use case without requiring the `HStack + flex + maxHeight` boilerplate. Could also include optional line-count display and character limit.
47+- 💡 **Textarea component** (`packages/components`) — A higher-level wrapper around TextInput that handles the autogrowing pattern out of the box. Props like `maxLines`, `minLines`, and `placeholder` would cover the common chat-input / form-field use case without requiring the `HStack + flex + maxHeight` boilerplate. Could also include optional line-count display and character limit.
4648
4749 - 💡 **Editor component** (`packages/components`) — A TextInput with a line-number gutter, built as a component. Would compose an HStack with a fixed-width line-number column (styled, right-aligned) alongside a flex TextInput, keeping scroll synchronized. Useful for code/config editing use cases like the markdown editor example.
4850
benchmarks/RESULTS.md+59−59
@@ -2,7 +2,7 @@
22
33 **Machine:** 12th Gen Intel Core i9-12900, ~4.4 GHz
44 **Runtime:** Bun 1.3.9 (x64-linux)
5-**Date:** 2026-04-04
5+**Date:** 2026-04-05 (updated from 2026-04-04 baseline)
66
77 ## Ink Comparison (caveat emptor)
88
@@ -23,11 +23,11 @@ The comparison is included as a rough reference point, not a claim of
2323 superiority. Ink solves a broader set of problems; cel-tui trades
2424 features for raw throughput.
2525
26-| What | cel-tui | Ink 6.8.0 | Ratio |
27-| ------------------------------------------ | ---------- | ------------------------------------------------- | ---------- |
28-| **Single render (comparable tree, 80×24)** | **65 µs** | 632 µs (`renderToString`) | **~10×** |
29-| **1,000 re-renders** | **64 ms** | 632 ms (`renderToString`) / 1,462 ms (`rerender`) | **10–23×** |
30-| **Projected 100k re-renders** | **~6.4 s** | ~63 s (`renderToString`) / ~146 s (`rerender`) | **10–23×** |
26+| What | cel-tui | Ink 6.8.0 | Ratio |
27+| ------------------------------------------ | ---------- | ------------------------------------------------- | --------- |
28+| **Single render (comparable tree, 80×24)** | **65 µs** | 632 µs (`renderToString`) | **~10×** |
29+| **1,000 re-renders** | **67 ms** | 632 ms (`renderToString`) / 1,462 ms (`rerender`) | **9–22×** |
30+| **Projected 100k re-renders** | **~6.7 s** | ~63 s (`renderToString`) / ~146 s (`rerender`) | **9–22×** |
3131
3232 The Ink benchmark script we used is a custom `renderToString` loop (see
3333 [How to Reproduce](#how-to-reproduce)), not Ink's own shipped benchmark,
@@ -51,11 +51,11 @@ numbers are included above.
5151 | Input | Time |
5252 | ---------------------------- | -------- |
5353 | ASCII short (5 chars) | 4.1 ns |
54-| ASCII (64 chars) | 40.3 ns |
55-| ASCII long (640 chars) | 398.6 ns |
56-| CJK + emoji (26 graphemes) | 26.8 ns |
57-| Mixed ASCII + CJK (60 chars) | 5.1 ns |
58-| ANSI escape sequences | 2.9 ns |
54+| ASCII (64 chars) | 39.1 ns |
55+| ASCII long (640 chars) | 386.6 ns |
56+| CJK + emoji (26 graphemes) | 26.6 ns |
57+| Mixed ASCII + CJK (60 chars) | 4.9 ns |
58+| ANSI escape sequences | 3.2 ns |
5959 | Empty string | 0.1 ns |
6060
6161 The fast ASCII path dominates — pure ASCII strings bypass grapheme segmentation entirely.
@@ -65,17 +65,17 @@ The fast ASCII path dominates — pure ASCII strings bypass grapheme segmentatio
6565 | Tree | Time |
6666 | ----------------------------- | -------- |
6767 | 10 children (flat) | 1.5 µs |
68-| 100 children (flat) | 11.9 µs |
69-| 1,000 children (flat) | 124.5 µs |
68+| 100 children (flat) | 12.0 µs |
69+| 1,000 children (flat) | 125.1 µs |
7070 | depth=3 breadth=3 (40 nodes) | 3.0 µs |
71-| depth=4 breadth=3 (121 nodes) | 15.3 µs |
71+| depth=4 breadth=3 (121 nodes) | 15.1 µs |
7272 | depth=3 breadth=5 (156 nodes) | 9.5 µs |
73-| 50 styled groups (200 nodes) | 49.9 µs |
73+| 50 styled groups (200 nodes) | 52.6 µs |
7474 | 10 word-wrap paragraphs | 2.6 µs |
75-| 50 word-wrap paragraphs | 12.3 µs |
76-| Ink-comparable tree | 1.6 µs |
77-| App tree (20 messages) | 9.9 µs |
78-| App tree (100 messages) | 37.9 µs |
75+| 50 word-wrap paragraphs | 13.1 µs |
76+| Ink-comparable tree | 1.7 µs |
77+| App tree (20 messages) | 10.1 µs |
78+| App tree (100 messages) | 39.6 µs |
7979
8080 Layout scales linearly with node count (~120 ns/node for flat trees).
8181
@@ -83,18 +83,18 @@ Layout scales linearly with node count (~120 ns/node for flat trees).
8383
8484 | Scenario | Time |
8585 | ----------------------------- | ------ |
86-| 10 children (flat, 120×40) | 95 µs |
87-| 100 children (flat, 120×40) | 195 µs |
88-| 1,000 children (flat, 120×40) | 198 µs |
89-| Nested 121 nodes (120×40) | 185 µs |
90-| 50 styled groups (120×40) | 220 µs |
91-| 200 lines scrollable (120×40) | 198 µs |
92-| 50 word-wrapped paragraphs | 283 µs |
93-| Ink-comparable (80×24) | 46 µs |
94-| App tree 20 msgs (120×40) | 187 µs |
95-| 80×24 (small terminal) | 110 µs |
96-| 120×40 (medium terminal) | 209 µs |
97-| 200×50 (large terminal) | 312 µs |
86+| 10 children (flat, 120×40) | 93 µs |
87+| 100 children (flat, 120×40) | 193 µs |
88+| 1,000 children (flat, 120×40) | 192 µs |
89+| Nested 121 nodes (120×40) | 180 µs |
90+| 50 styled groups (120×40) | 207 µs |
91+| 200 lines scrollable (120×40) | 185 µs |
92+| 50 word-wrapped paragraphs | 286 µs |
93+| Ink-comparable (80×24) | 45 µs |
94+| App tree 20 msgs (120×40) | 208 µs |
95+| 80×24 (small terminal) | 109 µs |
96+| 120×40 (medium terminal) | 196 µs |
97+| 200×50 (large terminal) | 284 µs |
9898
9999 Paint is O(cells), not O(nodes) — 100 vs 1,000 children produce similar times because only visible cells are painted. Cost scales with terminal size.
100100
@@ -102,14 +102,14 @@ Paint is O(cells), not O(nodes) — 100 vs 1,000 children produce similar times
102102
103103 | Operation | Time |
104104 | ---------------------------- | -------- |
105-| Buffer creation 80×24 | 24.2 µs |
106-| Buffer creation 120×40 | 58.6 µs |
107-| Buffer creation 200×50 | 122.2 µs |
108-| emitBuffer 80×24 (full) | 19.3 µs |
109-| emitBuffer 120×40 (full) | 46.8 µs |
110-| emitDiff 80×24 (no changes) | 11.6 µs |
111-| emitDiff 80×24 (partial) | 11.9 µs |
112-| emitDiff 80×24 (full change) | 10.7 µs |
105+| Buffer creation 80×24 | 24.7 µs |
106+| Buffer creation 120×40 | 58.2 µs |
107+| Buffer creation 200×50 | 117.0 µs |
108+| emitBuffer 80×24 (full) | 21.4 µs |
109+| emitBuffer 120×40 (full) | 46.4 µs |
110+| emitDiff 80×24 (no changes) | 11.8 µs |
111+| emitDiff 80×24 (partial) | 11.1 µs |
112+| emitDiff 80×24 (full change) | 11.2 µs |
113113
114114 Differential rendering has near-constant cost regardless of change amount — dominated by the comparison scan over all cells.
115115
@@ -117,36 +117,36 @@ Differential rendering has near-constant cost regardless of change amount — do
117117
118118 | Operation | Time |
119119 | ---------------------------- | ------- |
120-| hitTest flat 100, center | 135 ns |
121-| hitTest nested 121, center | 35 ns |
122-| hitTest app 50 msgs, center | 102 ns |
123-| hitTest miss (out of bounds) | 1.5 ns |
124-| collectFocusable 100 buttons | 1.15 µs |
125-| collectFocusable app tree | 1.03 µs |
120+| hitTest flat 100, center | 145 ns |
121+| hitTest nested 121, center | 41 ns |
122+| hitTest app 50 msgs, center | 108 ns |
123+| hitTest miss (out of bounds) | 7.7 ns |
124+| collectFocusable 100 buttons | 1.13 µs |
125+| collectFocusable app tree | 0.96 µs |
126126
127127 ### Key Parsing
128128
129129 | Input | Time |
130130 | --------------------- | ------ |
131-| Printable char 'a' | <1 ns |
132-| Ctrl+C (0x03) | <1 ns |
133-| Escape | <1 ns |
134-| Arrow up (CSI) | 2.7 ns |
135-| Shift+Tab (CSI Z) | 7.6 ns |
136-| F5 (CSI 15~) | 163 ns |
137-| Backspace (0x7F) | 6.8 ns |
138-| normalizeKey "ctrl+s" | 90 ns |
131+| Printable char 'a' | 15 ns |
132+| Ctrl+C (0x03) | 18 ns |
133+| Escape | ~1 ns |
134+| Arrow up (CSI) | 58 ns |
135+| Shift+Tab (CSI Z) | <1 ns |
136+| F5 (CSI 15~) | 111 ns |
137+| Backspace (0x7F) | 7.1 ns |
138+| normalizeKey "ctrl+s" | 84 ns |
139139
140140 ### End-to-End Pipeline
141141
142142 | Scenario | Time | Renders/sec |
143143 | ------------------------- | ------ | ----------- |
144-| Ink-comparable (80×24) | 65 µs | **15,400** |
145-| Flat 100 lines (80×24) | 153 µs | 6,500 |
146-| App tree 20 msgs (120×40) | 267 µs | 3,700 |
147-| Re-render no-change diff | 61 µs | 16,400 |
148-| Re-render +1 message diff | 252 µs | 3,970 |
149-| 1,000 re-renders batch | 64 ms | 15,600 |
144+| Ink-comparable (80×24) | 67 µs | **14,900** |
145+| Flat 100 lines (80×24) | 152 µs | 6,600 |
146+| App tree 20 msgs (120×40) | 268 µs | 3,700 |
147+| Re-render no-change diff | 61 µs | 16,300 |
148+| Re-render +1 message diff | 248 µs | 4,030 |
149+| 1,000 re-renders batch | 67 ms | 14,800 |
150150
151151 ## Ink Raw Numbers
152152
benchmarks/helpers.ts+15−15
@@ -36,17 +36,17 @@ export function styledTree(n: number): ContainerNode {
3636 const children: Node[] = [];
3737 for (let i = 0; i < n; i++) {
3838 children.push(
39- VStack({ fgColor: "cyan", bgColor: "black", padding: { x: 1 } }, [
40- Text(`Styled line ${i}`, { bold: true, fgColor: "yellow" }),
41- HStack({ fgColor: "white" }, [
39+ VStack({ fgColor: "color06", bgColor: "color00", padding: { x: 1 } }, [
40+ Text(`Styled line ${i}`, { bold: true, fgColor: "color03" }),
41+ HStack({ fgColor: "color07" }, [
4242 Text("left "),
43- Text("right", { fgColor: "green" }),
43+ Text("right", { fgColor: "color02" }),
4444 ]),
4545 ]),
4646 );
4747 }
4848 return VStack(
49- { height: "100%", fgColor: "white", bgColor: "blue" },
49+ { height: "100%", fgColor: "color07", bgColor: "color04" },
5050 children,
5151 );
5252 }
@@ -77,7 +77,7 @@ export function wrappedTextTree(paragraphs: number): ContainerNode {
7777 /** Build a tree resembling the Ink benchmark: styled text, flex layout, word-wrap. */
7878 export function inkComparableTree(): ContainerNode {
7979 return VStack({ padding: { y: 1, x: 1 } }, [
80- Text("Hello World", { underline: true, bold: true, fgColor: "red" }),
80+ Text("Hello World", { underline: true, bold: true, fgColor: "color01" }),
8181 VStack({ width: 60 }, [
8282 Text(
8383 "Cupcake ipsum dolor sit amet candy candy. Sesame snaps cookie I love tootsie roll apple pie bonbon wafer. Caramels sesame snaps icing cotton candy I love cookie sweet roll. I love bonbon sweet.",
@@ -85,11 +85,11 @@ export function inkComparableTree(): ContainerNode {
8585 ),
8686 ]),
8787 VStack({}, [
88- Text("Colors:", { fgColor: "black", bgColor: "white" }),
88+ Text("Colors:", { fgColor: "color00", bgColor: "color07" }),
8989 VStack({ padding: { x: 1 } }, [
90- Text("- Red", { fgColor: "red" }),
91- Text("- Blue", { fgColor: "blue" }),
92- Text("- Green", { fgColor: "green" }),
90+ Text("- Red", { fgColor: "color01" }),
91+ Text("- Blue", { fgColor: "color04" }),
92+ Text("- Green", { fgColor: "color02" }),
9393 ]),
9494 ]),
9595 ]);
@@ -101,19 +101,19 @@ export function appTree(messageCount: number): ContainerNode {
101101 for (let i = 0; i < messageCount; i++) {
102102 messages.push(
103103 VStack({}, [
104- Text(`▶ User message ${i}`, { bold: true, fgColor: "blue" }),
104+ Text(`▶ User message ${i}`, { bold: true, fgColor: "color04" }),
105105 Text(
106106 ` This is the content of message ${i}. It can be quite long and detailed.`,
107107 ),
108108 ]),
109109 );
110110 }
111- return VStack({ height: "100%", fgColor: "white" }, [
111+ return VStack({ height: "100%", fgColor: "color07" }, [
112112 // Header
113113 HStack({ height: 1, padding: { x: 1 } }, [
114114 Text("Agent Chat", { bold: true }),
115115 VStack({ flex: 1 }, []),
116- Text("model: gpt", { fgColor: "brightBlack" }),
116+ Text("model: gpt", { fgColor: "color08" }),
117117 ]),
118118 // Body
119119 VStack(
@@ -123,8 +123,8 @@ export function appTree(messageCount: number): ContainerNode {
123123 // Input bar
124124 HStack({ height: 1, padding: { x: 1 }, gap: 1 }, [
125125 Text("> "),
126- Text("type a message...", { fgColor: "brightBlack" }),
127- HStack({ bgColor: "brightBlack" }, [Text("[Send]", { bold: true })]),
126+ Text("type a message...", { fgColor: "color08" }),
127+ HStack({ bgColor: "color08" }, [Text("[Send]", { bold: true })]),
128128 ]),
129129 ]);
130130 }
bun.lock+14−14
@@ -17,7 +17,7 @@
1717 },
1818 "packages/components": {
1919 "name": "@cel-tui/components",
20- "version": "0.1.0",
20+ "version": "0.4.0",
2121 "dependencies": {
2222 "@cel-tui/core": "workspace:*",
2323 "@cel-tui/types": "workspace:*",
@@ -29,7 +29,7 @@
2929 },
3030 "packages/core": {
3131 "name": "@cel-tui/core",
32- "version": "0.1.0",
32+ "version": "0.4.0",
3333 "dependencies": {
3434 "@cel-tui/types": "workspace:*",
3535 "get-east-asian-width": "^1.5.0",
@@ -40,7 +40,7 @@
4040 },
4141 "packages/types": {
4242 "name": "@cel-tui/types",
43- "version": "0.1.0",
43+ "version": "0.4.0",
4444 "peerDependencies": {
4545 "typescript": ">=5.0.0",
4646 },
@@ -105,27 +105,27 @@
105105
106106 "get-east-asian-width": ["get-east-asian-width@1.5.0", "", {}, "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA=="],
107107
108- "lefthook": ["lefthook@2.1.4", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.4", "lefthook-darwin-x64": "2.1.4", "lefthook-freebsd-arm64": "2.1.4", "lefthook-freebsd-x64": "2.1.4", "lefthook-linux-arm64": "2.1.4", "lefthook-linux-x64": "2.1.4", "lefthook-openbsd-arm64": "2.1.4", "lefthook-openbsd-x64": "2.1.4", "lefthook-windows-arm64": "2.1.4", "lefthook-windows-x64": "2.1.4" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-JNfJ5gAn0KADvJ1I6/xMcx70+/6TL6U9gqGkKvPw5RNMfatC …
108+ "lefthook": ["lefthook@2.1.5", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.5", "lefthook-darwin-x64": "2.1.5", "lefthook-freebsd-arm64": "2.1.5", "lefthook-freebsd-x64": "2.1.5", "lefthook-linux-arm64": "2.1.5", "lefthook-linux-x64": "2.1.5", "lefthook-openbsd-arm64": "2.1.5", "lefthook-openbsd-x64": "2.1.5", "lefthook-windows-arm64": "2.1.5", "lefthook-windows-x64": "2.1.5" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-yB9IFWurFllusbPZqvG0EavTmpNXPya2MuO7Li7YT78xAj3u …
109109
110- "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.1.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-BUAAE9+rUrjr39a+wH/1zHmGrDdwUQ2Yq/z6BQbM/yUb9qtXBRcQ5eOXxApqWW177VhGBpX31aqIlfAZ5Q7wzw=="],
110+ "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.1.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-VITTaw8PxxyE26gkZ8UcwIa5ZrWnKNRGLeeSrqri40cQdXvLTEoMq2tjjw7eiL9UcB0waRReDdzydevy9GOPUQ=="],
111111
112- "lefthook-darwin-x64": ["lefthook-darwin-x64@2.1.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-K1ncIMEe84fe+ss1hQNO7rIvqiKy2TJvTFpkypvqFodT7mJXZn7GLKYTIXdIuyPAYthRa9DwFnx5uMoHwD2F1Q=="],
112+ "lefthook-darwin-x64": ["lefthook-darwin-x64@2.1.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-AvtjYiW0BSGHBGrdvL313seUymrW9FxI+6JJwJ+ZSaa2sH81etrTB0wAwlH1L9VfFwK9+gWvatZBvLfF3L4fPw=="],
113113
114- "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.1.4", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-PVUhjOhVN71YaYsVdQyNbFZ4a2jFB2Tg5hKrrn9kaWpx64aLz/XivLjwr8sEuTaP1GRlEWBpW6Bhrcsyo39qFw=="],
114+ "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.1.5", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-mXjJwe8jKGWGiBYUxfQY1ab3Nn5NhafqT9q3KJz8m5joGGQj4JD0cbWxF1nVBLBWsDGbWZRZunTCMGcIScT2bQ=="],
115115
116- "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.1.4", "", { "os": "freebsd", "cpu": "x64" }, "sha512-ZWV9o/LeyWNEBoVO+BhLqxH3rGTba05nkm5NvMjEFSj7LbUNUDbQmupZwtHl1OMGJO66eZP0CalzRfUH6GhBxQ=="],
116+ "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.1.5", "", { "os": "freebsd", "cpu": "x64" }, "sha512-exD69dCjc1K45BxatDPGoH4NmEvgLKPm4kJLOWn1fTeHRKZwWiFPwnjknEoG2OemlCDHmCU++5X40kMEG0WBlA=="],
117117
118- "lefthook-linux-arm64": ["lefthook-linux-arm64@2.1.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-iWN0pGnTjrIvNIcSI1vQBJXUbybTqJ5CLMniPA0olabMXQfPDrdMKVQe+mgdwHK+E3/Y0H0ZNL3lnOj6Sk6szA=="],
118+ "lefthook-linux-arm64": ["lefthook-linux-arm64@2.1.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-57TDKC5ewWpsCLZQKIJMHumFEObYKVundmPpiWhX491hINRZYYOL/26yrnVnNcidThRzTiTC+HLcuplLcaXtbA=="],
119119
120- "lefthook-linux-x64": ["lefthook-linux-x64@2.1.4", "", { "os": "linux", "cpu": "x64" }, "sha512-96bTBE/JdYgqWYAJDh+/e/0MaxJ25XTOAk7iy/fKoZ1ugf6S0W9bEFbnCFNooXOcxNVTan5xWKfcjJmPIKtsJA=="],
120+ "lefthook-linux-x64": ["lefthook-linux-x64@2.1.5", "", { "os": "linux", "cpu": "x64" }, "sha512-bqK3LrAB5l5YaCaoHk6qRWlITrGWzP4FbwRxA31elbxjd0wgNWZ2Sn3zEfSEcxz442g7/PPkEwqqsTx0kSFzpg=="],
121121
122- "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.1.4", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-oYUoK6AIJNEr9lUSpIMj6g7sWzotvtc3ryw7yoOyQM6uqmEduw73URV/qGoUcm4nqqmR93ZalZwR2r3Gd61zvw=="],
122+ "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.1.5", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-5aSwK7vV3A6t0w9PnxCMiVjQlcvopBP50BtmnnLnNJyAYHnFbZ0Baq5M0WkE9IsUkWSux0fe6fd0jDkuG711MA=="],
123123
124- "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.1.4", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i/Dv9Jcm68y9cggr1PhyUhOabBGP9+hzQPoiyOhKks7y9qrJl79A8XfG6LHekSuYc2VpiSu5wdnnrE1cj2nfTg=="],
124+ "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.1.5", "", { "os": "openbsd", "cpu": "x64" }, "sha512-Y+pPdDuENJ8qWnUgL02xxhpjblc0WnwXvWGfqnl3WZrAgHzQpwx3G6469RID/wlNVdHYAlw3a8UkFSMYsTzXvA=="],
125125
126- "lefthook-windows-arm64": ["lefthook-windows-arm64@2.1.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-hSww7z+QX4YMnw2lK7DMrs3+w7NtxksuMKOkCKGyxUAC/0m1LAICo0ZbtdDtZ7agxRQQQ/SEbzFRhU5ysNcbjA=="],
126+ "lefthook-windows-arm64": ["lefthook-windows-arm64@2.1.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-2PlcFBjTzJaMufw0c28kfhB/0zmaRCU0TRPPsil/HU2YNOExod4upPGLk9qjgsOmb2YVWFz6zq6u7+D1yqmzTQ=="],
127127
128- "lefthook-windows-x64": ["lefthook-windows-x64@2.1.4", "", { "os": "win32", "cpu": "x64" }, "sha512-eE68LwnogxwcPgGsbVGPGxmghyMGmU9SdGwcc+uhGnUxPz1jL89oECMWJNc36zjVK24umNeDAzB5KA3lw1MuWw=="],
128+ "lefthook-windows-x64": ["lefthook-windows-x64@2.1.5", "", { "os": "win32", "cpu": "x64" }, "sha512-yiAh8qxml6uqy10jDxOdN9fOQpyLxBFY1fgCEAhn7sVJYmJKRhjqSBwZX6LG5MQjzr29KStrIdw7TR3lf3rT7Q=="],
129129
130130 "linkify-it": ["linkify-it@5.0.0", "", { "dependencies": { "uc.micro": "^2.0.0" } }, "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ=="],
131131
docs/skill/cel-tui/SKILL.md+17−5
@@ -2,10 +2,10 @@
22 name: cel-tui
33 description: Build terminal user interfaces with cel-tui, a TypeScript TUI framework. Use when the user wants to create a TUI app, build a terminal UI, render text in the terminal, create a CLI with interactive elements, build a chat interface, text editor, or any interactive terminal application. Triggers include "build a TUI", "terminal UI", "interactive CLI", "text-based interface", "render to terminal", or any task requiring a programmatic terminal user interface.
44 license: MIT
5-compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
5+compatibility: Requires Bun runtime and a terminal supporting the Kitty keyboard protocol and SGR mouse mode.
66 metadata:
77 author: sacenox
8- version: "0.2.0"
8+ version: "0.4.0"
99 ---
1010
1111 # Building TUIs with cel-tui
@@ -75,7 +75,7 @@ The steps: `cel.init(terminal)` → `cel.viewport(() => tree)` → mutate state
7575 | `Text(content, props?)` | Leaf | Styled text, no children |
7676 | `TextInput(props)` | Container (no children) | Multi-line editable text |
7777
78-Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to true color via `cel.init(terminal, { theme })`.
78+Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`, `scrollStep`, `scrollOffset`, `onScroll`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to different …
7979
8080 Read [references/api.md](references/api.md) for the full props listing, sizing strategies, text props, and component reference.
8181
@@ -103,6 +103,17 @@ Scroll is **uncontrolled by default** — the framework manages scroll position
103103 VStack({ overflow: "scroll", scrollbar: true }, [...items]);
104104 ```
105105
106+Mouse wheel scrolling uses an **adaptive step** by default based on the scroll target's visible main-axis viewport size:
107+
108+- `floor(viewportMainAxis / 3)`
109+- clamped to `3..8`
110+
111+Override it with `scrollStep` when a view should scroll faster or slower:
112+
113+```ts
114+VStack({ overflow: "scroll", scrollbar: true, scrollStep: 6 }, [...items]);
115+```
116+
106117 Provide `scrollOffset` + `onScroll` to opt into **controlled mode** — you own the state:
107118
108119 ```ts
@@ -122,7 +133,7 @@ VStack(
122133 );
123134 ```
124135
125-Controlled mode enables patterns like auto-scroll to bottom on new content.
136+Controlled mode enables patterns like auto-scroll to bottom on new content. `scrollStep` affects mouse wheel input only — not programmatic `scrollOffset` updates.
126137
127138 ### Layers (modals)
128139
@@ -214,11 +225,12 @@ mySelect.reset(); // clear filter/highlight programmatically
214225
215226 - **State is external** — the framework has no state. Mutate variables then call `cel.render()`.
216227 - **Text is a pure leaf** — no sizing props, no children. Parent controls the box.
217-- **TextInput consumes editing keys** when focused (printable chars, arrows, backspace). Modifier combos (`ctrl+s`) bubble up through ancestors via `onKeyPress`.
228+- **TextInput consumes editing keys** when focused (printable chars, arrows, backspace, Enter, Tab). Enter inserts a newline by default. Use `onKeyPress` on TextInput to intercept keys before editing — return `false` to prevent the default action (e.g., intercept Enter for submit). Modifier combos (`ctrl+s`) are not editing keys and bubble up through ancestors via `onKeyPress`.
218229 - **Escape unfocuses** the current element. Tab/Shift+Tab traverses focusable elements (wraps around). After Escape, traversal continues from where focus was lost.
219230 - **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
220231 - **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
221232 - **Innermost handler wins** — for `onClick` and `onScroll`. For `onKeyPress`, keys **bubble up** through ancestors: return `false` from a handler to let the key continue to the next ancestor. Returning `void`/`undefined` consumes the key (stops bubbling). This is backward-compatible.
233+- **Mouse wheel step is adaptive by default** — scrollable containers and `TextInput` use `floor(viewportMainAxis / 3)`, clamped to `3..8`. Set `scrollStep` to override it for a specific view.
222234 - **Container `bgColor`** fills the rect with opaque background before painting children. Always pair `bgColor` with `fgColor` for contrast — terminal default fg is designed for the terminal default bg, not for arbitrary palette backgrounds.
223235 - **Colors are numbered slots** (`"color00"`–`"color15"`), not names. The default theme maps to ANSI 16. Omit `fgColor`/`bgColor` for terminal defaults (guaranteed readable across themes).
224236 - **`repeat: "fill"` in HStack** gets width 0 (intrinsic width is 0). Workaround: wrap in `VStack({ flex: 1 }, [Text(" ", { repeat: "fill" })])`.
docs/skill/cel-tui/references/api.md+25−7
@@ -17,6 +17,7 @@ All props accepted by `VStack` and `HStack`:
1717 alignItems, // "start" | "end" | "center" | "stretch"
1818 overflow, // "hidden" (default) | "scroll"
1919 scrollbar, // boolean
20+ scrollStep, // number (mouse wheel step in cells; default adaptive)
2021 scrollOffset, // number (controlled scroll)
2122 onScroll, // (offset: number, maxOffset: number) => void
2223 flexWrap, // "nowrap" (default) | "wrap" (HStack only)
@@ -61,7 +62,9 @@ VStack(
6162
6263 - Scroll direction follows the container’s main axis: VStack → vertical, HStack → horizontal.
6364 - Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
64-- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering).
65+- Mouse wheel scrolling uses an adaptive default step based on the scroll target's visible main-axis viewport size: `floor(viewportMainAxis / 3)`, clamped to `3..8`.
66+- Set `scrollStep` to override the mouse wheel step for a specific scrollable or `TextInput`.
67+- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering). `scrollStep` affects mouse wheel input only.
6568
6669 ## Text Props
6770
@@ -77,7 +80,7 @@ Text("content", {
7780 });
7881 ```
7982
80-Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to 256-color or true color. Omit a color prop for the terminal default.
83+Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to different ANSI indices or 24-bit true color. Omit a color prop for the terminal default.
8184
8285 ## TextInput Props
8386
@@ -85,10 +88,25 @@ Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to
8588 TextInput({
8689 value, // string (controlled)
8790 onChange, // (value: string) => void
88- onSubmit, // () => void
89- submitKey, // string (default "enter")
91+ onKeyPress, // (key: string) => boolean | void — return false to prevent default editing action
9092 placeholder, // Text() node shown when empty
91- // + all container props (sizing, styling, focus, etc.)
93+ // + all container props (sizing, styling, focus, scrollStep, etc.)
94+});
95+```
96+
97+Enter inserts a newline by default. Use `onKeyPress` to intercept keys before editing:
98+
99+```ts
100+// Enter submits instead of inserting newline
101+TextInput({
102+ value: input,
103+ onChange: handleChange,
104+ onKeyPress: (key) => {
105+ if (key === "enter") {
106+ handleSend();
107+ return false;
108+ }
109+ },
92110 });
93111 ```
94112
@@ -107,7 +125,7 @@ Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
107125
108126 Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
109127
110-TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.).
128+TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.) plus container scroll props like `scrollStep` for mouse wheel behavior.
111129
112130 ## Key Format
113131
@@ -228,7 +246,7 @@ Streaming works naturally — append chunks and call `cel.render()`. Unclosed bl
228246
229247 ## Theme
230248
231-The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to 256-color or 24-bit hex:
249+The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to different ANSI indices or 24-bit hex:
232250
233251 ```ts
234252 import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
examples/chat.ts+6−1
@@ -280,7 +280,12 @@ cel.viewport(() =>
280280 value: input,
281281 onChange: handleChange,
282282 placeholder: Text("type a message...", { fgColor: "color08" }),
283- onSubmit: handleSend,
283+ onKeyPress: (key) => {
284+ if (key === "enter") {
285+ handleSend();
286+ return false;
287+ }
288+ },
284289 focused: inputFocused,
285290 onFocus: () => {
286291 inputFocused = true;
examples/markdown-editor.ts+1−1
@@ -3,7 +3,7 @@
33 *
44 * A split-pane markdown editor with live preview, showcasing:
55 * - Custom color theme (Catppuccin Mocha via true color)
6- * - Large multi-line TextInput with ctrl+enter submit
6+ * - Large multi-line TextInput editor
77 * - Live Markdown rendering (source ↔ preview)
88 * - Split-pane layout with VDivider
99 * - Scrollable preview pane
examples/pet.ts+6−4
@@ -484,10 +484,12 @@ function createView() {
484484 nameInputFocused = false;
485485 cel.render();
486486 },
487- submitKey: "enter",
488- onSubmit: () => {
489- nameInputFocused = false;
490- cel.render();
487+ onKeyPress: (key) => {
488+ if (key === "enter") {
489+ nameInputFocused = false;
490+ cel.render();
491+ return false;
492+ }
491493 },
492494 }),
493495
package.json+2−1
@@ -11,7 +11,8 @@
1111 "format:fix": "prettier --write .",
1212 "typecheck": "tsc --noEmit",
1313 "bench": "bun run benchmarks/run-all.ts",
14- "docs": "typedoc --out docs/html && typedoc --out docs/md --plugin typedoc-plugin-markdown"
14+ "docs": "typedoc --out docs/html && typedoc --out docs/md --plugin typedoc-plugin-markdown",
15+ "prepublish-check": "bun run scripts/prepublish-check.ts"
1516 },
1617 "devDependencies": {
1718 "@biomejs/biome": "^2.4.10",
packages/components/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@cel-tui/components",
3- "version": "0.2.0",
3+ "version": "0.4.0",
44 "description": "Pre-made components for cel-tui — Button, Spacer, Divider, VDivider, Select, Markdown",
55 "type": "module",
66 "module": "src/index.ts",
packages/core/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@cel-tui/core",
3- "version": "0.2.0",
3+ "version": "0.4.0",
44 "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
55 "type": "module",
66 "module": "src/index.ts",
packages/core/src/cel.test.ts+184−46
@@ -186,66 +186,57 @@ describe("cel end-to-end", () => {
186186 expect(receivedKey).toBe("ctrl+s");
187187 });
188188
189- test("onScroll fires on mouse wheel", async () => {
190- const term = setup(20, 5);
189+ test("onScroll fires on mouse wheel using the adaptive default step", async () => {
190+ const term = setup(20, 12);
191191 let scrollOffset = 0;
192192 cel.viewport(() =>
193193 VStack(
194194 {
195195 width: 20,
196- height: 5,
196+ height: 12,
197197 overflow: "scroll",
198198 scrollOffset: scrollOffset,
199199 onScroll: (offset) => {
200200 scrollOffset = offset;
201201 },
202202 },
203- // Enough content to exceed viewport (5 rows)
204- Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
203+ // 12-row viewport → adaptive wheel step = floor(12 / 3) = 4
204+ Array.from({ length: 20 }, (_, i) => Text(`line ${i + 1}`)),
205205 ),
206206 );
207207 await waitForRender();
208208
209- // SGR scroll down at (3, 2): ESC [ < 65 ; 4 ; 3 M
210209 term.sendInput("\x1b[<65;4;3M");
211210 await waitForRender();
212211
213- expect(scrollOffset).toBe(1);
212+ expect(scrollOffset).toBe(4);
214213 });
215214
216215 test("batched mouse scroll events are all processed", async () => {
217- const term = setup(20, 5);
216+ const term = setup(20, 12);
218217 let scrollOffset = 0;
219218 cel.viewport(() =>
220219 VStack(
221220 {
222221 width: 20,
223- height: 5,
222+ height: 12,
224223 overflow: "scroll",
225224 scrollOffset: scrollOffset,
226225 onScroll: (offset) => {
227226 scrollOffset = offset;
228227 },
229228 },
230- [
231- Text("line1"),
232- Text("line2"),
233- Text("line3"),
234- Text("line4"),
235- Text("line5"),
236- Text("line6"),
237- Text("line7"),
238- Text("line8"),
239- ],
229+ Array.from({ length: 30 }, (_, i) => Text(`line${i + 1}`)),
240230 ),
241231 );
242232 await waitForRender();
243233
244234 // 3 scroll-down events batched in one data chunk (as real terminals do)
235+ // 12-row viewport → adaptive wheel step = 4, so total = 12
245236 term.sendInput("\x1b[<65;4;3M\x1b[<65;4;3M\x1b[<65;4;3M");
246237 await waitForRender();
247238
248- expect(scrollOffset).toBe(3);
239+ expect(scrollOffset).toBe(12);
249240 });
250241
251242 test("scroll clamps at max offset (no blank space past content)", async () => {
@@ -278,14 +269,14 @@ describe("cel end-to-end", () => {
278269 });
279270
280271 test("onScroll receives maxOffset", async () => {
281- const term = setup(20, 5);
272+ const term = setup(20, 12);
282273 let scrollOffset = 0;
283274 let receivedMax = -1;
284275 cel.viewport(() =>
285276 VStack(
286277 {
287278 width: 20,
288- height: 5,
279+ height: 12,
289280 overflow: "scroll",
290281 scrollOffset: scrollOffset,
291282 onScroll: (offset, maxOffset) => {
@@ -293,8 +284,35 @@ describe("cel end-to-end", () => {
293284 receivedMax = maxOffset;
294285 },
295286 },
296- // 8 items in 5-row viewport → max offset = 3
297- Array.from({ length: 8 }, (_, i) => Text(`item ${i + 1}`)),
287+ // 20 items in 12-row viewport → max offset = 8
288+ Array.from({ length: 20 }, (_, i) => Text(`item ${i + 1}`)),
289+ ),
290+ );
291+ await waitForRender();
292+
293+ term.sendInput("\x1b[<65;4;3M");
294+ await waitForRender();
295+
296+ expect(scrollOffset).toBe(4);
297+ expect(receivedMax).toBe(8);
298+ });
299+
300+ test("scrollStep overrides the adaptive default", async () => {
301+ const term = setup(20, 12);
302+ let scrollOffset = 0;
303+ cel.viewport(() =>
304+ VStack(
305+ {
306+ width: 20,
307+ height: 12,
308+ overflow: "scroll",
309+ scrollStep: 6,
310+ scrollOffset: scrollOffset,
311+ onScroll: (offset) => {
312+ scrollOffset = offset;
313+ },
314+ },
315+ Array.from({ length: 30 }, (_, i) => Text(`line ${i + 1}`)),
298316 ),
299317 );
300318 await waitForRender();
@@ -302,20 +320,19 @@ describe("cel end-to-end", () => {
302320 term.sendInput("\x1b[<65;4;3M");
303321 await waitForRender();
304322
305- expect(scrollOffset).toBe(1);
306- expect(receivedMax).toBe(3);
323+ expect(scrollOffset).toBe(6);
307324 });
308325
309326 test("uncontrolled scroll works without onScroll", async () => {
310- const term = setup(20, 5);
327+ const term = setup(20, 12);
311328 cel.viewport(() =>
312329 VStack(
313330 {
314331 width: 20,
315- height: 5,
332+ height: 12,
316333 overflow: "scroll",
317334 },
318- Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
335+ Array.from({ length: 20 }, (_, i) => Text(`line ${i + 1}`)),
319336 ),
320337 );
321338 await waitForRender();
@@ -324,16 +341,14 @@ describe("cel end-to-end", () => {
324341 const buf1 = cel._getBuffer()!;
325342 expect(buf1.get(0, 0).char).toBe("l"); // "line 1"
326343
327- // SGR scroll down at (3, 2): ESC [ < 65 ; 4 ; 3 M
328344 term.sendInput("\x1b[<65;4;3M");
329345 await waitForRender();
330346
331- // After scroll by 1, line 2 should now be at row 0
347+ // After scrolling by the adaptive step (4), line 5 should now be at row 0
332348 const buf2 = cel._getBuffer()!;
333- // Read first 6 chars of row 0
334349 let row0 = "";
335350 for (let x = 0; x < 6; x++) row0 += buf2.get(x, 0).char;
336- expect(row0).toBe("line 2");
351+ expect(row0).toBe("line 5");
337352 });
338353
339354 test("uncontrolled scroll clamps at max offset", async () => {
@@ -397,6 +412,42 @@ describe("cel end-to-end", () => {
397412
398413 expect(scrollOffset).toBe(2);
399414 });
415+
416+ test("scroll up unsticks from Infinity scrollOffset (sticky-bottom pattern)", async () => {
417+ const term = setup(20, 5);
418+ let scrollOffset = 0;
419+ let stickToBottom = true;
420+
421+ cel.viewport(() =>
422+ VStack(
423+ {
424+ width: 20,
425+ height: 5,
426+ overflow: "scroll",
427+ scrollbar: true,
428+ scrollOffset: stickToBottom ? Infinity : scrollOffset,
429+ onScroll: (offset, maxOffset) => {
430+ scrollOffset = offset;
431+ stickToBottom = offset >= maxOffset;
432+ cel.render();
433+ },
434+ },
435+ // 10 items in 5-row viewport → max offset = 5, adaptive wheel step = 3
436+ Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
437+ ),
438+ );
439+ await waitForRender();
440+
441+ // Initially stuck to bottom (Infinity → clamped to maxOffset=5)
442+ expect(stickToBottom).toBe(true);
443+
444+ // Scroll up — should unstick from bottom
445+ term.sendInput("\x1b[<64;4;3M");
446+ await waitForRender();
447+
448+ expect(stickToBottom).toBe(false);
449+ expect(scrollOffset).toBe(2); // maxOffset(5) - 3 = 2
450+ });
400451 });
401452
402453 describe("focus system", () => {
@@ -916,6 +967,90 @@ describe("cel end-to-end", () => {
916967 expect(value).toBe("hello\t");
917968 });
918969
970+ test("Shift+Enter inserts newline in TextInput", async () => {
971+ const term = setup(20, 5);
972+ let value = "hello";
973+ cel.viewport(() =>
974+ VStack({ width: 20, height: 5 }, [
975+ TextInput({
976+ value,
977+ focused: true,
978+ onChange: (v) => {
979+ value = v;
980+ },
981+ }),
982+ ]),
983+ );
984+ await waitForRender();
985+
986+ // Shift+Enter should insert a newline at cursor position
987+ term.sendInput(kittyEncode("shift+enter"));
988+ await waitForRender();
989+ expect(value).toBe("hello\n");
990+ });
991+
992+ test("Shift+Enter inserts newline at cursor, not just at end", async () => {
993+ const term = setup(20, 5);
994+ let value = "hello";
995+ // Stable onChange ref so cursor state persists across re-renders
996+ const onChange = (v: string) => {
997+ value = v;
998+ };
999+ cel.viewport(() =>
1000+ VStack({ width: 20, height: 5 }, [
1001+ TextInput({
1002+ value,
1003+ focused: true,
1004+ onChange,
1005+ }),
1006+ ]),
1007+ );
1008+ await waitForRender();
1009+
1010+ // Move cursor left 3 times (to position 2: "he|llo")
1011+ term.sendInput(kittyEncode("left"));
1012+ await waitForRender();
1013+ term.sendInput(kittyEncode("left"));
1014+ await waitForRender();
1015+ term.sendInput(kittyEncode("left"));
1016+ await waitForRender();
1017+
1018+ // Shift+Enter should insert newline at cursor
1019+ term.sendInput(kittyEncode("shift+enter"));
1020+ await waitForRender();
1021+ expect(value).toBe("he\nllo");
1022+ });
1023+
1024+ test("Shift+Enter inserts newline even when onKeyPress intercepts Enter", async () => {
1025+ const term = setup(20, 5);
1026+ let value = "hello";
1027+ let submitted = false;
1028+ cel.viewport(() =>
1029+ VStack({ width: 20, height: 5 }, [
1030+ TextInput({
1031+ value,
1032+ focused: true,
1033+ onChange: (v) => {
1034+ value = v;
1035+ },
1036+ onKeyPress: (key) => {
1037+ if (key === "enter") {
1038+ submitted = true;
1039+ return false;
1040+ }
1041+ },
1042+ }),
1043+ ]),
1044+ );
1045+ await waitForRender();
1046+
1047+ // Shift+Enter is a different key — should insert newline, not trigger onKeyPress for "enter"
1048+ term.sendInput(kittyEncode("shift+enter"));
1049+ await waitForRender();
1050+ expect(submitted).toBe(false);
1051+ expect(value).toBe("hello\n");
1052+ });
1053+
9191054 test("Shift+Tab does not traverse focus when TextInput is focused", async () => {
9201055 const term = setup(20, 5);
9211056 let value = "hello";
@@ -1131,18 +1266,20 @@ describe("cel end-to-end", () => {
11311266
11321267 describe("TextInput mouse wheel scroll", () => {
11331268 test("mouse wheel scrolls TextInput content", async () => {
1134- const term = setup(20, 3);
1135- let value = "line1\nline2\nline3\nline4\nline5";
1269+ const term = setup(20, 12);
1270+ let value = Array.from({ length: 20 }, (_, i) => `line${i + 1}`).join(
1271+ "\n",
1272+ );
11361273 // Stable onChange ref so TextInput scroll state persists across re-renders
11371274 const onChange = (v: string) => {
11381275 value = v;
11391276 };
Cut short: this commit's diff is over 1000 lines.
packages/core/src/cel.ts+61−80
Cut short: this commit's diff is over 1000 lines.
packages/core/src/emitter.test.ts+38−1
Cut short: this commit's diff is over 1000 lines.
packages/core/src/emitter.ts+65−6
Cut short: this commit's diff is over 1000 lines.
packages/core/src/keys.test.ts+4−0
Cut short: this commit's diff is over 1000 lines.
packages/core/src/keys.ts+1−0
Cut short: this commit's diff is over 1000 lines.
packages/core/src/layout.test.ts+17−1
Cut short: this commit's diff is over 1000 lines.
packages/core/src/layout.ts+7−24
Cut short: this commit's diff is over 1000 lines.
packages/core/src/paint.test.ts+42−1
Cut short: this commit's diff is over 1000 lines.
packages/core/src/paint.ts+13−151
Cut short: this commit's diff is over 1000 lines.
packages/core/src/primitives/text-input.ts+8−4
Cut short: this commit's diff is over 1000 lines.
packages/core/src/scroll.test.ts+89−0
Cut short: this commit's diff is over 1000 lines.
packages/core/src/scroll.ts+77−0
Cut short: this commit's diff is over 1000 lines.
packages/core/src/text-input.test.ts+173−13
Cut short: this commit's diff is over 1000 lines.
packages/core/src/text-layout.test.ts+48−0
Cut short: this commit's diff is over 1000 lines.
packages/core/src/text-layout.ts+250−0
Cut short: this commit's diff is over 1000 lines.
packages/types/package.json+1−1
Cut short: this commit's diff is over 1000 lines.
packages/types/src/index.ts+23−12
Cut short: this commit's diff is over 1000 lines.
scripts/prepublish-check.ts+122−0
Cut short: this commit's diff is over 1000 lines.
spec.md+42−14
Cut short: this commit's diff is over 1000 lines.