ADR-0145: The GUI is one file per concern; rio-gui.tcl is the entry

Status: Accepted
Date: 2026-10-02
Deciders: jka

Context

rio-gui/rio-gui.tcl was 14,103 lines and 689 procs in one file. The core's largest file is 1,030. jka's instructions ask for code a human can read.

Tcl resolves a proc when it is called, so a proc can live in any file. Only top-level code is bound to an order: the widgets, the menubar, the boot.

Decision

rio-gui.tcl stays the entry. It reaches the core, sources the parts, boots. Every installer and test still starts there.
A part is a concern: its procs and the state they own. rio-gui/<concern>.tcl, flat, as in rio-core/.
Top-level code lives in three places only, in this order: build.tcl (widgets), menubar.tcl, the entry's tail (boot).
Load order: state.tcl first, build.tcl and menubar.tcl last. Between them, any order.

 rio-gui.tcl   args · spawn or connect the core
      │
      ├─ source  state … widgets     procs and their state
      ├─ source  build, menubar      top-level code: order matters
      │
      └─ boot    prefs · theme · session · first paint

Only the entry carries the D54 guard. It sets the system encoding before a part is read.
The move changed no code. Lines were cut by range, not retyped. A checker held old against new: the same 689 procs, the same top-level statements, the same order, bar the keymap tables, which now load before the widgets and read none of them.

Alternatives considered

Move each pane's widgets into its concern file. It changes the order widgets are created in, and with it stacking and focus traversal. Not earned yet.
Namespaces per concern. A rename of 689 procs and every caller, tests included.
A rio-gui/lib/ directory. The core is flat; one way is enough.

Consequences

The largest GUI file is about 1,100 lines.
git blame needs -C to see past the move.
A new proc goes in its concern's file. New top-level code goes in build.tcl, menubar.tcl or the boot, never in a part.