# MeTube

An unofficial Chrome extension (Manifest V3) that remakes YouTube to be quieter and more yours: hide suggested videos, thumbnails, view and subscriber counts, comments and Shorts; skip the home page; force dark and theatre mode; keep statistics; or strip YouTube down to nothing but the video (Mega Minimal). **Use at your own risk: it works by guessing how YouTube's pages are built, and will need fixing whenever YouTube changes them.** Live in the toolbox at `tools/public/metube/` → `/metube`. 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/`, the same way as DustyTab and Claude Reframe. It is filed in the "Chrome Extensions" drawer on the home page.

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone changing things here. Read before touching code |
| `README.md` | This file: layout, how it works, how to test and release |
| `TASKS.md` | The live checklist and "Next up" |
| `DECISIONS.md` | What is decided and what waits on Austin |
| `PLAN.md` | Architecture and phases |
| `POSSIBILITIES.md` | Research: what an extension can do with YouTube, and the ranked shortlist of what to build next |
| `DATA-MODEL.md` | Exactly what is saved and the backup file format |
| `LEARNINGS.md` | Bugs found and lessons |
| `info.md` | The public write-up shown at `/metube/info` |
| `meta.json` | Toolbox metadata |
| `index.html` | The toolbox page: download, install and update steps, version history |

## Layout

```
extension/
  manifest.json      MV3; "key" pins the extension id; content script on https://www.youtube.com/* at document_start; Alt+Shift+M and Alt+Shift+Y
  shared.js          THE FEATURE REGISTRY: every setting, every selector, the CSS each produces, presets, backup files (classic script, adds MeTube)
  statslib.js        statistics: data shape, folding in counts, merging, summaries (classic script, adds MeTubeStats)
  content.js         the page script: style injection, page type, home redirect, theatre, dark, text sweeps, Mega Minimal page, counting
  background.js      the service worker: the only writer of the statistics, keyboard shortcuts
  ui.js              DOM helpers and the one function that draws any setting as a control (popup and settings page share it)
  popup.html/js/css  the toolbar popup: master switch, Mega Minimal, quick settings, presets, status, copy diagnostics, check for updates
  options.html/js/css  the settings page: every setting from the registry, search, presets, backup and restore, reset
  stats.html/js/css  the Statistics page: totals, a chart per day, time of day, pages, top channels and videos, export, clear
  icons/             icon.svg (source) and the PNGs Chrome uses
  HOW-TO-INSTALL-AND-UPDATE.txt   shipped inside the zip
releases/            releases.json (version history, newest first) and a zip per version
dev/                 make-icons.mjs, make-release.mjs
tests/unit/          node --test for shared.js and statslib.js
tests/e2e/           the real extension in Chromium against stand-in YouTube pages (standins.mjs)
```

## How it works

- **One registry.** `FEATURES` in `shared.js` lists every setting once: its type, default, label, help text, the CSS it produces (`css(value, settings)`), the selectors Diagnostics should probe, and whether it needs a text sweep. The settings page, the popup, import and export, presets and the page script all read that list, so adding a feature is one entry (see "Adding a feature" below).
- **CSS from settings.** `buildCss(settings)` joins the CSS of every feature that is switched on into one string; the page script puts it in a single `<style id="metube-style">`. Page-specific rules key off `html[data-mt-page="watch"]` (also `home`, `subscriptions`, `search`, `channel`, `shorts`, and so on), which the page script keeps up to date as the single-page app navigates. With every setting at its default the CSS is empty and YouTube is untouched.
- **No flash.** The page script runs at `document_start`, before anything is drawn, and reads a copy of the settings the page keeps in its own localStorage (`metube.cache`) so the first paint is already right. The authoritative copy is in `chrome.storage.local` and a change reaches every open tab at once.
- **Text sweeps.** View and subscriber counts, the "Most relevant" shelf and mostly-watched videos cannot be found by CSS. A `MutationObserver` looks at newly added nodes and marks matches with `data-mt-hid="views"` (and so on); the feature's CSS hides the marked elements. Views and subscribers look only at short metadata spans (`SEL.metaCandidates`), never titles; the words come from a list in the settings in the person's own language. Turning the setting off removes every mark.
- **Narrow layout.** YouTube drops to one column under about 1000 px (suggestions and comments move under the video). The selectors name the elements, not their position, so the same rules apply; the tests run both layouts. Theatre mode does nothing there because the button does not exist.
- **Home page.** At `document_start` on a bare `/`, `location.replace` goes to the chosen page before the home page draws; a click on the logo is intercepted the same way, and the app's own `yt-navigate-start` event is watched for navigations inside the page. A three-second loop guard and `?metube=off` (pauses MeTube in that tab until it closes; `?metube=on` brings it back) are the escape hatches.
- **Dark mode.** Sets YouTube's own `dark` attribute on `<html>`, adds a `--yt-spec-*` variable fallback, and puts the attribute back if YouTube removes it. "Match this computer" follows `prefers-color-scheme`.
- **Theatre mode.** Clicks YouTube's own size button (so the layout is exactly YouTube's), once per video, and never again for that video after a real click by the person. Skipped in full screen and in the narrow layout.
- **Mega Minimal.** On a watch page the masthead, sidebar, suggestions, comments and the rest are hidden, the player's containers are fixed to the whole window, and a `resize` event makes YouTube re-lay out the video. On every other YouTube page `body` is hidden and a `#metube-blank` overlay holds only the MeTube icon (anything still playing is paused). The toolbar popup and Alt+Shift+M always switch it off again.
- **Statistics.** The page script counts seconds (site open and visible; video playing, ads excluded), the hour, the video id, its title and channel, page kinds, Shorts, searches, redirects and theatre clicks, and sends a small delta every 15 seconds and when the page is hidden. The background worker folds each delta into `metube.stats` one at a time (the only writer), applies the retention, and caps the video list. Nothing is sent anywhere.
- **Diagnostics.** The popup's "Copy diagnostics" asks the page for a report: page kind, layout, which YouTube elements exist, and for each switched-on feature how many elements each selector found (and how many text marks). No page text. Paste it to whoever is fixing MeTube.

## Adding a feature

1. Add an entry to `FEATURES` in `extension/shared.js` (`id`, `group`, `type`, `def`, `label`, `hint`, and `css` and `probe` if it acts on the page). Selectors go in `SEL`, nowhere else.
2. If CSS cannot see what you want to hide, add a sweep kind in `sweepPlan` and `sweepNode` (text in short elements, a section heading, a progress bar) and have the feature's CSS hide `[data-mt-hid~="kind"]`.
3. Add it to a preset or to the popup's `QUICK` list if it deserves it. The settings page and backup files need nothing.
4. Add a stand-in element to `tests/e2e/standins.mjs`, a check to `tests/e2e/extension.mjs`, and unit tests if it has logic. Bump the version and release (see `CLAUDE.md`).

## Run and test

- During development load `tools/public/metube/extension/` unpacked at `chrome://extensions` (Developer mode → Load unpacked) and press reload after each change. Use the toolbar popup's "Copy diagnostics" on a real YouTube tab to see what matched.
- Unit: `node --test tools/public/metube/tests/unit/*.test.mjs`
- End to end: `node tools/public/metube/tests/e2e/extension.mjs --shots <dir>`. Launches Chromium with the real extension, answers every request to www.youtube.com with a stand-in page (watch, subscriptions, home, search and channel pages with YouTube's real element names, wide and narrow), and drives every feature, the popup, the settings page, the statistics page and backup and restore. Needs Playwright; no network. It proves the features work on pages built the way YouTube builds them, not on the live site: look at the screenshots, and try the extension on the real YouTube.

## Releasing

See "Before you push" in `CLAUDE.md`.

## Storage

`chrome.storage.local`: `metube.settings` and `metube.stats`. The page's own localStorage on youtube.com holds `metube.cache` (a copy of the settings, for the first paint) and `sessionStorage` holds a few per-tab flags. Not the toolbox's storage, so the toolbox Settings backup does not cover it; MeTube has its own backup. See `DATA-MODEL.md`.
