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, URL, or tag 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.

## Tags

In grid view, click **+ tag** on any card to add one or more free-form
labels (comma-separated, e.g. `css, research`); click the **×** on a chip to
remove it. Tags are grid-only: list view stays the compact bookshelf row
it's meant to be.

Click a tag chip (on a card, or in the 🏷 toolbar button's dropdown, which
lists every tag currently in use) to instantly filter the shelf to it. This
just fills in the search box, so typing a tag name works too, and it
combines with everything search already matches (title, domain, URL).

## 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. This is
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 and 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, avoiding 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 on 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 on 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, tags, spotlight
backoff counters, never 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`.