Skip to content

qt start: first frame in 0.3 s at phone speed; APK ships bytecode; settings pages build lazily - #2104

Merged
trissim merged 6 commits into
mainfrom
fork-qt-startup
Nov 18, 2026
Merged

trissim merged 6 commits into
mainfrom
fork-qt-startup

Conversation

@trissim

@trissim trissim commented Nov 18, 2026 •

Copy link
Copy Markdown

Qt start at phone speed (desktop throttled to 45% of one core, Android's in-thread renderer, warm bytecode unless noted).

before (main) after
first frame 9.2 s (the app window) 0.31 s (QtSplash: the welcome banner on the theme background)
app window paints 9.2 s 9.3–9.4 s
ApplicationStart done (sidebar rows) 17.5 s 16.2 s
first start after an install (client imports, shipped app folder) 14.8 s (compiles everything) 10.1 s (ships -O1 bytecode)
application action summaries on the phone all 10 blank (p4a runs -OO: docstrings stripped) all 10 present
settings dialog: construct / show→first paint 680–780 ms / 29–102 ms 6–8 ms / 2 ms

Not met: usable within 3 s. The app window still waits on the client's imports: 7.8 s at this throttle, 82% of the start in py-spy (agent_comms 51% of import self-time, toad 16%, acp 8%, nominal_refactor_advisor 7%). Making agent_comms' Core annotation-only on the client path (13 modules, TYPE_CHECKING, NRA imported lazily) measured 7.6 → 7.49 s, inside noise, so it is not in this PR. Comms still loads at runtime through cli_verbs/cli_command.Command[Comms, Answer] (via team_heartbeat → cli_bridges), and native_pi/acp load through registry/threads → agent_backend → pi_commands. Getting under 3 s means the client's ui_model.observation stops importing server-side readings (TeamHudReading) and registry/threads stops importing the backend.

Changes:

  • First frame before the client loads. toad.qt.main and toad.qt.android import only Qt and the theme, paint QtSplash, then load the client. StepAside closes the splash when the client window shows. open_app/serve moved to toad.qt.client_start, the held-bus connection moved to toad.qt.android_bus, and the banner moved to toad.welcome_banner/toad.qt.banner, which have no Core imports. The APK's start, closure.py and bundle_check.py all load the client through toad.qt.android.load_client(), so what ships and gets checked is what runs.
  • The APK runs at -O1 and ships bytecode for it. p4a's PythonActivity sets PYTHONOPTIMIZE=2, which strips the docstrings that MenuDeclaration.key_summary and ApplicationAction.summary return, so every action description was blank on the phone. ToadActivity overrides setEnvironmentVariable (PythonActivity sets the interpreter environment through it, before Qt starts Python) to set PYTHON_OPTIMIZE = 1: asserts dropped, docstrings kept. recipe_built.python_optimize reads that one constant. assemble.py compiles only the shipped packages at that level with unchecked-hash invalidation, because source and bytecode unpack together and unpacking resets mtimes. buildozer ships .pyc. bundle_check and shipped_run run the app at the phone's level with -B. bundle_check fails if a shipped module lacks bytecode for that level or if any application action's summary is empty.
  • Settings pages are built lazily. This uses the rule qt frame budget: measured stutter and tab-open stalls removed at their owners (sticky header, row roles, notifications, lazy panel pages, sidebar groups, GC freeze) #2102 applied to panel menus, now LazyPages, which PanelMenuModel and SettingsEditing both inherit. Qt builds the shown page after the dialog's first paint. Textual's switcher keeps every page mounted, so it still builds all of them.
  • settle_heap and the first bus read (follow_sidebar) already run inside the ApplicationStart operation, after the window opens. The 18% field_codec decode in the startup profile is the saved settings file being decoded during QtToadApp.__init__ (open_settings), not the bus read. Both now come after the first frame.

Gates on the final head: qt_inherit_ratchet passes (bare 21/21, copies 0; QtSplash and StepAside are declared Qt-only); shadow_check 0; tools/android/check.sh exit 0 on the final head: closure; assemble (3048 .opt-1.pyc, none at other levels); "shipped bytecode is cpython-314.opt-1.pyc"; "every application action has a summary"; bundle check 15/15 baseline; shipped app ran every view kind and bound key. On the assembled bundle at PYTHONOPTIMIZE=1, all 1725 loaded app modules have their shipped cache file and all 10 summaries are present. At p4a's default of 2, none of the shipped files are used and all 10 summaries are blank. The touched TUI tests (settings, forms, welcome, panels) have the same 11 failures on main and on this branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3

trissim and others added 6 commits November 18, 2026 01:53
Qt showed nothing for 9.2 s at a phone's speed: the entries (toad.qt.main, toad.qt.android)
imported the whole client (Core's wire records, the transport, every view) before
QApplication painted anything. The entries now import only Qt and the theme, paint
QtSplash (the welcome's banner on the theme's background), then load the client; the
splash steps aside when the client's window shows.

- toad.welcome_banner owns the banner text (it imported Core's sidebar model through
  toad.client.welcome); toad.qt.banner owns Qt's Banner (from qt/window.py).
- toad.qt.client_start holds open_app/serve (from qt/main.py); toad.qt.android_bus holds
  the held-bus connection (from qt/android.py). toad.qt.android.load_client is the one call
  that loads the client: the APK's start makes it after the first frame, and closure.py
  and bundle_check.py make it, so what the APK bundles and checks is what runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…ompile the client

An install unpacks the app folder afresh, so the bytecode the last start wrote is gone and
the next start compiles every module: imports took 14.0 s instead of 8.1 s at a phone's
speed. assemble.py compiles the app folder as the phone runs Python (optimization 2, the
.opt-2.pyc the phone writes itself), unchecked-hash since source and bytecode always
unpack together; buildozer ships .pyc.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…reen's frame paints

Qt's settings screen built every page's form before its first frame: 680-780 ms of the
loop at a phone's speed, ahead of the pending indicator. The rule the sidebar panel menu
used (a page realized when first shown) is now LazyPages, which PanelMenuModel and
SettingsEditing both inherit. FieldViews tells which fields a form shows without building
their views; FieldForm.pages answers each page's builder. Qt builds the shown page once the
screen's frame has painted; Textual's switcher keeps every page mounted, so it builds each
as it composes. Edits, search and discard reach the built pages; a page built later starts
from the current search.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
… bytecode

QtSplash and StepAside are declared Qt-only with the fact that keeps them out of the shared
tree. bundle_check and shipped_run run the assembled app folder with -B, since that folder
now ships the bytecode assemble.py compiled and their runs would add their own beside it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
compileall's worker pool died mid-compile under the build interpreter (ConnectionResetError
from a pool worker), failing assemble; one process compiles the 3049 files reliably.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…keeps its summary

python-for-android's activity sets PYTHONOPTIMIZE=2, which strips docstrings, and the menus'
and actions' summaries are their docstrings (MenuDeclaration.key_summary,
ApplicationAction.summary): all ten application actions had a blank summary on the phone.
ToadActivity replaces that level with PYTHON_OPTIMIZE = 1 (asserts dropped, docstrings kept)
through the setEnvironmentVariable PythonActivity sets the interpreter's environment with,
before Qt starts Python. recipe_built.python_optimize reads that one constant: assemble.py
compiles the shipped packages at it (only them, not the build state in the app folder), and
bundle_check and shipped_run run the app at it. bundle_check now fails when a shipped module
lacks bytecode for that level or an application action's summary is empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant