[RFC / Discussion] Reflections on TUI async lifecycle, blast radius, and modular boundaries in Zero

[hazyhaar]

Hi everyone, cc @jatmn,

First of all, thank you for the thorough and rigorous reviews on recent PRs (such as #953). The high bar on concurrency invariants and platform safety is truly appreciated.

Going through these successive review rounds got me reflecting on our debugging ergonomics: I rarely experienced this much ping-pong while tracking down lifecycle and UI regressions, and it made me wonder whether our current repository structure and state coupling might be contributing to these cascading side effects.

When working inside internal/tui/model.go (and across internal/ in general), I noticed how easily a change targeting a specific view or an async loading path can inadvertently cross paths with other components (modal routing, git sweeps, or terminal resizing) due to shared state fields and distributed lifecycle checks.

To explore this, I put together an experimental spike on a separate branch in my fork (proposal/decoupled-architecture) with a structure that feels more modular and familiar to me, trying to see if we could naturally minimize blast radius and isolate unit tests.

I documented some thoughts in docs/repostructure.md, but I would love to get your perspective and humble advice on a few design questions:

---

1. Pure, Zero-Dependency Utility Packages (pkg/)

Would there be value in extracting completely self-contained, pure algorithms out of internal/tui/ into standalone pkg/ packages?

• For instance, in the spike:
  • pkg/difftool: purely handles canonical line key normalizations (CanonicalLineKey, MatchChangedLines) so that terminal presentation transforms (tabs, control bytes) can never interfere with diff gutter alignment (▎).
  • pkg/ansi: dedicated to terminal string sanitization (SanitizeFileLine).
  • pkg/safefs: houses non-wrapping integer bounds arithmetic (InBoundsNonWrapping for $2^{64}-1$ anti-wrap) and atomic file updates.
• Question: Does having standalone pkg/ packages (which execute unit tests in ~2ms with zero UI setup) align with the long-term vision of Zero, or is keeping all helpers under internal/ an intentional boundary design?

---

2. Unified Monotonic Authority Store vs. Distributed State Fields

In #953, moving to a monotonically increasing source revision (pathRevisions map[string]uint64) proved to be the key to eliminating race conditions where intermediate resize/theme events could drop required source refreshes.

• In the experimental branch, we isolated this into internal/ui/state.MonotonicAuthority (liveSeq, lifetimeToken, pathRevisions, generation).
• Question: How do maintainers view centralizing async lifecycle authorities into a dedicated state store versus continuing to maintain sequence tokens on the main model struct?

---

3. Structuring internal/tui/ by Sub-domains

With internal/tui/ currently holding ~250 files and over 90k lines in a flat directory, navigating and assessing caller impact can be challenging.

• Question: Would the core team be open in the future to grouping TUI components into sub-packages (such as ui/views, ui/components, ui/layout, ui/state), or does the current flat internal/tui layout provide specific advantages for Bubbletea model composition that I might be overlooking?

---

Everything on the experimental branch is fully green under go test -race -count=1 ./... across all 83 packages, but this is purely shared as food for thought and an open conversation starter.

I would love to hear your thoughts on whether any of these patterns could be helpful as Zero continues to scale!

Thanks again for your time and feedback.

[jatmn]

I don’t lead this project, so I may not be the right person to direct this proposal to. That said, I do think the information is useful and worth considering.

From my perspective, the extended review process is primarily driven by three factors:

1. Review feedback can unintentionally expand the scope of a PR.

   CodeRabbit AI provides useful feedback, but its suggestions can sometimes lead to scope drift—either directly or through follow-up changes. This appears to have become more noticeable over the past month, with reviews increasingly prompting changes beyond the PR’s original purpose.

2. Many built-in PR-review workflows are intentionally lightweight.

   The general PR-review capabilities included with most coding harnesses, including Zero, are often designed to provide a “good enough” review for common cases.

   The review workflow I use is custom-built and performs several independent, critical passes. In practice, it is closer to running a standard review five to ten times, with each pass approaching the code from a fresh, blind context.

   This is important because current models—including the Fabel family—can be biased toward their own generated code and preferred coding styles. They also do not always follow every review requirement consistently. Even when a review appears thorough, the model may concentrate heavily on one issue while only sampling other parts of the change.

3. How authors use their own coding harnesses to address findings can create additional churn.

   I’m not pointing fingers here; I have encountered the same challenge in my own reviews and have sometimes gone through many rounds of review against my own PR-review workflow.

   The central issue is how the model is instructed to address reported findings. If the instructions are too broad—or sometimes even too narrow—one of two outcomes commonly occurs:

   • The fix introduces additional scope drift. The model may make broader changes than necessary while attempting to address the feedback. If those changes generate new review findings, the process can become a cycle of correcting changes introduced by earlier corrections. A relatively small feature or bug fix can gradually become a rewrite of every function it touches.
   • The fix is applied too literally. When instructions are overly specific, the model may correct only the exact instance that was reported without checking for the same issue elsewhere. This can lead to repeated review rounds as each related occurrence is discovered separately.

Ultimately, I believe the extended review cycle comes down to three closely related factors:

• CodeRabbit AI can unintentionally encourage scope drift, depending on how its findings are interpreted.
• Many standard PR-review workflows do not perform a genuinely comprehensive review without several independent passes.
• The way we prompt our own models to implement fixes—and the care with which we inspect those changes—has a significant effect on review churn.

One practical way to reduce this is to challenge each proposed fix before accepting it. Ask whether the change stays within the PR’s intended scope, whether it introduces unnecessary refactoring, and whether the same issue exists elsewhere in the relevant code.

A rapidly growing PR is often a useful warning sign that scope drift may be occurring. Stepping back and reviewing how the PR expanded can help identify where the model chose an overly broad or expedient solution. It can also reveal cases where the reported issue already exists on the main branch and would be better handled in a separate PR.