Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -363,6 +368,8 @@ Presentation-layer note:
### Article preview

- when enabled in Reader settings, clicking any card (including its title) loads a reader view in a right-hand panel instead of opening a new tab
- while the preview request is in flight, the panel keeps the card title and shows a preview skeleton after a short delay; the loaded title and content fade in, and a failed request replaces the skeleton with a readable error message
- the visible loading message is visually hidden while the skeleton is shown; the panel remains `aria-busy` and a live region announces the loading state
- `Cmd`/`Ctrl`/`Shift`-clicking a title still opens the article in a new tab
- the panel shows the extracted title, byline, publication date/reading time, rich text with validated inline links/emphasis/inline code, image blocks with captions and intrinsic dimensions, and semantic tables; images load directly from the source with lazy loading and no referrer; `Open source` opens the original page
- consecutive list items render as one list and prose uses the full preview width; figures are capped in height so a single image cannot dominate the panel
Expand Down
10 changes: 9 additions & 1 deletion core/render.ts
Original file line number Diff line number Diff line change
Expand Up @@ -195,9 +195,16 @@ export function renderIndexPage(data: PageData): string {
<link rel="apple-touch-icon" href="/apple-touch-icon.png?v=8" />
<script>${data.themeInitScript}</script>
<style>${data.inlineCss}</style>
<script src="/static/app.js?v=106" defer></script>
<script src="/static/app.js?v=108" defer></script>
</head>
<body data-app-version="${escapeHtml(data.appVersion)}">
<div class="boot-veil" data-boot-veil aria-hidden="true">
<div class="boot-veil-brand">
<img class="boot-veil-mark" src="/favicon.svg?v=8" alt="" aria-hidden="true" />
<span class="boot-veil-wordmark">reader<span class="boot-veil-dot">.</span></span>
</div>
<span class="boot-veil-track" aria-hidden="true"><span class="boot-veil-bar"></span></span>
</div>
<header class="shell page-header">
<div class="toast" data-toast role="status" aria-live="polite"></div>
<div class="header-top">
Expand Down Expand Up @@ -503,6 +510,7 @@ ${errorsBlock}
</svg>
Personalized by AI
</p>
<p class="sr-only" data-feed-status role="status" aria-live="polite"></p>
<section class="cards-grid${cardsHiddenClass}" data-card-grid data-current-source="${escapeHtml(data.currentSource)}" data-page-size="${data.pageSize}" data-has-next="${data.hasNext ? "true" : "false"}" aria-busy="false">
${data.cards.map(renderCard).join("\n ")}
</section>
Expand Down
43 changes: 43 additions & 0 deletions core/test/render.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import { describe, expect, it } from "vitest";
import { renderIndexPage } from "../render.ts";

function renderPage(): string {
return renderIndexPage({
cards: [],
errors: [],
sourceFilters: [],
currentSource: "all",
searchQuery: "",
searchOpen: false,
emptyMessage: "No items yet.",
pageSize: 12,
hasNext: false,
currentYear: 2026,
canonicalUrl: "https://example.com/",
socialImageUrl: "https://example.com/og.png",
appVersion: "test",
inlineCss: ":root{--bg:#000}",
themeInitScript: "document.documentElement.dataset.theme='dark';",
});
}

describe("renderIndexPage", () => {
it("renders the launch veil and accessible feed status hooks", () => {
const html = renderPage();
expect(html).toContain('class="boot-veil" data-boot-veil aria-hidden="true"');
expect(html).toContain(
'<p class="sr-only" data-feed-status role="status" aria-live="polite"></p>',
);
});

it("inlines the theme/bootstrap assets and versions app.js", () => {
const html = renderPage();
expect(html).toContain("<style>:root{--bg:#000}</style>");
expect(html).toContain(
"<script>document.documentElement.dataset.theme='dark';</script>",
);
expect(html).toContain('/static/app.js?v=108');
expect(html).not.toContain("style.css");
expect(html).not.toContain("theme-init.js");
});
});
9 changes: 9 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,15 @@

Browser-only preferences and reading state live in `localStorage`: theme preference (including Auto, which follows the device), density, visible sources, the article-preview and bookmark-visibility settings, visited links, and saved articles. Bookmarks store a display snapshot and never leave the device, so they survive source pruning and offline use without a server API.

## Loading and launch states

- The inline pre-paint theme script also records `display-mode: standalone` (and iOS `navigator.standalone`) as `data-standalone`. The server renders a lightweight boot veil; CSS only displays it in an installed app, and `app.js` fades and removes it after the first content frame. Browser tabs never see it, so it does not affect LCP.
- Client-side feed loads use skeleton cards. A 150 ms delay avoids flashing placeholders on fast responses when a feed is already on screen (an empty grid shows them immediately); replace loads snapshot the current grid so a failed request can restore it, and append loads add three skeleton rows at the bottom.
- The reader preview uses the same delayed-skeleton idea: the card title stays visible, a preview skeleton replaces the visible loading message after 150 ms, and the loaded title/content fade in. Aborts and failures clear the skeleton and restore the readable status message.
- Skeleton cards are `aria-hidden`; the grid sets `aria-busy`, and a visually hidden live region carries the loading message.
- Completed replace loads crossfade through the View Transitions API when available, with a Web Animations fade fallback. `prefers-reduced-motion: reduce` disables shimmer and both transition paths.
- The search field hides the browser's native `type="search"` clear control; the app's search toggle/close button is the only clear affordance.

## Data model and refresh behavior

- Items are upserted by `(source, external_id)`.
Expand Down
1 change: 1 addition & 0 deletions docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ The checked-in `wrangler.toml` config does not hardcode a route. Domain attachme
- D1: 5GB storage, 5M row reads/day, 100k row writes/day.
- Workers: 100k requests/day, 10ms CPU time per invocation, 50 subrequests per request.
- The five-minute home-page cache absorbs most `GET /` traffic, so only cache misses run the feed query and render the HTML. Each cold-isolate cache miss also reads `style.css` and `theme-init.js` through the `ASSETS` binding (two local subrequests), then reuses them in memory.
- The standalone launch veil and skeleton styles are inlined with the existing HTML/CSS, so they add no extra requests. Bump the shell cache version when the HTML shell or `app.js` changes; see [RUNBOOK.md](RUNBOOK.md#pwa-shell-updates).
- Article previews add one outbound fetch (and one `node-html-parser` parse) per uncached `/api/preview` request. The 400 KB body cap and 30-minute edge cache in `core/preview.ts` bound that cost; watch the CPU-time panel if preview usage is heavy. Richer preview blocks (inline links, captions, tables) increase the cached response payload but not the upstream fetch count; the same byte cap and cache TTL apply.

Check the Cloudflare dashboard's D1 usage and Workers CPU-time panels periodically — see [RUNBOOK.md](RUNBOOK.md) for what to do if a source consistently nears the CPU ceiling.
14 changes: 14 additions & 0 deletions docs/RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,11 @@ Before considering any `core/render.ts` change done:
3. Load `http://127.0.0.1:8788` and verify:
- the document has no external `style.css` or `theme-init.js` request; both are inlined in `<head>`
- the response carries `Cache-Control: public, max-age=0, s-maxage=300`
- in a regular browser tab the launch veil stays hidden (`display: none`) and is removed from the DOM; in an installed/standalone window it is visible and fades out within about a second
- throttle the network, then change a source filter or run a search: skeleton cards appear after ~150 ms and are replaced by the new cards; `View more` appends three skeleton rows
- enable article preview, throttle the network, and open a card: the card title stays visible while a preview skeleton appears in the panel, then the fetched title/content fade in; a failed preview clears the skeleton and shows the error status
- with `prefers-reduced-motion: reduce`, skeleton shimmer and the view/Web Animations transitions are disabled
- typing in the search box shows only the app's close control, not a second native clear X
- header actions render correctly
- source filters and search controls render correctly
- the reader settings dialog opens and closes, its Appearance/Reading/Sources tabs switch via click and arrow keys, and Cancel/Save show their icons
Expand All @@ -117,3 +122,12 @@ Before considering any `core/render.ts` change done:
- enabling bookmarks in Reader settings, bookmarking a card, confirming the Saved count and view, then reloading to confirm the bookmark persists; disabling bookmarks hides the card/preview controls and Saved filter, leaves the Saved view, and re-enabling restores the saved item

4. If the change also affects `/api/items`, hit the endpoint directly and verify the JSON shape still matches what `web-static/static/app.js` expects.

## PWA shell updates

The launch veil and skeleton styles are part of the server-rendered HTML/CSS shell. When changing `core/render.ts`, `web-static/static/style.css`, `web-static/static/theme-init.js`, or `web-static/static/app.js`:

- bump the `app.js?v=` value in `core/render.ts` and `web-static/service-worker.js`
- bump `SHELL_CACHE` in `web-static/service-worker.js`

The service worker navigation handler is network-first, but the version bump ensures installed clients install the new shell atomically.
4 changes: 2 additions & 2 deletions web-static/service-worker.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
const SHELL_CACHE = "reader-shell-v140";
const SHELL_CACHE = "reader-shell-v142";
const ITEMS_CACHE = "reader-items-v24";
const CORE_ASSETS = [
"/",
"/static/app.js?v=106",
"/static/app.js?v=108",
"/static/source-icons/hackernews.svg",
"/static/source-icons/github.svg",
"/static/source-icons/huggingface.svg",
Expand Down
Loading
Loading