Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/107. This local document is retained as an engineering spec/evidence record.

FEAT-100 - Improve startup progress and UI readiness locking

Summary

Make startup progress and startup-time UI locking coherent. The current app has early and main-window startup progress dialogs, but repainting depends on broad message pumping while the app is only partially initialized. That keeps the dialog visible, but it can also dispatch normal commands, timers, or UI work before the shell, services, network, and shared-file state are fully ready.

This item owns the broader lifecycle safety and UX pass. Existing narrower items remain the owners for specific heavy startup paths:

  • FEAT-072: startup cache and shared-library startup blocking
  • FEAT-075: daily config backup progress responsiveness
  • FEAT-034: shared-files reload and scan responsiveness

Current Evidence

  • CLifecycleProgressDlg is shared by startup and shutdown progress.
  • PumpLifecycleProgressMessages currently peeks and dispatches all queued messages, with only dialog-message handling special-cased.
  • Early startup progress is shown before preferences and core services finish initialization.
  • Main-window startup progress is shown while the modal main dialog is created and while UM_STARTUP_NEXT_STAGE advances startup phases.
  • Several startup phases still contain blocking I/O or large in-memory work, especially daily config backup and shared startup cache/load/scan paths.

Intended Shape

  1. Add a lifecycle progress controller.
  2. Own startup and shutdown progress phase state in one place.
  3. Preserve monotonic percent updates.
  4. Rate-limit repaint/pump work.
  5. Track elapsed time and last visible progress update for diagnostics.

  6. Keep early startup and main-window startup transitions explicit.

  7. Restrict lifecycle message pumping.

  8. Replace broad PeekMessage dispatch during lifecycle progress with a narrow pump for paint/dialog/lifecycle-safe messages.
  9. Do not let arbitrary commands, normal timers, hotkeys, tray actions, or mutating REST work run while startup is incomplete.

  10. Keep shutdown pumping similarly constrained so teardown cannot reenter normal app workflows.

  11. Add a startup readiness gate.

  12. Define explicit startup readiness states such as shell creating, UI created, services starting, network starting, and startup complete.
  13. Centralize command availability for toolbar buttons, menus, tray commands, hotkeys, and mutating REST commands.

  14. Make disabled/blocked commands explainable in logs or diagnostics where appropriate.

  15. Add progress callbacks for known blocking paths.

  16. Start with daily config backup callbacks from FEAT-075.
  17. Add rate-limited progress reports for shared startup cache and scan loops under FEAT-072.

  18. Keep callbacks side-effect-light and testable; they should update lifecycle progress only, not advance normal app work.

  19. Improve the visible dialog after the safety model is clear.

  20. Consider a dedicated startup progress dialog resource instead of reusing the shutdown progress resource.
  21. Use stable text areas for header, phase, detail, and optional elapsed time.
  22. Use marquee mode for unknown-duration I/O and determinate mode for known phase progress.
  23. Avoid a cancel button unless there is a real safe abort contract.

Scope Constraints

  • Do not change eD2K/Kad protocol behavior or startup network defaults.
  • Do not dispatch normal app commands from lifecycle progress pumping.
  • Do not mutate MFC UI, shared-file owner state, or network state from worker threads.
  • Do not make daily config backup asynchronous in the first slice; keep its early snapshot ordering until a separate worker-backed plan proves safe.
  • Do not treat visual polish as complete while broad lifecycle message pumping remains unsafe.

Acceptance Criteria

  • [ ] Startup and shutdown progress use a shared lifecycle progress controller.
  • [ ] Lifecycle message pumping is restricted to approved paint/dialog/lifecycle messages.
  • [ ] Toolbar, menu, tray, hotkey, and mutating REST commands respect centralized startup readiness state.
  • [ ] Startup progress remains repaintable during daily config backup and large shared startup cache/load/scan work.
  • [ ] Progress diagnostics expose stale progress updates or long unpumped startup phases.
  • [ ] Native tests cover lifecycle pump filtering, readiness gate decisions, monotonic progress updates, and progress callback cadence.
  • [ ] Startup profiling or live evidence shows no broad command/timer reentry during startup progress pumping.

Validation

  • python -m emule_workspace validate
  • focused native tests for lifecycle progress controller and readiness gates
  • focused native tests for backup/cache progress callback cadence
  • x64 Debug and Release app builds before implementation commit