read-it-later/README.md

# Read it later

A new-tab page that shows everything you've saved to read later, as a
sortable grid or list. No account, no server — everything lives in your
browser's local extension storage.

## How to save something

- **Click the toolbar icon** — saves the page you're currently on.
- **Right-click a page** → "Save page for later"
- **Right-click a link** → "Save link for later" (doesn't need to be open)

A ✓ briefly appears on the icon to confirm the save.

## The shelf (new tab page)

- Toggle between **grid** (cards with thumbnails) and **list** (compact,
  bookshelf-spine style) — top right.
- **Sort** by newest, oldest, title, or site.
- **Search** filters by title, domain, or URL as you type.
- **Archive** tucks an item away without deleting it; "Show archived"
  reveals archived items again.
- **Delete** removes an item, with a 5-second **Undo**.

Thumbnails are captured automatically when you save the *current* page
(a screenshot of what's on screen). Links saved via right-click show a
favicon instead, since the browser hasn't loaded that page yet.

## Reminders and auto-delete

The gear icon opens a settings panel (also home to the light/dark/system
theme picker) with two optional timers, both off by default:

- **Remind me after** — items older than this get pinned to the top of the
  shelf and highlighted, so they don't get buried.
- **Delete unarchived items after** — silently removes items you never
  came back to. Archiving an item takes it out of consideration entirely.

The delete period must be longer than the reminder period — enforced both
in the settings panel (an inline error if you try to set it shorter) and as
a hard rule in the deletion logic itself, so you're always warned before
anything is removed. Auto-delete runs on an hourly background alarm (so it
still works even if you never open the new tab page), and again whenever
the shelf page is open; when the shelf page does the deleting, it shows a
courtesy toast with an **Undo**.

## Worth a second look

Above the shelf, a small strip proactively surfaces 2–3 old, forgotten,
unarchived items each time you open a new tab — on by default, toggleable
in the settings panel. Unlike a notification, it doesn't nag: the more
times an item gets shown without you opening/archiving/deleting it, the
less often it's picked again (backing off from every few days out to every
couple of months), so nothing gets shown forever, but nothing gets shown
*so* rarely that it's effectively forgotten again either. Archiving or
deleting an item removes it from the strip immediately with no replacement
until the next refresh — no whack-a-mole.

"Old enough to matter" uses the same period as the reminder setting above
when reminders are on, or a 14-day default when they're off. It's fine (and
expected) for the same item to show up both pinned/highlighted in the main
shelf *and* in this strip at once — they're not trying to be non-overlapping,
just two different nudges.

## Install — Chrome / Edge (unpacked)

1. Go to `chrome://extensions` (or `edge://extensions`).
2. Turn on **Developer mode** (top right).
3. Click **Load unpacked** and select this folder.
4. Open a new tab — you should see the Read it later page.

## Install — Firefox (temporary, for testing)

1. Go to `about:debugging#/runtime/this-firefox`.
2. Click **Load Temporary Add-on…**
3. Select the `manifest.json` file inside this folder.
4. Open a new tab. Firefox will ask permission to let the extension
   override the new tab page the first time — allow it.

> Temporary add-ons in Firefox are removed when you close the browser.
> For a permanent install, the extension needs to be signed by Mozilla
> (via [addons.mozilla.org](https://addons.mozilla.org)) or loaded in a
> [Developer Edition / Nightly build](https://www.mozilla.org/firefox/developer/)
> with `xpinstall.signatures.required` set to `false`.

## Syncing across devices

Read it later keeps full items (including screenshot thumbnails) in
`chrome.storage.local`, and also mirrors a lightweight copy of each item
(url, title, domain, favicon, dates, archived state, spotlight backoff
counters — no images) to
`chrome.storage.sync`, one entry per item so each stays well under the
8KB-per-item sync limit. On another device signed into the same browser
account, opening the shelf pulls those in automatically; thumbnails just
aren't part of what syncs, so items saved elsewhere show a favicon instead
until re-saved on that device. Archiving and deleting also sync. This is
all best-effort — offline, not signed in, or over the (~100KB / 512-item)
sync quota just means that device keeps working from local storage alone.

Note: `chrome.storage.sync` needs a stable extension ID to work, which
only applies to a permanently installed, signed add-on — not a Firefox
"temporary add-on" loaded via `about:debugging` (see install notes above),
which won't persist sync identity across restarts.

## Notes / things you might want to change

- Icons in `icons/` are placeholders — swap them for your own artwork
  any time; sizes 16/32/48/128 are already wired up in `manifest.json`.