Phase 4: Split the draw code into app/ui/¶
Master plan: PLAN-app-split.md.
Planning effort¶
Planned at high effort. The phase looks like the moves phases 2 and
3 did, and most of it is, but three parts are not. Nesting a module
under app/ needs a visibility form neither earlier phase used, and
getting it wrong is a compile error in every step at once. The
status bar is a single 373-line ui.horizontal closure that cannot
move as one function. And the central panel sets two flags that
later blocks read, so it is the one block whose extraction changes a
signature rather than just a location.
Review effort belongs on draw order. Everything else here is checkable by script; the order the panels and windows are drawn in is a contract with egui that no test in this repository exercises.
Scope¶
In:
ryll/src/app/ui/-- a new module directory withmod.rsand ten children:cursor.rs,dialogs.rs,keys.rs,notifications_panel.rs,region_select.rs,stats_bar.rs,surface.rs,traffic_panel.rs,usb_panel.rs,webdav_panel.rs.- Reducing
eframe::App::uito the sequence of calls that drives them, with the draw order stated in a comment where it is load-bearing. - The
&mut selfresize callersmaybe_send_monitors_resizeandsend_pending_guest_size, plus the viewport-fit block at the top ofui, which join the pure helpers phase 2 already moved toapp/resize.rs(survey finding 7). - The eight tests in
app/mod.rsthat belong to moved code, moved verbatim with it. ARCHITECTURE.md'sryll/src/tree,app/mod.rs's file-header comment, and one line inAGENTS.mdfor the visibility rule a nested module introduces (decision 3).
Out:
logic,on_exitand theimpl eframe::App for RyllAppblock itself, which stay inapp/mod.rs(decision 2).logicis 156 lines but under 100 once comments are discounted, so phase 6's lint will not flag it and this phase does not touch it (survey finding 8).RyllApp::new(243 lines by clippy's count) andconnection.rs'sreconnect(154). They are the only two functions inapp/that phase 6's lint will flag onceuiis gone;newis phase 5's field regrouping andreconnectis phase 6's own problem (survey finding 9).- Enabling
clippy::too_many_lines. This phase runs it by hand as a done-criterion; phase 6 wires it intomake lint. clipboard,trigger_paste,push_notification,push_connection_event,handle_cadenceandwindow_focused, which stay inapp/mod.rs(decision 8).- Any behaviour change. Panels keep reaching into
selfexactly as they do today; grouping those fields is phase 5.
What the survey found¶
Surveyed against develop at 32d8b22, after #714 (phase 3) and
717 (its review follow-ups) merged. ryll/src/app/mod.rs is 3,230¶
lines, of which ui is 1,691 (lines 1241-2931).
- The master plan's file list does not cover
ui. Its nine files account for about 1,100 of the 1,691 lines. The central panel -- the surface itself, 149 lines at 2364-2512 -- has no file in the list, and neither does the viewport-fit block at the top. The full inventory, with the destination this phase gives each block:
| Lines | Block | Takes | Destination |
|---|---|---|---|
| 1241-1255 | ctx binding, shutdown early return |
ctx | stays in ui |
| 1257-1261 | input gate while the bug dialog is open | ctx | keys.rs |
| 1263-1289 | viewport fit, then maybe_send_monitors_resize |
ctx | resize.rs |
| 1291-1364 | hotkeys: Esc, F12, F11, F8, Esc, Ctrl+Alt+V | ctx | keys.rs |
| 1366-1379 | handle_input, held-key end of frame, screenshot dialog |
ctx | keys.rs |
| 1381-1390 | traffic-entry refresh | -- | traffic_panel.rs |
| 1392-1764 | status bar panel | ui, ctx | stats_bar.rs |
| 1765-1855 | traffic viewer panel | ui | traffic_panel.rs |
| 1857-2003 | notifications panel, then mark-all-read | ui | notifications_panel.rs |
| 2005-2245 | USB panel, with its pre-draw polling | ui, ctx | usb_panel.rs |
| 2247-2362 | WebDAV panel | ui, ctx | webdav_panel.rs |
| 2364-2512 | central panel: the surface | ui, ctx | surface.rs |
| 2514-2630 | bug report window | ctx | dialogs.rs |
| 2632-2658 | paste error window | ctx | dialogs.rs |
| 2660-2769 | region selection overlay | ctx | region_select.rs |
| 2771-2836 | cursor texture and overlay | ctx | cursor.rs |
| 2838-2859 | protocol gaps window | ctx | dialogs.rs |
| 2860-2920 | reconnect modal | ctx | dialogs.rs |
| 2922-2928 | hide the host cursor | ctx | cursor.rs |
| 2930 | observe_ui_state |
ctx | stays in ui |
Four items outside ui move with their blocks: handle_input
(928-962), release_guest_keys (963-974) and
keep_keyboard_for_guest (1055-1063) to keys.rs;
send_pending_guest_size (994-999) and
maybe_send_monitors_resize (1000-1040) to resize.rs;
default_arrow_cursor (2935-2985) to cursor.rs; and
TRAFFIC_VIEWER_MAX_ENTRIES / TRAFFIC_VIEWER_REFRESH_MS (83,
86) to traffic_panel.rs. Phase 3's scope section already
promised the last two and default_arrow_cursor to this phase,
and all three are referenced only from app/mod.rs, so nothing
else has to change to move them. The master plan's phase 4
section has been corrected to name surface.rs and to stop
implying the list is complete.
-
"each a
fn draw_*(&mut self, ui: &mut egui::Ui)" is wrong for half of them. egui 0.35 unified the panel types and madePanel::showtake&mut Ui, butWindow::showstill takes&Context. Six blocks need the root&mut Ui: the status bar (Panel::bottom(…).show_collapsible(ui, …), 1444), the traffic, notifications, USB and WebDAV side panels (Panel::right(…).show(ui, …)at 1767, 1859, 2070, 2284) and the central panel (2370). The four windows -- bug report, paste error, protocol gaps, reconnect modal -- takectxand never touch the rootui, and neither do the hotkeys, the region overlay, the cursor overlay or the viewport fit, which work throughctx.input,ctx.output_mutandctx.layer_painter. The master plan's section has been corrected. Both signatures are safe to pass together:ctxis a borrow of thectx_ownedclone made at 1249, not ofui, which is why that clone exists. -
Nesting needs a visibility form phases 2 and 3 never used. The twelve existing children of
app/are siblings ofmod.rs, sopub(super)makes an item visible toappand therefore to every sibling. Fromapp::ui::stats_bar,pub(super)means visible inapp::uionly -- not inapp, whereuiitself lives and does the calling. The form that works ispub(in crate::app), which grants exactly the scopepub(super)grants a direct child: moduleappand all its descendants. A probe compiled in theryll-devcontainer confirms all three cases this phase needs -- a grandchild's inherent method called fromapp, the same method called from a sibling ofui(app::screenshots), and a grandchild calling a private method ofapp-- and is recorded in decision 3. -
Only two locals escape their block.
pointer_on_surfaceandopen_channel_bug_reportare declared at 2365-2366, written inside the central panel, and read afterwards at 2509 and 2926. Every other local inui--is_maximized,show_stats,stats_frame,streaming_state,panel_frame,dialog_held,paste_triggered,modifiers,dialog_action,paste_dialog_action,wants_reconnect-- is read only inside the block that declares it, so every other extraction is a pure move of a{ … }body. -
The status bar cannot move as one function. 1392-1764 is one
ui.horizontalclosure (1445) whose right-hand group is a nestedwith_layout(right_to_left, …)(1536). At 373 lines it would be the largest function inapp/the moment it landed, so it splits along the boundaries the code already has: metrics 1446-1535, volume 1537-1551, streaming indicator 1552-1636, agent indicator 1637-1645, bandwidth sparkline 1646-1679, bell 1680-1707, and the☰menu of panel toggles 1708-1763. Thestreaming_stateclassification at 1405-1434 is logic, not drawing: it can push a notification, and the comment at 1401-1404 records that it must run before the bell draws so the bell sees it on the same frame. It becomes a method called at the top of the status bar's draw, which keeps that ordering by construction. -
The cursor code is in two pieces, separated in the draw order. The texture setup and overlay are 2771-2836; hiding the host cursor is 2922-2928, after the protocol gaps window and the reconnect modal.
cursor.rstherefore gets two entry points called at their present positions, not one. -
Phase 2 moved the resize helpers but left their callers.
app/resize.rsholds six free functions (compute_auto_resize,compute_outgoing_resize,resolution_notification_due,send_guest_size,auto_fit_size_acceptable,is_primary_surface) and twelve tests, but the&mut selfmethods that call them --maybe_send_monitors_resize,send_pending_guest_size-- and the viewport-fit block inuistayed inmod.rs. Finishing that seam costs 74 lines and no new file. -
logicdoes not need this phase. It is 156 lines at 1085-1240, but the inline work in it is three short blocks (ticket-expiry warning, auto-reconnect tick, resolution notification) and the rest is comments and delegation. Counted the wayclippy::too_many_linescounts -- non-blank, non-comment body lines -- it is under 100 and the lint will not flag it. An earlier verbal estimate in this session said phase 4 should coverlogicas well asui; measurement says otherwise. -
Phase 6's baseline, measured with the lint itself. Running
cargo clippy --frozen -p ryll --features gui,digest-decode -- -W clippy::too_many_linesin the devcontainer reports three functions underryll/src/app/:ui(1,389/100),RyllApp::new(243/100) andconnection.rs'sreconnect(154/100). After this phase the first is gone and nothing new exceeds 100, which leaves phase 6 two call sites inapp/to decide about rather than three -- plus six elsewhere inryll(bugreport.rstwice,capture.rs,web/signalling.rsandmain.rstwice) and twenty-five in the sibling crates, which is phase 6's scoping problem and not this phase's. -
Eight tests in
mod.rs, five of which move. The three cursor tests and theirsurface_contains_pointerhelper (3063-3131) go tocursor.rs; the two status-button tests withkey_pressandstatus_button_clicks(3132-3206) go tokeys.rs, which is wherekeep_keyboard_for_guest-- the function they exercise -- is going. Note thatsurface_contains_pointeris a replica of the containment test, written inside the test module: those three tests pin egui's behaviour, not this crate's, which is worth knowing before treating them as coverage ofcursor.rs. The twologictests andvolume_control_round_tripstay (decision 9). -
One method needs the cross-subtree form.
release_guest_keysis called fromapp::screenshots(screenshots.rs) as well as from the hotkey block, so once it is inapp::ui::keysit is the one moved item whose caller is neitherappnor a descendant ofapp::ui.pub(in crate::app)covers it; the probe in finding 3 includes exactly this case. -
The tree does not currently pass its own lint, for reasons that predate this phase.
make lintfails ondevelopunder rustc/clippy 1.100.0 (2026-11-09) withneedless_range_loopinshakenfist-spice-usbredir/src/messages.rs, and the CI Lint lane has failed on every pull request since the devcontainer image picked that toolchain up -- the last green run is #717's merge-queue run. The code is unchanged since the crate was extracted; clippy is what moved. It is nothing to do withapp.rs, so this phase does not fix it: filed as ryll#722 with the one-line fix. It does gate the phase's pull request, because that pull request cannot go green until #722 lands, and it gatespre-commit run --all-fileslocally for anyone with a current image.
Nothing else the master plan's phase 4 section claims turned out to
be wrong: the nine file names it gives are all sound as far as they
go, the draw-order constraint it names is real and already
commented at 1392, and the panels do all still reach into self
the way it says.
Decisions¶
-
app/ui/as a nested directory, not flatapp/ui_*.rsfiles. The master plan saidapp/ui/and the alternative has got worse since: flat would put 23 files in one directory and would shelve tenui_*.rsdraw files next toui_state.rs, which is state, not drawing. The cost is decision 3. -
uistays inapp/mod.rs; theimpl eframe::App for RyllAppblock is not moved. A trait impl cannot be split across files, so movingui's new body intoapp/ui/mod.rswould draglogicandon_exitwith it -- 180 lines of per-frame logic into a module calledui, andwindow_focusedand two tests after them. Keeping the block whole has a price: becauseuilives inappand the draw methods live inapp::ui::*,pub(super)is not enough for them. That is decision 3, and it is the cheaper of the two prices. -
Every method
uicalls across the boundary ispub(in crate::app), and nothing is wider. The master plan's decision 7 says "pub(super)and nothing wider"; this is the same scope with a different spelling -- moduleappand its descendants -- so it honours that decision rather than relaxing it.pub(in super::super)is also legal and was rejected as harder to read. Nopub(crate)and no barepubis added anywhere inapp/ui/. Verified by probe before planning:
mod app {
pub struct RyllApp { n: u32 }
mod screenshots {
pub(super) fn save(a: &mut super::RyllApp) { a.release_guest_keys(); }
}
mod ui {
mod keys {
impl crate::app::RyllApp {
pub(in crate::app) fn release_guest_keys(&mut self) { self.n += 10; }
}
}
}
}
compiles and runs, as does the grandchild calling a private
method of app. Children import what they need explicitly --
use crate::app::RyllApp; and so on -- matching phase 2's
convention; no file-scope use super::*; glob is introduced,
because the workspace has none.
-
The central panel returns what escapes it; it does not grow two
RyllAppfields.draw_surfacereturns a smallSurfaceOutcome { pointer_on_surface: bool, open_channel_bug_report: bool }declared insurface.rs. Adding fields would push against phase 5, whose whole job is to shrink the struct, and would turn two frame-scoped flags into state with a lifetime longer than the frame. -
The status bar splits into seven draws plus a classification method along the boundaries in survey finding 5. This is the one step that is not a block move, and the one where the diff will not read as a pure relocation: the bodies are unchanged but their indentation and their closure nesting are not.
-
Draw order is the contract. The call sequence in
uiafter this phase is, exactly: keyboard-focus gate, viewport fit, hotkeys, traffic refresh, status bar, traffic panel, notifications panel, USB panel, WebDAV panel, surface, bug report window, paste error window, region select, cursor overlay, protocol gaps window, reconnect modal, hide host cursor,observe_ui_state. Note the first two: the keyboard focus gate sits before the viewport fit today and the hotkeys after it, which is whykeys.rskeeps two entry points instead of one (step 4f). The comment inuisays why the status bar must precede the central panel (egui reserves panel space in draw order) and that the window order is z-order. No step may reorder these, including the two steps that would read more naturally grouped -- the four windows are not adjacent anddialogs.rs's four methods are called at four separate points. -
The resize callers go to
app/resize.rs, not underui/. They are the missing half of a seam phase 2 opened, and the viewport fit is not drawing: it reads the viewport and sends a display size.resize.rsreaches 526 lines, within the 800-line ceiling the phase keeps. -
keys.rstakes the input subsystem, not just the hotkeys. The master plan scoped it to "the global hotkey handling at the top ofui", which is 89 lines that call straight intohandle_input,release_guest_keysandkeep_keyboard_for_guest-- and the two tests that exist for any of this exercise the last of those. Splitting them across two files would leave the tests pointing at a different module from the code.clipboardandtrigger_pastestay inmod.rs: they are clipboard plumbing that the Ctrl+Alt+V arm happens to call, and a descendant can call an ancestor's private method unchanged. -
volume_control_round_tripstays inmod.rs. It pinsVolumeControl's get/set contract becauseRyllApp::reconnectmust not reset the user's slider. The slider is in the status bar, but the behaviour it guards is inconnection.rs, so neitherstats_bar.rsnor a move makes it more findable than leaving it where the author put it. -
One commit per step, each one compiling. Every step removes its block from
uiand inserts the call in the same commit, so the tree builds at each one and the move check can run againstHEAD~1. No step leaves a method defined but uncalled.
Step plan¶
Steps run sequentially: every one of them edits app/mod.rs, so
they cannot share the worktree. Sub-agents work in the phase
worktree with no isolation, as in phases 2 and 3, and leave the work
uncommitted for review in the management session.
| Step | Effort | Model | Isolation | Brief for sub-agent |
|---|---|---|---|---|
| 4a | medium | sonnet | none | Create app/ui/ and move the four side panels into it |
| 4b | high | opus | none | Move and split the status bar |
| 4c | high | opus | none | Move the central panel, returning what escapes it |
| 4d | medium | sonnet | none | Move the four windows into dialogs.rs |
| 4e | medium | sonnet | none | Move the region overlay and the cursor into their files |
| 4f | high | opus | none | Move the input subsystem into keys.rs |
| 4g | medium | opus | none | Finish ui, the resize seam, and the documentation |
| 4h | high | opus | none | Bring every draw method under the length lint |
Step 4a: app/ui/ and the four side panels¶
Create ryll/src/app/ui/mod.rs declaring its children
alphabetically, and add mod ui; to app/mod.rs's alphabetical
mod list (between trigger_snapshot and ui_state). app/ui/
inherits app's #[cfg(feature = "gui")] gate from the mod app;
declaration, so no file in it carries a feature attribute.
Move four blocks out of eframe::App::ui in app/mod.rs, each
into a pub(in crate::app) fn in its own file, replacing each with
a single call at the point the block was:
- 1381-1390 (the refresh gate) and 1765-1855 to
traffic_panel.rs, asrefresh_traffic_entriesanddraw_traffic_panel, plus the twoTRAFFIC_VIEWER_*constants from lines 83 and 86 ofmod.rs. - 1857-2003 to
notifications_panel.rsasdraw_notifications_panel. Keep the mark-all-read transition at 1995-2003 inside it, in place: it must run after the panel and it readsnotifications_panel_was_open_last_frame. - 2005-2245 to
usb_panel.rsasdraw_usb_panel, including the pre-draw enumeration and file-picker polling at 2007-2065 -- it only runs whenshow_usb_panel, so it is part of the same block. - 2247-2362 to
webdav_panel.rsasdraw_webdav_panel.
All four take ui: &mut egui::Ui; draw_usb_panel and
draw_webdav_panel also take ctx: &egui::Context, each for a
request_repaint_after. The if
self.show_* { test moves inside the method rather than staying at
the call site, so ui reads as an unconditional sequence. Import
explicitly (use crate::app::RyllApp; and the types each file
needs); do not add a use super::*; glob -- the workspace has
none. Bodies are moved verbatim: the only edits are the
dedent, the method header, and imports.
Verify with the move check in the definition of done, then make
lint and make test.
Commit subject: Move the side panels into app/ui/.
Step 4b: the status bar¶
Move 1392-1764 to app/ui/stats_bar.rs as
pub(in crate::app) fn draw_stats_bar(&mut self, ui: &mut egui::Ui),
splitting it as survey finding 5 and decision 5 describe: the
streaming_state computation at 1405-1434 becomes
fn classify_streaming_state(&mut self) -> StreamingState called
first, and the closure contents become private methods on RyllApp
in the same file -- metrics 1446-1535, volume 1537-1551, streaming
indicator 1552-1636 (taking &StreamingState), agent indicator
1637-1645, sparkline 1646-1679, bell 1680-1707, menu 1708-1763.
Each takes the &mut egui::Ui of the closure it came from, so the
nesting of ui.horizontal and with_layout stays exactly as it is
and only the bodies move out.
The sub-methods are private (no pub(in …)): they are called only
from inside stats_bar.rs. Keep every comment with the code it
explains, including the three long ones at 1552-1560 (why the glyph
is ▶), 1571-1573 (why the tooltip strings are built inside the
hover closure) and 1401-1404 (why the classification runs before
the bell).
No statement may change order, and no if condition may be
rewritten. Verify that cargo clippy -W clippy::too_many_lines
reports nothing in stats_bar.rs.
Commit subject: Split the status bar into its own module.
Step 4c: the surface¶
Move 2364-2512 to app/ui/surface.rs as
pub(in crate::app) fn draw_surface(&mut self, ui: &mut egui::Ui, ctx: &egui::Context) -> SurfaceOutcome,
where SurfaceOutcome is a pub(in crate::app) struct with the two
bool fields decision 4 names. panel_frame (2367) moves inside.
The follow-up at 2508-2512 -- opening the bug report dialog for a
channel error -- stays in ui, because it reads the returned flag
and runs before the dialog draws; it reads
outcome.open_channel_bug_report instead of the local.
pointer_on_surface is read by the host-cursor block at 2926, which
step 4e moves, so until then ui keeps it in a local bound from the
return value.
Nothing in the body changes except the two assignments to the escaping locals, which become fields of the returned value. Check that both reads still see the same value they do today: the flag is written in several places inside the closure (2415, 2451, 2471).
Commit subject: Move the surface panel into app/ui/.
Step 4d: the four windows¶
Move all four egui::Window blocks to app/ui/dialogs.rs, each a
pub(in crate::app) fn taking ctx: &egui::Context:
- 2514-2630 bug report, as
draw_bug_report_dialog. Keep the two-pass shape: render intodialog_action, then act on it outside the closure (2603-2630).dialog_held(2516) moves in. - 2632-2658 paste error, as
draw_paste_error_dialog, including the Escape dismissal at 2652-2658. - 2838-2859 protocol gaps, as
draw_protocol_gaps_window. - 2860-2920 reconnect modal, as
draw_reconnect_modal, including thewants_reconnectfollow-up at 2918-2920.
The four calls stay at the four positions they occupy today (decision 6); they are not adjacent and must not be grouped.
Commit subject: Move the dialog windows into app/ui/.
Step 4e: region select and the cursor¶
Move 2660-2769 to app/ui/region_select.rs as
pub(in crate::app) fn draw_region_select(&mut self, ctx: &egui::Context).
Move 2771-2836 and 2922-2928 to app/ui/cursor.rs as two methods --
draw_cursor_overlay(&mut self, ctx: &egui::Context) and
hide_host_cursor(&mut self, ctx: &egui::Context, pointer_on_surface: bool)
-- called at their present positions, with the protocol gaps window
and the reconnect modal still between them (survey finding 6).
default_arrow_cursor (2935-2985) moves to cursor.rs as a private
free function, and the three cursor tests with their
surface_contains_pointer helper (3063-3131) move into a
#[cfg(test)] mod tests in the same file, verbatim, keeping their
section comment.
Commit subject: Move the cursor and region overlays into app/ui/.
Step 4f: the input subsystem¶
Move to app/ui/keys.rs: the input gate at 1257-1261, the hotkey
block at 1291-1364, the handle_input call and held-key end of
frame at 1366-1373, the screenshot-dialog trigger at 1375-1379, and
the three functions handle_input (928-962), release_guest_keys
(963-974) and keep_keyboard_for_guest (1055-1063).
Two entry points, not one. The gate at 1257-1261 runs before
the viewport fit and the hotkeys run after it, so merging them
would reorder one against the other. ui keeps
self.gate_keyboard_focus(ctx) where the gate is today and
self.handle_hotkeys(ctx) where the hotkey block is today, with
the viewport fit between them. The remaining three blocks
(1366-1379) are contiguous with the hotkeys and fold into
handle_hotkeys.
release_guest_keys is called from app::screenshots as well, so
it -- like the two entry points -- is pub(in crate::app);
keep_keyboard_for_guest is a free function used by
handle_hotkeys and by the tests, so it is private to keys.rs.
handle_input becomes private too: after the move its only caller
is in this file.
Move the two status-button tests with key_press and
status_button_clicks (3132-3206) into a #[cfg(test)] mod tests
in keys.rs, verbatim. paste_triggered and modifiers (1339,
1372) are locals of the moved block and move with it.
Doc comments on the moved functions reference items by name --
check every […] link still resolves, because this is exactly
where phase 3 silently broke three of them. The rustdoc lane in
make lint is the check.
Commit subject: Move the input and hotkey handling into app/ui/.
Step 4g: ui, the resize seam, and the documentation¶
Three things, in one commit because they are one change to the same reader's mental model:
-
Move the viewport-fit block (1263-1289) and the two methods
send_pending_guest_size(994-999) andmaybe_send_monitors_resize(1000-1040) intoapp/resize.rs, as animpl RyllAppblock with a singlepub(super) fn fit_viewport_to_surface(&mut self, ctx: &egui::Context)entry point that ends by callingmaybe_send_monitors_resize(both of those stay private to the file).pub(super)is right here:resize.rsis a direct child ofapp. -
Give
uiits final shape: thectxbinding, the shutdown return, the eighteen calls of decision 6 in that order, and one comment block saying that panel order is how egui reserves space (status bar before the central panel) and that window order is z-order. Rewriteapp/mod.rs's file-header comment (lines 1-10), which currently says the file implements the panels and carries the egui 0.35 migration notes -- the migration notes move toapp/ui/mod.rs, which is where those call sites now live. -
Documentation.
ARCHITECTURE.md'sryll/src/tree gains theapp/ui/subtree with a one-line description per file, in the same style as the existingapp/entries, placed betweentrigger_snapshot.rsandui_state.rs;mod.rs's entry stops claiming "panels and dialogs".AGENTS.mdgains one line, in the feature-gating or conventions area, recording that items inapp/ui/arepub(in crate::app)becausepub(super)reaches onlyapp::ui-- a convention an agent cannot infer from one file. Nothing else inAGENTS.mdchanges, and nothing is added todocs/for this phase: no user-visible behaviour changed.
Commit subject: Reduce ui to its draw sequence.
Step 4h: under the length lint¶
Added during execution; see the execution notes for why. After 4g, run
and split every function it names under ryll/src/app/ui/ until it
names none. Two are known in advance, both created by 4a:
draw_usb_panel at 210 lines and draw_notifications_panel at
123. The USB panel's first 60 lines are not drawing at all -- first-
open enumeration, the file-picker poll, the error auto-clear and a
repaint request -- so they become a poll_usb_state method called
at the top of the draw; what is left splits along the panel's own
header, device-list and virtual-disk seams. The notifications panel
splits at its header and list boundary. Whatever 4c to 4f leave over
100 is split the same way, along a seam the code already has.
The rules of 4b apply unchanged: bodies verbatim, sub-methods private, no statement reordered, and the re-inlining check must reproduce each original block token for token.
RyllApp::new and connection.rs's reconnect are out of scope
and stay over the threshold: they are phase 5's and phase 6's.
Commit subject: Bring every draw under the length lint.
Risks and mitigations¶
-
A reordered draw changes what the user sees, and no test notices. Panel space reservation and window z-order are both positional, and this repository has no test that renders a frame. Mitigation: decision 6 writes the order down in the plan; the reviewer diffs the final call order in
uiagainst the block order ingit show develop:ryll/src/app/mod.rsbefore the last commit; and the move check proves no line inside a block moved relative to its neighbours. Residual risk is real but small, and it is the one thing in this phase worth a manual run against the desktop test guest -- see the back brief. -
Extracting a closure body hits the borrow checker. The bodies run inside
ui.horizontal(|ui| …)andPanel::show(ui, |ui| …)closures that capture&mut selfwhileuiis separately borrowed. Callingself.draw_x(ui)from inside such a closure is fine --selfand the closure'suiare disjoint -- but a sub-method that needs both the closure'suiand the outerctxmust takectxas a parameter rather than reach forui.ctx(), which borrowsui. That is why line 1249 clones the context, and the comment explaining it stays. Mitigation: the compiler, and the step briefs say which parameters each method takes. -
The move check is weaker here than in phase 3. Reindentation changes every moved line, and steps 4b and 4c add function headers and a struct. Mitigation: the check strips leading whitespace before comparing, and the definition of done enumerates what the diff may report. For 4b and 4c the reviewer additionally compares the token multiset of the whole diff, as #714's review did, rather than relying on the line check alone.
-
Moving an item silently breaks a rustdoc intra-doc link. Phase 3 broke three and no lint caught them until
cargo docwas run by hand; #717 added the rustdoc lane tomake lintfor exactly this. Mitigation:make lintnow fails onrustdoc::broken_intra_doc_links, and step 4f's brief names it. -
app/ui/is not covered by theguifeature lane. It would be invisible to CI if the gate were wrong. Mitigation:mod ui;sits insidemod app, whichmain.rsgates ongui, so the files inherit it and need no attribute of their own; andmake lint's-p ryll --features gui,digest-decodelane (added in phase 3) compiles them with warnings denied. -
A sub-agent "tidies" a body while moving it. Mitigation: the briefs say verbatim, the move check is run per step, and the management session reads each diff rather than the report.
Definition of done¶
ryll/src/app/ui/holds exactly these eleven files:
cursor.rs dialogs.rs keys.rs mod.rs notifications_panel.rs
region_select.rs stats_bar.rs surface.rs traffic_panel.rs
usb_panel.rs webdav_panel.rs
ryll/src/app/mod.rsis under 1,400 lines (it is 3,230 today), and no file underryll/src/app/exceptmod.rsexceeds 800 lines:
find ryll/src/app -name '*.rs' ! -name mod.rs -exec wc -l {} + \
| awk '$1 > 800 && $2 != "total" { print; bad=1 } END { exit bad }'
eframe::App::uiis under 60 lines and constructs no egui panel or window:
awk '/^ fn ui\(&mut self/,/^ \}$/' ryll/src/app/mod.rs \
| grep -cE 'egui::(Panel|Window|CentralPanel)'
is 0, and the same range is under 60 lines.
-
The call order in
uiis the order decision 6 lists, and it matches the block order ondevelop. Checked by the reviewer againstgit show develop:ryll/src/app/mod.rs; the expected sequence is in decision 6 and in the commentuicarries. -
No moved item is defined in
app/mod.rsany more:
grep -nE '^( )?(pub(\(super\)|\(in crate::app\))? )?fn (handle_input|release_guest_keys|keep_keyboard_for_guest|send_pending_guest_size|maybe_send_monitors_resize|default_arrow_cursor)\b' \
ryll/src/app/mod.rs
prints nothing, and grep -c 'TRAFFIC_VIEWER_' ryll/src/app/mod.rs
is 0.
- Nothing in
app/ui/is wider thanpub(in crate::app):
prints nothing.
- No function under
ryll/src/app/exceeds 100 lines by clippy's count exceptRyllApp::newandconnection.rs'sreconnect:
cargo clippy --frozen -p ryll --features gui,digest-decode \
-- -W clippy::too_many_lines 2>&1 \
| grep -A1 'has too many lines' | grep 'ryll/src/app/'
names those two and nothing else, at 243/100 and 154/100. Run it
through the devcontainer the way make lint does
(DOCKER_RUN_OFFLINE, after make fetch), and touch
ryll/src/main.rs first: cargo replays cached diagnostics, so a
second run on a warm cache prints nothing and the check passes
vacuously; the figures in survey
finding 9 come from running exactly this during planning. The
implementer records the list in the execution notes.
- The move check passes for steps 4a, 4d, 4e and 4f. It compares the multiset of moved lines, leading whitespace stripped, so that a dedent does not register as a change:
d=$(mktemp -d)
git diff HEAD~1 -U0 -- ryll/src/app/mod.rs | grep '^-[^-]' | sed 's/^-//' \
| sed -E 's/^[[:space:]]+//' | grep -vE '^(use |mod |$)' | sort > "$d/removed"
git diff HEAD~1 -U0 -- ryll/src/app/ | grep '^+[^+]' | sed 's/^+//' \
| sed -E 's/^[[:space:]]+//' | grep -vE '^(use |mod |$)' | sort > "$d/added"
diff "$d/removed" "$d/added"
Every line it reports must be a brace- or paren-only line, a new
fn/impl/struct header, a comment, or the call that replaced
the moved block. The implementer lists them in the execution
notes; anything else is a body change and fails the step.
-
For steps 4b and 4c, where the line check cannot be exact, the token multiset of the whole diff differs only by the new headers, the
SurfaceOutcomestruct and its two field reads, and the}/)lines the re-nesting adds. Stated in the execution notes with the comparison that was run. -
The
ryllbinary's test count is unchanged fromdevelop, and no moved test body was edited:git diff develop -- ryll/src/app/ | grep '^-'contains no line from inside a#[test]body that is not also added verbatim elsewhere. The twologictests andvolume_control_round_tripare still inapp/mod.rs; the three cursor tests are inapp/ui/cursor.rs; the two status-button tests are inapp/ui/keys.rs. -
ARCHITECTURE.md'sryll/src/tree lists every file that exists underryll/src/app/andryll/src/app/ui/:
comm -23 <(ls ryll/src/app/*.rs ryll/src/app/ui/*.rs | xargs -n1 basename | sort -u) \
<(sed -n '/^ryll\/src\/$/,/^shakenfist-spice-renderer\/src\/$/p' ARCHITECTURE.md \
| grep -oE '[a-z_]+\.rs' | sort -u)
prints nothing. mod.rs appears once in both lists, so the check
cannot distinguish app/mod.rs from app/ui/mod.rs; a reviewer
confirms by eye that both are described, and that the app/ui/
sub-block names no file that does not exist.
-
app/mod.rs's file-header comment no longer says the file implements the panels, andAGENTS.mdrecords thepub(in crate::app)rule in one line. -
make lint,make testandpre-commit run --all-filespass. Note survey finding 12: on a toolchain of 1.100.0 or later they cannot pass until ryll#722 is fixed, which is not this phase's work. If #722 is still open when the steps run, the implementer records each check's result with that one error excluded and says so, rather than reporting a pass it did not get. -
No behaviour change, so the CI GUI build and the unit tests are the evidence. What that evidence does not cover: nothing in the tree renders a frame, so no test distinguishes the current draw order from a wrong one, and no test constructs a
RyllAppat all (phase 3 recorded the same gap for its two edited paths). Risk 1 says what is done instead. If a manual run against the desktop test guest is wanted, the back brief asks for it.
Execution notes¶
Implementation began 2026-11-14 (AEDT), in
../ryll-wt-app-p04 on app-split-phase-04-panels.
Rebased before starting. The branch was planned on 32d8b22
and rebased onto da0e593, which carries #723. Without that fix
make lint cannot pass on rustc 1.100.0, so every step's checks
would have failed for a reason outside the phase (survey finding
12). #722 is closed.
Back brief answers.
- The module shape is as planned: nested
app/ui/,uistays inapp/mod.rs, and the draw methods arepub(in crate::app)(decisions 1-3). The two alternatives offered -- flatapp/ui_*.rsfiles keepingpub(super), and moving the wholeimpl eframe::Appblock intoapp/ui/mod.rs-- were declined. - A manual run against the desktop test guest is wanted before the pull request. The phase therefore stops after step 4g with the branch built, for the operator to check the panels, dialogs and cursor by eye. This is the mitigation risk 1 asks for.
- This session may push and open the pull request, after that check.
Three cells of the inventory table's "Takes" column were
wrong, all the same way. The status bar, the WebDAV panel and the
central panel each need ctx as well as ui -- for a repaint
request, a texture lookup and an input read. The survey measured
ctx use per block correctly; the error was in transcribing those
measurements into the table and into three step briefs, where "the
panels take ui" became a rule instead of a per-block fact. All
three cells and the step 4c signature are corrected above, and the
rule to draw from it is that the column is derived from the tree,
not from the kind of egui widget a block uses.
The lint check needs a cold cache. cargo replays cached
diagnostics for a crate it considers fresh, so running the
-W clippy::too_many_lines command twice prints the warnings the
first time and nothing the second. Touch a file in the crate --
touch ryll/src/main.rs -- before each run, or the check passes by
printing nothing at all. The definition of done says so now.
Step 4a corrected the plan. draw_webdav_panel needs
ctx: &egui::Context as well as ui: its body calls
ctx.request_repaint_after. Survey finding 1's inventory table and
the step 4a brief both said ui alone, which is wrong and would
not compile; both are corrected above. The survey's own
measurements had it right, so this was a transcription error in the
plan rather than a wrong reading of the tree.
A step was added: 4h. The definition of done says no function
under ryll/src/app/ may exceed 100 lines by clippy's count except
RyllApp::new and reconnect, but the step table had no step that
could deliver it. Step 4a's draw_usb_panel is 210 lines and
draw_notifications_panel 123 -- they were always that long, hidden
inside a 1,390-line ui, and the survey measured them before the
criterion was written. The criterion was the error, not the step.
Offered the choice between splitting them and recording them as
exceptions for phase 6, the operator chose to split, so step 4h
sweeps whatever clippy still names once the moves are done. The
definition of done stands as written.
app/mod.rs also loses four imports in step 4a -- format_size,
TrafficDirection, usb::{self, DeviceSource} -- because their
only users moved. That is not a body edit; clippy denies unused
imports, so the step could not have left them.
Rebased onto develop at 8381d96 on 2026-11-15 (AEDT), after
session-relay reported #726 CONFLICTING: #718
(session-follows-server) and #725 (input accounting) landed while
the pull request was open. One conflict, in app/mod.rs, from the
one file both sides changed. #718 added a ModalVariant::ServerEnded
arm and wrapped the modal body in a ScrollArea -- inside the
reconnect modal that step 4d had already moved to
app/ui/dialogs.rs. Resolved by taking the move in mod.rs and
porting both additions onto the moved copy, with
server_ended_body imported there instead; mod.rs keeps only
forbid_retry_modal and ReconnectState from reconnect. The
resolution sits in 4d's own commit, so the moved body still matches
the base line for line: 70 lines either side of the move, nothing
lost and nothing added.
That rebase also breaks one definition-of-done item, and not
because of this phase: no file under ryll/src/app/ except
mod.rs may exceed 800 lines, and reconnect.rs is now 881 on
develop itself, where #718 added 350 lines to it. Phase 4 never
touches that file. Recorded here rather than ticked, relaxed or
swept into this phase's scope; reconnect.rs belongs to a later
phase's inventory.
The manual guest run (back brief point 2) happened on 2026-11-15
against the XFCE desktop guest, and the panels, dialogs and cursor
were confirmed by hand. It needed make test-qemu-desktop
QEMU_SPICE_PORT=5901: andris holds 127.0.0.1:5900 on this host, and
the target's default port is 5900, so qemu exits before it
daemonizes and make still prints a connect line for a guest that
is not there.
Back brief¶
Before executing any step, back brief the operator on your understanding of the plan. Three points need an answer first:
-
The file set and the draw order (the inventory table in survey finding 1 and the sequence in decision 6). This is cheap to agree and expensive to redo: once the blocks are moved, changing which file one lives in is another full move.
-
Whether a manual run against the desktop test guest is wanted before the pull request. Risk 1 is the phase's only test-invisible risk, and
make desktop-guestplus a GUI run is the only way to see it. It needs a human at the desktop session, so it is the operator's call, not a step. -
Whether this session may push and open the pull request.