Skip to content

feat(ui): add PWA launch veil and skeleton loading states - #17

Merged
phatpham9 merged 2 commits into
mainfrom
feat/pwa-loading-ux
Nov 13, 2026
Merged

phatpham9 merged 2 commits into
mainfrom
feat/pwa-loading-ux

Conversation

@phatpham9

@phatpham9 phatpham9 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

PWA launch experience

  • Added a theme-matched launch veil that is rendered in the server HTML but only displayed in an installed/standalone PWA. It uses the inline pre-paint theme, so it matches the current theme immediately.
  • app.js fades the veil out after the first content frame and removes it from the DOM. Browser tabs never display it, so it cannot affect browser LCP.
  • Standalone detection lives in theme-init.js (display-mode: standalone plus iOS navigator.standalone).

Feed skeleton loading and transitions

  • Replaced the toast-only feed loading state with skeleton cards that mirror the real card's title/brief/host rhythm.
  • Skeletons appear after 150 ms when a feed is already on screen (immediately on an empty grid), so fast responses never flash a placeholder.
  • Replace loads snapshot the current grid and restore it if the request fails; View more appends three skeleton rows at the bottom.
  • Completed replace loads crossfade through the View Transitions API where available, with a Web Animations fade fallback. Appended cards get a short staggered fade-in.
  • prefers-reduced-motion: reduce disables shimmer, view transitions, and Web Animations while keeping the state changes.
  • Accessibility: the grid exposes aria-busy, skeleton cards are aria-hidden, and a visually hidden live region announces loading messages.

Article preview loading state

  • The preview panel keeps the card title visible while loading and replaces the visible “Loading preview…” text with a preview skeleton after 150 ms.
  • The loading status stays in the live region but is visually hidden (sr-only); it becomes visible again only for the empty/error messages.
  • On success, the updated title and loaded content fade in. On failure or abort, the skeleton is cleared and the readable error status is shown.
  • Reduced motion disables the skeleton shimmer and the title/content fade.
  • Verified the delayed skeleton, 30 rendered content blocks on success, the error state after a simulated failure, and zero skeleton/WAAPI animation under prefers-reduced-motion.

Search field

  • Suppressed the browser's native type="search" clear control so the app's search toggle/close button is the only clear affordance. Typing in the field no longer shows a second X.

Housekeeping

  • Bumped app.js to v108 and the service-worker shell cache to reader-shell-v142.
  • Added render hook tests (core/test/render.spec.ts) and updated README, ARCHITECTURE, DEPLOYMENT, and RUNBOOK.

Verification

  • npm run typecheck
  • npm test — 87 passing
  • npm run db:migrate:local
  • wrangler deploy --dry-run
  • npm audit — 0 vulnerabilities
  • Chrome DevTools checks:
    • Browser tab: launch veil computed display: none, then removed from the DOM
    • Mocked standalone: data-standalone="true", veil computed display: grid, removed after the fade
    • Search/filter load: 12 skeleton cards, aria-busy=true, live status Searching feed…, then 12 real cards
    • View more: 12 real cards + 3 skeleton rows, then 24 real cards
    • Simulated failed feed load after skeletons: skeletons removed, previous 24 cards restored, aria-busy=false
    • View transition path invoked once on a successful replace
    • Preview load: card title + preview skeleton, then skeleton removed with 30 content blocks and the full title/byline/reading time
    • Simulated failed preview: skeleton removed, error status visible, byline/reading meta hidden
    • Reduced motion: skeleton animation-name: none, zero view-transition and WAAPI calls
    • Search field: only the app's close control remains; no native clear X
    • Cold mobile trace: LCP 292 ms, no render-blocking requests, no forced reflow

Notes

🤖 Generated with Claude Code

- Show a theme-matched launch veil only in installed/standalone PWAs; it
  fades out after the first content frame and is never rendered in a browser
  tab, so it cannot regress browser LCP
- Replace toast-only feed loading with delayed skeleton cards: 150 ms delay
  when cards are already visible, immediate on an empty grid; replace loads
  snapshot and restore the previous grid on failure, View more appends three
  skeleton rows
- Crossfade skeleton/content through the View Transitions API with a Web
  Animations fallback; disable shimmer and transitions under
  prefers-reduced-motion
- Add aria-busy on the grid, aria-hidden skeleton cards, and a visually
  hidden live status region for loading messages
- Suppress the browser's native type=search clear control so only the app's
  search toggle/close button remains
- Bump app.js to v107 and the service-worker shell cache to v141; add render
  hook tests and update README/ARCHITECTURE/DEPLOYMENT/RUNBOOK

Verified: 87 tests, typecheck, wrangler dry-run, 0 audit findings; browser
and standalone launch states, replace/append skeletons, failed-load restore,
view-transition usage, reduced-motion behavior, and search-field rendering
were exercised in Chrome DevTools.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🔎 Cloudflare preview: https://3b6149f0-feedreader.phatpham9.workers.dev

Uploaded from ac66e7b4fe6a617495c47b3dc3bff62942cb750b. This is a Worker version preview — it shares the production D1 database, so it reads/writes real data; it does not receive cron-triggered refreshes.

- Keep the card title visible while a preview loads and replace the visible
  "Loading preview…" text with a preview skeleton after 150 ms
- Hide the loading status visually (sr-only) but keep it in the live region;
  clear the skeleton on completion, abort, or failure
- Fade the updated preview title and loaded content in; respect reduced motion
  and skip all view/Web Animations when requested
- Add preview skeleton styles and bump app.js to v108 / shell cache to v142
- Update README, ARCHITECTURE, and RUNBOOK

Verified in Chrome DevTools: delayed skeleton with card title, skeleton removal
and 30 rendered content blocks on success, focused error state on failure, and
zero skeleton/WAAPI animation under prefers-reduced-motion.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@phatpham9
phatpham9 merged commit e6f621e into main Nov 13, 2026
3 checks passed
@phatpham9
phatpham9 deleted the feat/pwa-loading-ux branch November 13, 2026 03:27
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