From 02c59591d8744a3750b2669e7d897eb3ce748064 Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 10:08:57 +0700 Subject: [PATCH 1/2] feat(ui): add PWA launch veil and skeleton loading states - 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 --- README.md | 11 +- core/render.ts | 10 +- core/test/render.spec.ts | 43 +++++ docs/ARCHITECTURE.md | 8 + docs/DEPLOYMENT.md | 1 + docs/RUNBOOK.md | 13 ++ web-static/service-worker.js | 4 +- web-static/static/app.js | 285 +++++++++++++++++++++++++++----- web-static/static/style.css | 241 +++++++++++++++++++++++++++ web-static/static/theme-init.js | 11 ++ 10 files changed, 576 insertions(+), 51 deletions(-) create mode 100644 core/test/render.spec.ts diff --git a/README.md b/README.md index c934e49..76566ca 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ npx lighthouse https://reader.boringcode.dev --view - **Persisted visited-link dimming** for feed card titles across reload/reopen using local storage - **Optional article preview** (off by default, toggled in Reader settings) that opens a reader view beside the feed on wide screens or full-screen on phones, with inline links/emphasis, image captions, tables, publication date/reading time, source-specific Hacker News comments, and an **Open source** button - **Saved articles** with an optional per-card bookmark toggle, a `Saved` filter, and a preview-panel toggle; bookmark controls are disabled by default and can be enabled in Reader settings, with saved items stored locally under `feedreader.bookmarks` -- **PWA-ready assets and offline caching** including manifest, service worker, touch icons, cached shell assets, and cached `/api/items` responses for previously visited views +- **PWA-ready assets and offline caching** including manifest, service worker, touch icons, cached shell assets, cached `/api/items` responses for previously visited views, a standalone launch veil, and skeleton loading states - **Reconnect list refresh** re-fetches the current view from backend stored items only; it does **not** refresh upstream sources - **Cloudflare-native deployment** with Workers, D1, Cron Triggers, and Workers Static Assets @@ -312,16 +312,21 @@ Presentation-layer note: - typing is debounced and only triggers the search API once the query reaches at least 2 characters - closing the search control clears the query and resets the feed only when an active query exists - closing an empty visible search box just hides the control and does not refetch `/api/items` +- the browser's native `type="search"` clear button is suppressed so the app's search toggle/close control is the only clear affordance ### Loading and empty states -- first-load bootstrap queries, source filter changes, searches, `View more`, and header refresh all show an explicit toast-based loading state -- source-filter changes use the generic loading toast text `Loading feed…` +- first-load bootstrap queries, source filter changes, searches, `View more`, and header refresh use skeleton cards instead of a loading toast +- skeletons appear after a short delay (150 ms when a feed is already on screen, immediately when the grid is empty) so fast responses do not flash a placeholder; replace loads swap the current grid for skeleton cards, while `View more` appends three skeleton rows +- the grid exposes `aria-busy` while loading, skeleton cards are `aria-hidden`, and a visually hidden live region announces the loading message +- completed loads crossfade into the new cards using the View Transitions API where available and a Web Animations fade as the fallback; a failed request restores the previous cards +- `prefers-reduced-motion: reduce` disables shimmer and transition animations while keeping the state changes - source-filter and search requests that return zero items replace the list with an empty-state message instead of leaving stale cards on screen - `View more` disables itself while an append request is in flight and hides itself when the current result set has no further page ### Offline and connectivity +- installed PWAs show a theme-matched launch veil instead of a blank frame while the shell starts; it fades out after the first content frame and is never displayed in a regular browser tab - the app shell and previously fetched `GET /api/items` views are cached by the service worker for offline reuse - this offline/PWA behavior requires a secure-context origin where service workers are available (for example `localhost` or HTTPS) - when the browser goes offline, a no-wifi indicator appears in the header action row instead of showing connectivity toasts diff --git a/core/render.ts b/core/render.ts index ed474ed..6d46210 100644 --- a/core/render.ts +++ b/core/render.ts @@ -195,9 +195,16 @@ export function renderIndexPage(data: PageData): string { - + +