@@ -0,0 +1,224 @@
1+# cel-tui Benchmark Results
2+
3+**Machine:** 12th Gen Intel Core i9-12900, ~4.4 GHz
4+**Runtime:** Bun 1.3.9 (x64-linux)
5+**Date:** 2026-04-04
6+
7+## Ink Comparison (caveat emptor)
8+
9+These numbers compare cel-tui's end-to-end pipeline against Ink using a
10+visually similar tree (styled text, flexbox columns, word-wrap, nested
11+containers with colors — the same shape as Ink's own `benchmark/simple`).
12+
13+**This is not an apples-to-apples comparison.** Ink is a React-based
14+framework that does significantly more work per render: JSX → React
15+reconciliation → Yoga layout (C++ via NAPI) → segment compositing →
16+ANSI output. It supports React hooks, component lifecycle, concurrent
17+mode, and a rich ecosystem of composable components. cel-tui is a
18+minimal stateless framework that builds plain JS objects and writes
19+cells into a flat buffer — it's a fundamentally different (and much
20+simpler) architecture.
21+
22+The comparison is included as a rough reference point, not a claim of
23+superiority. Ink solves a broader set of problems; cel-tui trades
24+features for raw throughput.
25+
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×** |
31+
32+The Ink benchmark script we used is a custom `renderToString` loop (see
33+[How to Reproduce](#how-to-reproduce)), not Ink's own shipped benchmark,
34+which does 100k `rerender()` calls that also write to stdout. Both
35+numbers are included above.
36+
37+### What each framework does per render
38+
39+| Step | cel-tui | Ink |
40+| -------------------- | -------------------------------- | ------------------------------- |
41+| Tree construction | Plain JS objects (~0 cost) | React.createElement + JSX |
42+| Layout | Custom flexbox (TypeScript) | Yoga (C++ via NAPI) |
43+| Painting | Cell buffer (typed array writes) | Segment compositor (string ops) |
44+| Output | ANSI emitter (string concat) | ANSI string builder (chalk) |
45+| State reconciliation | None (stateless) | React reconciler |
46+
47+## cel-tui Pipeline Breakdown
48+
49+### visibleWidth (character measurement)
50+
51+| Input | Time |
52+| ---------------------------- | -------- |
53+| 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 |
59+| Empty string | 0.1 ns |
60+
61+The fast ASCII path dominates — pure ASCII strings bypass grapheme segmentation entirely.
62+
63+### Layout Engine
64+
65+| Tree | Time |
66+| ----------------------------- | -------- |
67+| 10 children (flat) | 1.5 µs |
68+| 100 children (flat) | 11.9 µs |
69+| 1,000 children (flat) | 124.5 µs |
70+| depth=3 breadth=3 (40 nodes) | 3.0 µs |
71+| depth=4 breadth=3 (121 nodes) | 15.3 µs |
72+| depth=3 breadth=5 (156 nodes) | 9.5 µs |
73+| 50 styled groups (200 nodes) | 49.9 µs |
74+| 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 |
79+
80+Layout scales linearly with node count (~120 ns/node for flat trees).
81+
82+### Paint (cell buffer writing)
83+
84+| Scenario | Time |
85+| ----------------------------- | ------ |
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 |
98+
99+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.
100+
101+### CellBuffer & ANSI Emission
102+
103+| Operation | Time |
104+| ---------------------------- | -------- |
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 |
113+
114+Differential rendering has near-constant cost regardless of change amount — dominated by the comparison scan over all cells.
115+
116+### Hit Test & Focus
117+
118+| Operation | Time |
119+| ---------------------------- | ------- |
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 |
126+
127+### Key Parsing
128+
129+| Input | Time |
130+| --------------------- | ------ |
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 |
139+
140+### End-to-End Pipeline
141+
142+| Scenario | Time | Renders/sec |
143+| ------------------------- | ------ | ----------- |
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 |
150+
151+## Ink Raw Numbers
152+
153+Ink v6.8.0, visually similar tree to cel-tui's "ink-comparable"
154+scenario. Run with Bun 1.3.9 on the same machine. Note: the
155+`renderToString` benchmark was written by us (not shipped by Ink) to
156+isolate the render pipeline from terminal I/O.
157+
158+### `renderToString` (pure pipeline, no I/O)
159+
160+```
161+Run 1: 1,000 renders: 632.75 ms — 632 µs/render
162+Run 2: 1,000 renders: 632.66 ms — 633 µs/render
163+Run 3: 1,000 renders: 630.99 ms — 631 µs/render
164+```
165+
166+### `rerender` (full render with React reconciler + stdout)
167+
168+```
169+Run 1: 1,000 re-renders: 1473.63 ms — 1,474 µs/render
170+Run 2: 1,000 re-renders: 1461.48 ms — 1,461 µs/render
171+Run 3: 1,000 re-renders: 1450.79 ms — 1,451 µs/render
172+```
173+
174+## How to Reproduce
175+
176+```bash
177+# cel-tui benchmarks
178+cd cel-tui
179+bun install
180+bun run benchmarks/run-all.ts # full suite
181+bun run benchmarks/e2e.bench.ts # just the headline numbers
182+
183+# Ink benchmarks
184+git clone https://github.com/vadimdemedes/ink.git /tmp/ink-bench
185+cd /tmp/ink-bench
186+npm install && npm run build
187+
188+# Create a renderToString benchmark (Ink ships rerender-to-stdout only)
189+cat > benchmark/simple/bench-rts.tsx << 'BENCH'
190+import React from "react";
191+import { renderToString, Box, Text } from "../../src/index.js";
192+
193+function App() {
194+ return (
195+ <Box flexDirection="column" padding={1}>
196+ <Text underline bold color="red">{"Hello World"}</Text>
197+ <Box marginTop={1} width={60}>
198+ <Text>
199+ Cupcake ipsum dolor sit amet candy candy. Sesame snaps cookie
200+ I love tootsie roll apple pie bonbon wafer. Caramels sesame
201+ snaps icing cotton candy I love cookie sweet roll.
202+ </Text>
203+ </Box>
204+ <Box marginTop={1} flexDirection="column">
205+ <Text backgroundColor="white" color="black">Colors:</Text>
206+ <Box flexDirection="column" paddingLeft={1}>
207+ <Text>- <Text color="red">Red</Text></Text>
208+ <Text>- <Text color="blue">Blue</Text></Text>
209+ <Text>- <Text color="green">Green</Text></Text>
210+ </Box>
211+ </Box>
212+ </Box>
213+ );
214+}
215+
216+renderToString(<App />, { columns: 80 }); // warmup
217+const start = performance.now();
218+for (let i = 0; i < 1_000; i++) renderToString(<App />, { columns: 80 });
219+const elapsed = performance.now() - start;
220+console.log(`1,000 renders: ${elapsed.toFixed(2)} ms (${(elapsed / 1000).toFixed(3)} ms/render)`);
221+BENCH
222+
223+bun run benchmark/simple/bench-rts.tsx
224+```