|
| 1 | +--- |
| 2 | +id: task-250 |
| 3 | +title: Fix startup rendering flash - hide UI scaffolding until ready |
| 4 | +status: To Do |
| 5 | +assignee: [] |
| 6 | +created_date: '2026-02-03 07:16' |
| 7 | +updated_date: '2026-02-03 07:18' |
| 8 | +labels: |
| 9 | + - frontend |
| 10 | + - ux |
| 11 | + - polish |
| 12 | + - startup |
| 13 | +dependencies: [] |
| 14 | +priority: medium |
| 15 | +--- |
| 16 | + |
| 17 | +## Description |
| 18 | + |
| 19 | +<!-- SECTION:DESCRIPTION:BEGIN --> |
| 20 | +## Problem |
| 21 | + |
| 22 | +During app startup (first 1-2 seconds), the UI flashes various components before they're properly sized and styled. Users see the scaffolding of the app (unstyled/unsized components) before everything is in place. |
| 23 | + |
| 24 | +## Evidence |
| 25 | + |
| 26 | +**Original recordings:** |
| 27 | +- `~/Desktop/Kapture 2026-02-03 at 01.10.38.mp4` (7s video, issue visible in first ~3s) |
| 28 | +- `~/Desktop/Kapture 2026-02-03 at 01.10.38.gif` (same timing) |
| 29 | + |
| 30 | +**Extracted key frames** (213 total frames at 30fps): |
| 31 | +- `docs/evidence/startup-flash/01-initial-state.png` - Frame 1: Empty olive background, no content area |
| 32 | +- `docs/evidence/startup-flash/02-pre-content.png` - Frame 61: Main area still empty, sidebar rendered |
| 33 | +- `docs/evidence/startup-flash/03-loading-state.png` - Frame 62: Column headers appear (#, Title, Artist, Album), loading spinner |
| 34 | +- `docs/evidence/startup-flash/04-content-loaded.png` - Frame 74: Content populated with track list |
| 35 | + |
| 36 | +**Timeline analysis:** |
| 37 | +- Frames 1-61 (~2 seconds): Empty scaffolding visible |
| 38 | +- Frames 62-73 (~0.4 seconds): Loading state with headers but no content |
| 39 | +- Frames 74+: Final rendered state |
| 40 | + |
| 41 | +## Expected Behavior |
| 42 | + |
| 43 | +The end user should not see any scaffolding or unstyled components. The app should either: |
| 44 | +1. Show nothing (blank/background) until fully ready |
| 45 | +2. Show a minimal splash/loading indicator until all components are sized and styled |
| 46 | +3. Use CSS techniques to prevent FOUC (Flash of Unstyled Content) |
| 47 | + |
| 48 | +## Technical Considerations |
| 49 | + |
| 50 | +- Consider using `visibility: hidden` or `opacity: 0` on the root container until Alpine.js initializes and styles are computed |
| 51 | +- May need to coordinate with Tauri window show/hide to prevent flash |
| 52 | +- Could use `x-cloak` directive pattern from Alpine.js |
| 53 | +- Ensure all async data (library stats, playlists, etc.) is loaded before reveal |
| 54 | +- Test with both cold starts and hot reloads |
| 55 | +<!-- SECTION:DESCRIPTION:END --> |
| 56 | + |
| 57 | +## Acceptance Criteria |
| 58 | +<!-- AC:BEGIN --> |
| 59 | +- [ ] #1 No visible flash of unstyled/unsized content during app startup |
| 60 | +- [ ] #2 All components are properly sized and styled before becoming visible |
| 61 | +- [ ] #3 Startup experience feels polished and professional |
| 62 | +- [ ] #4 Works consistently across cold starts and app restarts |
| 63 | +- [ ] #5 No regression in startup time (or minimal acceptable increase) |
| 64 | +<!-- AC:END --> |
0 commit comments