@@ -3,6 +3,7 @@
33 > Context: I'm mostly a web engineer, with some backend experience with python, node and go.
44
55 Some of my notes might be because of lack of Zig experience.
6+These are **my** notes. Use your own file for your notes...
67
78 ## Notes
89
@@ -26,9 +27,6 @@ Some of my notes might be because of lack of Zig experience.
2627 I suggest the above structure, so we match the work we did for opencode. Basically the mistake here is assuming all providers use the same api for all models, which is not true. Not even for local envs.
2728 Another note here is that again, I'm shocked at how cumbersome it is to read and validate JSON.
2829
29-**resize, width measurements, line wrapping** - these still behave in suprising ways sometimes, breaking highligting, wrapping at weird limits, stange states after resize.
30-A definite research about the best approach to a clean rendering method is required, instead of trial and error. This is not breakthrough, many TUIs have these issues and address them. Use github to learn. Once you've applied the fixes, do exhaustive testing with the stress script or the techniques described there.
31-
3230 **`src/main.zig` - has some headless concerns mixed into the entry point of the app. Worth considering extracting headless into `src/headless.zig`. Single concern files are easier to make a mental model around.
3331
3432 `src/diff.zig` - We are rendering a whole header with index and divider, just to strip it in the TUI. Seems counter productive.
@@ -36,57 +34,3 @@ A definite research about the best approach to a clean rendering method is requi
3634 `src/tui/tui.zig` - This file has a lot of responsibilities, making it very big. Token estimation and commands at least, could be extracted.
3735
3836 `src/tui/theme.zig` - will eventually grow too much, each theme we add will make that file worse. A refactor for later, since it's ok right now.
39-
40-## Rendering defects reproduced (real kitty, real provider)
41-
42-Measured against a real kitty window via `kitty @` remote control
43-(`get-text`, `resize-os-window`) and a real turn against the live provider.
44-
45-1. **Width model is per-codepoint.** `render.charWidth` sums codepoints; a
46- grapheme cluster is not a codepoint. Kitty-measured vs app:
47- `π³οΈβπ` 2 vs 4, `π¨βπ©βπ§βπ¦` 2 vs 8, `π©πͺ` 2 vs 4, `ππ½` 2 vs 4,
48- `β
` 2 vs 1, `βοΈ`/`β’οΈ`/`0οΈβ£` 2 vs 1, `πΊπΈ` 2 vs 4, `π` 2 vs 1.
49- Wide chars (`ζ₯ ν ο½`) and ambiguous (`β΅ β΄`) are right.
50-2. **Highlighting breaks across a soft wrap.** `wrapLine` splits bytes at a
51- width boundary; a tree-sitter span that crosses the boundary loses its SGR
52- on the continuation row (the opening sequence stays on the previous row).
53- Narrowing a fenced python block to 50 shows the continuation rows in the
54- normal fg.
55-3. **Reflow does not rejoin on widen.** `history` stores already-wrapped
56- physical rows; `reflow` re-wraps them, so a paragraph wrapped at 100 stays
57- broken at 100 after widening to 120. Confirmed: after 100β120 the rows still
58- end at the old 100-col boundary.
59-4. **Reflow loses style.** `reflow` repaints every history row with
60- `paintRow` (which prepends `SGR_PLAIN`), so styled rows come back unstyled.
61- Confirmed: teal/comment rows repaint as `[197,201,197]`.
62-5. **`3J` on every resize drops native scrollback** (`\x1b[2J\x1b[3J\x1b[H`).
63-6. **Live-region accounting after resize** is a heuristic
64- (`reanchor = live.rows >= height-1`), and `reflow` resets `live` without
65- reconciling the cursor.
66-
67-Reference implementations studied: bubbletea `cursed_renderer.go` (inline
68-`Erase`+redraw on width change, cursor parked off the last column, cells owned
69-by the app), Ink/`wrap-ansi` and lipgloss SGR-balanced wrap, Ghostty/uucode
70-grapheme-cluster width, `unicode-display_width` precedence rules.
71-
72-### Resolved approach
73-
74-Validated against real kitty by driving the terminal over remote control and
75-reading back `get-text`/`get-cell-colors` and DSR replies (prototypes in
76-`/tmp/proto`), so the design comes from measured terminal behavior, not trial
77-and error.
78-
79-- **Committed transcript is written as logical lines once.** kitty soft-wraps
80- logical lines, repeats the active SGR on every wrapped row, and *reflows and
81- rejoins* them on resize; it neither rejoins nor restyles hard (CRLF) rows.
82- So the app must not pre-wrap or re-emit committed content, and must not send
83- `ED2`/`ED3` on resize.
84-- **The live region is pre-wrapped by the app** (status, queue, body, editor),
85- because the editor needs to own its cursor. It is redrawn every frame.
86-- **Erase uses the caret.** The cursor is parked on the caret cell. To erase,
87- move up by the caret's physical row offset *recomputed at the current width
88- from the previous frame's live rows* (`sum ceil(cells_i/W) + col/W`), CR,
89- SGR, `ED0`. The terminal keeps the cursor attached to its character across
90- reflow, so that offset is exact.
91-- **Width** comes from generated UCD tables and a UAX#29 grapheme-cluster
92- walk (`src/tui/width.zig`); it matches kitty cell-for-cell.