# DustyTab

A Chrome extension (Manifest V3) in the spirit of a one-click tab saver: press the toolbar button and every tab in the current window is saved to a list and closed, ready to reopen later. DustyTab adds what a plain tab dump lacks: Chrome tab groups carry over by name and color; every item shows its title, link, date added and age; items can be rated (0 to 3 stars, then +1 past 3) and noted; YouTube lengths are read before the tab closes so the list knows how many hours of video it holds; and anything opened or deleted goes to a Dustyard that records how long it sat. The purpose is behavioral: see the pile honestly and work towards watching less.

It lives in the toolbox at `tools/public/dustytab/` → `/dustytab`. That page (`index.html`) is the download and install page with the version history; the extension itself is in `extension/` and is downloaded as a zip from `releases/`.

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone changing things here: data safety, privacy, code rules, what to run before pushing |
| `README.md` | This file: layout, how it works, how to run, test and release |
| `TASKS.md` | The live checklist and "Next up". Update it when you finish or add work |
| `DECISIONS.md` | What is decided (including Austin's corrections) and the open questions |
| `PLAN.md` | Phases: what v1 covers and what comes next (video data, AI, habits) |
| `DATA-MODEL.md` | Storage keys, every stored shape, the backup format, text import format |
| `LEARNINGS.md` | Non-obvious bugs found here and how they were fixed |
| `TRANSCRIPTS.md` | Transcript research: the routes tried, how to test them, fallbacks to explore |
| `info.md` | The public write-up at `/dustytab/info` |
| `meta.json` | Toolbox metadata |
| `index.html` | The toolbox page: download, install and update steps, version history |

## Layout

```
index.html                  toolbox download page (reads releases/releases.json)
favicon.svg                 the mark, for the toolbox pages
extension/                  the unpacked extension, exactly what goes in the zip
  manifest.json             MV3; "key" pins the extension id; permissions; Alt+Shift+D / Alt+Shift+L
  background.js             service worker: toolbar button, right-click menus, save-and-close flow, messages
  dustytab.html             the list page (#list, #dustyard, #notes, #settings); also the options page
  icons/                    icon.svg (source) and the PNGs Chrome uses
  assets/dustytab.css       styles: dark by default, light when Windows is light or chosen in Settings
  assets/js/
    model.js                constants, defaults, normalizers, urlKey, formatting         (pure, tested)
    youtube.js              YouTube URL parsing, resume times, watch-page parsing          (pure, tested)
    ops.js                  every change to the data: save, rate, note, open/delete, groups, merge, import (pure, tested)
    views.js                search, sorted views, place counts, notes view                 (pure, tested)
    stats.js                backlog meter, dustyard stats, group totals                    (pure, tested)
    importers.js            backup JSON, OneTab-style text, CSV                            (pure, tested)
    dusty.js                Dusty flags, Auto dust rules, heads-up list                    (pure, tested)
    transcript.js           transcript and caption parsers                                 (pure, tested)
    transcript-fetch.js     the transcript routes (panel API, caption file, background tab), storage
    charts.js               hand-built SVG charts with tooltips and table views
    store.js                chrome.storage.local with a shared Web Lock (update())
    capture.js              runs inside a YouTube tab: player details before closing, and the in-tab transcript route (self-contained)
    videofill.js            looks up missing video details from the public watch page
    app.js                  page boot, routing, search, live updates, shared actions (open, remove, undo)
    list-view.js            List: meter, views, groups, rows, ratings, notes, locks, transcripts, drag and drop
    dusty-view.js           Dusty: dusty tabs, Keep, let go, and the Auto dust heads-up
    dust-view.js            Dustyard
    stats-view.js           Stats: weekly in and out, backlog and hours over time, ages, waits, sites, ratings
    dust-settings.js        the Dusty, Auto dust (draft and Apply) and Transcripts cards in Settings
    notes-view.js           Notes (remembered ratings and notes; greyed when not in the list)
    settings-view.js        Settings, backup and restore, import and export, shortcuts, about
    ui.js                   h(), icons, toast, favicon URL, download
    boot-check.js           plain script: shows "DustyTab couldn't start" with the fix instead of a blank page
  HOW-TO-INSTALL-AND-UPDATE.txt   the install and update steps, shipped inside the zip
releases/
  releases.json             version history: version, date, notes, file, size, sha256 (newest first)
  dustytab-<version>.zip    every released version, kept
  dustytab-latest.zip       copy of the newest
showcase/                   explainer-v1 (33 s) and logo-v1 (4 s loop), with MP4s and posters; lib/ has the player and drawing kit
dev/
  make-icons.mjs            draws the mark and renders the PNGs (Playwright)
  make-release.mjs          zips extension/ into releases/ and updates releases.json
tests/
  unit/*.test.mjs           node --test, for the pure modules
  e2e/extension.mjs         loads the real extension in Chromium and drives it end to end
```

## How it works

- **Saving.** `saveTabs()` picks the tabs (skipping pinned tabs, blank tabs and DustyTab's own page), reads each Chrome tab group's name and color, asks each loaded YouTube tab for its player data (`capture.js`, 1.5 second limit), writes everything with `update()`, and only then opens the list and closes the tabs. Each Chrome tab group becomes a DustyTab group (or joins one with the same name, per Settings); loose tabs go to a group named after the time ("Saved Oct 30, 2:05 PM"); single tabs and links go to a lasting "Inbox" group.
- **Storage.** One state object in `chrome.storage.local` (`dustytab.state`) with the `unlimitedStorage` permission, settings in `dustytab.settings`, and bookkeeping (last backup) in `dustytab.meta`. The service worker cannot use `localStorage`, which is why the data is in extension storage; the page's view preferences (current view, collapsed groups) are in the page's `localStorage` (`dustytab.ui`).
- **Dusty.** Off by default (Settings → Dusty). A tab is dusty once it has gone `afterDays` without being opened or kept (its clock starts at `addedAt`, or `keptAt` after Keep or Put back). "Flag" mode keeps it in the List with a dusty chip; "move" mode hides it from the List until it is kept. Either way it keeps its `groupId`, so the Dusty section can say where it came from and Keep puts it right back. Nothing is stored for this: it is computed from the dates each time.
- **Auto dust.** Off by default (Settings → Auto dust). Rules (age, dusty for N days, no stars, fewer than N stars, no note, loose or named group, video or page, long video, duplicate, seen before, site) combine with ALL or ANY, behind a "never younger than" floor and an optional whole-group mode. The service worker runs it hourly with `chrome.alarms`, at browser start, and when the list opens; matches go to the Dustyard as `dusted`. Locked tabs and groups are skipped. The Dusty section shows a heads-up list of tabs that will match within `warnDays`.
- **Capture mode.** Chrome's closed (saved) tab groups can't be read by extensions, so while Capture mode is on, the service worker saves every tab group that opens (once it has stopped growing, waiting briefly for titles) and closes its tabs. Austin opens the closed groups from Chrome's tab-groups menu one after another. State is in `chrome.storage.session` (`dustytab.capture`), so it is off after a restart; Open all sends `capture-pause` first.
- **Titles.** A tab whose title is just its link (common after bulk adds) is looked up like a missing length: from the watch page, with YouTube's oEmbed endpoint as the fallback.
- **Transcripts.** Experimental; see `TRANSCRIPTS.md`.
- **Speed with big lists (1.2.1).** The List draws about 250 rows at once and the rest as you scroll (`progressive()` in `list-view.js`); menus listing every group are built when opened; changes from storage are drawn once per frame and not while the tab is hidden; a change that only touches some rows redraws just those rows and the meter (`drawSignature()` and `tryPatch()` in `app.js`, `patchList()` in `list-view.js`); stars, +1 and locks are applied to the page first and saved right after (`ctx.mutateNow`); video lookups save once per batch of three.
- **Live updates.** The list page listens to `chrome.storage.onChanged`, so a save from the toolbar shows up immediately. It never redraws while you are typing a note or a group name; it catches up when the field loses focus.
- **The id.** The manifest's `key` fixes the id to `bnfpeedofipnpobbmdbefimclgjfioim`, so the extension's data belongs to that id no matter which folder it is loaded from. Only the public key is in the repo; the private key was not kept (it is only needed to publish a packed `.crx`, which this does not do).

## Install (Austin, Windows 10 and Chrome)

The steps are on the toolbox page `/dustytab` (sections Install, Update, If something goes wrong) and in `extension/HOW-TO-INSTALL-AND-UPDATE.txt`, which ships in the zip. Install: Extract All into Documents, so Chrome loads `Documents\DustyTab` (the folder with `manifest.json` directly inside), via Developer mode and Load unpacked. Update: download a backup, find the folder under the card's Details ("Loaded from"), delete everything inside it, paste in all the new version's files, press reload on the card. Never press Remove: that deletes the list. Copying only some new files over old ones (Austin's first attempt at 1.1.0) can mix versions and stop the page from starting; since 1.1.1 the page then says so and shows the fix.

During development you can load `tools/public/dustytab/extension/` from a clone directly, and press reload after pulling.

## Tests

- Unit: `node --test tools/public/dustytab/tests/unit/*.test.mjs`
- End to end: `node tools/public/dustytab/tests/e2e/extension.mjs --shots <dir>`. It launches Chromium with the extension, answers every web request with local fake pages (including a fake YouTube player, watch page and transcript endpoint), saves a window with a pinned tab, a Chrome tab group, a duplicate and a video, then drives the list page: ratings, +1, notes, open to the Dustyard, Notes memory and restore, rename, sorted views, search, drag and drop, Open all as a Chrome tab group, video lookup, backup download, Dusty in both modes, group locks, Auto dust through Settings, placeholder titles, Get transcript, Stats and the light theme (25 checks).

- Performance: `node tools/public/dustytab/tests/e2e/perf.mjs`. Builds a made-up list of 300 groups and 2,000 tabs and checks opening time, page size, a star click with everything drawn, and a toolbar save, against limits. 1.2.0 fails it; 1.2.1 passes (about 0.5 s to open, 9,000 elements, 40 ms for a star).
- Update path: `node tools/public/dustytab/tests/e2e/update.mjs`. Installs the real 1.0.0 zip, saves tabs, updates to the latest zip the documented way (empty the folder, paste, reload) and checks the list survived; then checks that a folder with an old script shows "DustyTab couldn't start", and one with the old page shows the mixed-versions notice. Needs `unzip`.

## Releasing

See "Before you push" in `CLAUDE.md`. In short: bump the version in `manifest.json` and `model.js`, add the notes to `releases/releases.json`, run `node tools/public/dustytab/dev/make-release.mjs`, bump `meta.json`, add to the `info.md` changelog, commit the new zip.
