TUI State Management in XHS-Downloader#

Overview#

XHS-Downloader's Textual TUI routes all application log output through a single shared Print wrapper object on the XHS application instance. This object holds a mutable func pointer that each TUI screen overwrites in its on_mount handler — with no corresponding teardown when the screen is popped. The result is that the pointer can be left pointing at a destroyed widget, causing silent state corruption when the user navigates between screens.

The Print Wrapper#

Print is a small callable wrapper defined in source/application/app.py:

• Constructed with func = rich.print (the default terminal printer).
• XHS.__init__ creates self.print = Print() and passes it down to Manager for use throughout the application layer 1.
• All application-level messages are emitted via XHS.logging, which calls logging(self.print, text, style) in source/module/tools.py. That helper calls self.print() to get the current callable, then dispatches either func(string) (for rich.print) or func.write(string, scroll_end=True) (for a Textual RichLog widget) 2.

Because XHS is a singleton 3, the Print object and its func pointer are global to the entire TUI session.

How Screens Claim the Output Target#

Both interactive TUI screens redirect output by assigning their own RichLog widget to xhs.print.func inside on_mount:

There is no on_unmount or equivalent teardown in either screen that resets func back to rich.print or to the other screen's widget.

Lifecycle and Corruption Risk#

The TUI app initializes and pushes the Index screen on mount 4. Navigation flow when entering and exiting clipboard monitor mode:

Index (on_mount → sets print.func = Index.RichLog)
  └── push_screen(Monitor(...))
        └── Monitor (on_mount → sets print.func = Monitor.RichLog)
              └── action_close → app.action_back() ← Monitor is popped
                    # print.func now points to Monitor's destroyed RichLog
                    # Index.on_mount does NOT re-run; func is never reset

When Monitor.action_close is called 5, it stops the monitor loop and calls app.action_back(). Textual pops Monitor off the screen stack, but print.func is never restored. Any subsequent call to XHS.logging will try to call .write() on the now-unmounted RichLog from Monitor, instead of the visible Index log widget.

The same issue applies to the settings refresh flow: refresh_screen tears down and recreates all screens, meaning the Index screen gets a brand-new RichLog — but print.func still points to the old (destroyed) widget until the new Index mounts and reassigns it.

Key Entry Points for Debugging / Fixing#

Mitigation approaches to consider:

• Add an on_unmount handler to Monitor that resets self.xhs.print.func = print (or to a sentinel that drops writes silently).
• Implement on_resume in Index (Textual's callback for when a screen returns to focus) to re-assign print.func to its own RichLog, ensuring the pointer is always valid when Index is the active screen.