Files

T

retoor 29c489e27a Standalone tai.py: native TUI framework, grouped classes, full suite green

- In-tai.py TUI framework (panels, compositor, z-layers, mouse, focus,
  VT screen, pty sub-terminals, widgets, animation) plus /demo, --demo,
  --demo-shot, tui.md docs, and research/tui-framework-design archive
- Focus safety: Tab/Shift+Tab always cycle, auto-focus prefers
  non-terminals, dialogs restore previous focus on close
- Native Consts/Install/Sandbox/Opencode/SysInfo classes in tai.py;
  module functions delegate so live patches apply; fixes 19 failures
- Retargeted 4 test patches to the real tai.* seams (assertions unchanged)
- Deleted tai_pkg/; tai.py is standalone stdlib-only (bare copy imports)
- AGENTS.md/README.md updated to the standalone architecture
- test_tai.py 320/320 OK, test_seal.py 16/16 OK

2026-10-10 23:45:12 +02:00

3.6 KiB

Raw Blame History

Textual research synthesis (rabbitui project)

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	tui-framework-design
Document type	Source Dossier
Tier	1
Source title	Textual (Python / Textualize) — rabbitui research note
Source URL	https://raw.githubusercontent.com/joshka/rabbitui/HEAD/docs/research/textual.md
Source publisher / author	joshka (rabbitui project)
Source type	other (third-party architecture research note)
Source date (published)	2026-07-06
Date researched	2026-10-10
Researched by	tai (agent), model: Muse Spark, on behalf of retoor
Research method	direct page fetch
Confidence	Medium
Status	Active

Summary

A dense third-party synthesis of Textual's architecture from its docs, blogs, and source: retained DOM with reactive descriptors; actor-per-widget message pumps; a compositor that paints styled segments per line via cuts/chops/occlusion (not cell diffing); a 100x20 spatial map for culling and hit-testing; synchronized-output anti-flicker; DOM-traversal focus chains; plus a critical account of Textual's weaknesses (DataTable performance, release churn, maintenance mode).

Key findings

Compositor algorithm per line: (1) find cuts (every x-offset where any widget region begins/ends), (2) slice segment lists into aligned chops, (3) discard occluded chops (not top-most in z), (4) merge survivors. Paint primitive is Rich Segments (text + style runs), which is how CJK/emoji stay sane.
Z-order comes from CSS layers (leftmost name = bottom); visibility culling uses a spatial map (widgets hashed into a 100x20-cell grid, rebuilt only when geometry changes).
Anti-flicker recipe attributed to McGugan: "overwrite don't clear / single write / Synchronized Output".
Focus: exactly one focused widget; Tab walks a chain computed by DOM traversal sorted by on-screen (y, x) position (no tab-index); _trap_focus confines the chain inside modals; :focus/:focus-within styling hooks.
Layout math uses exact rationals (fractions.Fraction) so 1fr 1fr 1fr never leaves a 1-cell gap; the modest vocabulary (linear + grid + dock + offset + fr) covered Textual's whole ecosystem.
Cautionary findings: built-in DataTable took ~63s on a 538k-row set vs 0.077s for a virtualized rewrite (~800x, eager ingestion without a pluggable backend); Textualize wound down May 2025 with eight majors shipped between 1.0 and 8.x (breaking-change churn).

Pros / strengths

The single best "what to steal" list found: compositor cuts/chops, spatial map, sync output, reactive invalidation split (repaint vs relayout), focus traversal, exact fractional layout — each tied to its upstream doc or post.
Honestly critical (perf failures, churn, maintenance risk), not a fan note.

Cons / limitations / caveats

Secondary synthesis with a Rust-port agenda; time-sensitive claims (versions, star counts, company status) not independently verified in this pass.
Compositor claims describe Textual's source secondhand; the primary (_compositor.py) was not read line by line here.

Relevance to tai

This is the blueprint document for tai's renderer: retained tree, per-line cuts/chops/occlusion compositing over styled runs, named layers for z, spatial-map hit-testing, single-write synchronized output, traversal-ordered focus with modal trap, exact integer layout math.
The DataTable lesson becomes a tai rule: list-like widgets virtualize (render visible rows only), never eagerly ingest.

Changelog

Date	Change
2026-10-10	Initial dossier created.

3.6 KiB Raw Blame History