# BB-004 rss-offline status — 2026-05-14

Current state for offline feed reading on `ballbox-first`.

## Outcome

Primary path now:

- `https://ballbox-first.emperor-ratio.ts.net/rss-offline/`

## Why the pivot happened

Previous cross-origin browser caching was not reliable enough for the main user goal:

- read recent content offline on phone
- avoid opening blogs one by one first

The weak point was cross-origin caching of external blog pages from mobile browsers.
That made offline hit rate inconsistent even after prefetch attempts.
The current builder saves fetched blog pages locally and produces a daily stitched PDF archive.

## What `rss-offline` does

- reads a curated feed list from local config
- fetches recent entries directly from feeds
- sorts entries by date descending
- downloads recent linked articles server-side
- stores a full local HTML copy of each fetched article page
- builds one stitched PDF per day with a dated filename
- serves a static web UI at `/rss-offline/`
- shows a simple archive of generated PDFs
- registers a service worker under `/rss-offline/`
- precaches generated local article pages for better offline behavior
- runs a rebuild cron once per day

## Current files and paths

Project source:

- `/home/sebas/work/projects/rss-offline/`
- `/home/sebas/work/projects/rss-offline/feed-sources.json`
- `/home/sebas/work/projects/rss-offline/build.py`

Generated site:

- `/var/www/rss-offline/`
- `/var/www/rss-offline/index.html`
- `/var/www/rss-offline/entries.json`
- `/var/www/rss-offline/sw.js`
- `/var/www/rss-offline/offline.html`
- `/var/www/rss-offline/article-*.html`

Logs:

- `/home/sebas/runtime/rss-offline-build.log`

## Current behavior limits

- offline reliability is now centered on the generated PDFs
- Safari/iPhone caching still may not be perfect for every generated local HTML page every time
- some sites will still depend on remote assets for full visual fidelity, but the saved local page is much closer to the original than the old text-only copy
- no category/tag UX yet; the current product is a simple PDF archive
- local copies are raw saved pages with a small local banner, used as build inputs and fallback browsing

## Operational notes

Cron currently rebuilds once per day at 06:00.
That means:

- a new dated PDF should appear automatically each day when there is fresh content
- local article copies refresh during the daily build
- service worker cache version only changes when the generated file content changes

## Product direction for now

Treat `rss-offline` as the current best offline reading path.
Keep investing in `rss-offline` only if a future need appears for:

- better feed management UX
- multi-user reader features
- categorization/search heavier than the current simple offline list