fxcss 0.20.0__tar.gz → 0.22.0__tar.gz

{fxcss-0.20.0 → fxcss-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxcss
-Version: 0.20.0
+Version: 0.22.0
 Summary: Live-reload, inspect and screenshot-test Firefox userChrome.css themes
 Author: AdamXweb
 License: MIT
@@ -21,7 +21,7 @@ Provides-Extra: images
 Requires-Dist: pillow>=10.1; extra == "images"
 Dynamic: license-file
 
-## fxcss
+# fxcss
 
 <p align="center">
 <img width="120" src="https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/icon.png" alt="fxcss">
@@ -29,141 +29,64 @@ Dynamic: license-file
 <a href="https://pypi.org/project/fxcss/"><img src="https://img.shields.io/pypi/v/fxcss" alt="PyPI"></a>
 <img src="https://github.com/AdamXweb/fxcss/actions/workflows/ci.yml/badge.svg" alt="CI">
 <br>
-A testing toolkit for <code>userChrome.css</code> Firefox themes.<br>
-Edit your CSS and see it live, click any part of the UI to get its selector,
-and screenshot-test changes in CI.
+An all-in-one toolkit for <code>userChrome.css</code> Firefox themes.<br>
+Try and install themes, build them with live editing, and keep them tested
+with visual previews and Firefox compatibility checks.
 </p>
 
-**Three ways in:**
+## Getting started
 
-| You are… | Start with |
-| --- | --- |
-| **Building a theme** | `fxcss new my-theme` scaffolds one; `fxcss watch` shows edits live in ~50ms; `fxcss pick` names any element you click. |
-| **Trying someone's theme** | `fxcss try owner/repo` — test-drive it in a throwaway profile; close the window and nothing remains. Sure about it? `fxcss install owner/repo` puts it in your real profile, with a backup. |
-| **Maintaining a theme repo** | `fxcss init` — before/after screenshots on every pull request, on macOS, Windows and Linux. |
-
-## Your first ten minutes
-
-```bash
-pipx install "fxcss[images]"    # no pipx? brew install pipx / sudo apt install pipx
-
-# See it work on a real theme before touching your own:
-fxcss try AdamXweb/WhiteSurFirefoxThemeMacOS
-
-# No theme yet? Start from a small working one:
-fxcss new my-theme
-
-# Point it at your theme (the folder containing chrome/) and edit live:
-cd my-theme && fxcss watch
-
-# Can't name the element you want to style? Click it:
-fxcss pick
-
-# Happy? Give the repo CI previews:
-fxcss init && git add .github && git commit -m "ci: theme previews"
-```
-
-Every one of these runs in a throwaway profile. Looking for themes to try?
-Browse [firefoxcss-store.github.io](https://firefoxcss-store.github.io/) or
-[r/FirefoxCSS](https://www.reddit.com/r/FirefoxCSS/) — anything with a
-`userChrome.css` on GitHub works with `fxcss try owner/repo`.
-
-## Description
-
-Working on a Firefox theme normally means: edit CSS, restart Firefox, squint,
-repeat — and guessing at element names, because the browser's own UI isn't in
-any page inspector you're used to.
-
-fxcss removes both problems. It installs your theme into a throwaway profile,
-drives Firefox over **Marionette** (Firefox's built-in automation protocol), and
-gives you a live-reload loop, an element picker, and a screenshot differ.
-
-Your real Firefox profile is never touched — except by the one command whose
-job that is: `fxcss install`, which backs up what it replaces and keeps a
-manifest so `fxcss uninstall` can put everything back.
-
-![Three saved edits in fxcss watch, each recolouring the chrome](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch-loop.gif)
-
-<p align="center"><sub>Three saves in <code>fxcss watch</code> — the window updates in ~50ms.
-Every image in this README was generated by fxcss itself.</sub></p>
-
-## Requirements
-
-- Python 3.9+
-- Firefox (any recent release; the toolkit finds it automatically on macOS,
-  Windows and Linux, or set `FIREFOX_BIN`)
-- `pillow`, only for `catalogue`, `compare` and `tweaks` — every other
-  command is standard library. Added later with `pipx inject fxcss pillow`.
-
-## Installation
-
-fxcss is [on PyPI](https://pypi.org/project/fxcss/). Install it with **pipx**,
-which gives it its own environment and puts `fxcss` on your PATH:
+You need **Python 3.9+** and an installed **Firefox** on macOS, Windows or
+Linux. Install fxcss with its image tools, then try a theme in a disposable
+profile:
 
 ```bash
 pipx install "fxcss[images]"
+fxcss try AdamXweb/WhiteSurFirefoxThemeMacOS
 ```
 
-No pipx yet? `brew install pipx` (macOS), `sudo apt install pipx` (Debian and
-Ubuntu), or `python3 -m pip install --user pipx` elsewhere.
-
-> **Why not plain pip?** On current Homebrew, Debian and Ubuntu Pythons,
-> `python3 -m pip install` refuses with `error: externally-managed-environment`
-> — that's [PEP 668](https://peps.python.org/pep-0668/) protecting your system
-> Python, not fxcss being broken. pipx is the intended answer for installing an
-> application. pip still works fine *inside a virtual environment*:
->
-> ```bash
-> python3 -m venv ~/.venvs/fxcss && ~/.venvs/fxcss/bin/pip install "fxcss[images]"
-> ```
-
-For CI, or anywhere a surprise upgrade would be unwelcome, pin the release —
-the [releases page](https://github.com/AdamXweb/fxcss/releases) has the latest.
-CI runners' Pythons are not externally managed, so plain pip is fine there:
-
-```bash
-pip install "fxcss[images]==0.20.0"
-```
-
-Either gives you an `fxcss` command. To hack on it, clone and install editable:
-
-```bash
-git clone https://github.com/AdamXweb/fxcss.git
-cd fxcss && python3 -m pip install -e ".[images]"
-```
+Close the preview window when you are done; your everyday Firefox profile is
+unchanged. See [installation options](#installation) if you do not have pipx.
 
-And if you would rather install nothing at all, the repo runs as-is:
+Choose what you want to do next:
 
-```bash
-python3 -m fxcss <command>
-```
+| I want to… | Next step |
+| --- | --- |
+| Use a theme in my everyday browser | [Install it](#fxcss-install), then check updates, change options or roll back. |
+| Create or edit a theme | [Start a theme](#fxcss-new), see edits live and inspect Firefox's interface. |
+| Maintain a theme on GitHub | [Generate workflows](#fxcss-init) for PR previews and scheduled Firefox checks. |
 
-Run commands from your theme's root (the folder containing `chrome/`), or point
-at it with `--theme /path/to/theme`.
+For local development and testing, run commands from the theme's root (the
+folder containing `chrome/`), or pass `--theme /path/to/theme`. Use
+`fxcss <command> --help` for its options.
 
-## Commands
+## Explore the toolkit
 
-| Command | What it's for |
+| Section | What you can do |
 | --- | --- |
-| `new` | Start a theme from a small, working scaffold |
-| [`try`](#fxcss-try) | Download a theme from GitHub and test-drive it |
-| [`install`](#fxcss-install) | Install a theme into your real Firefox profile |
-| [`uninstall`](#fxcss-install) | Remove it again, restoring what was there |
-| [`upgrade`](#fxcss-upgrade) | Fetch a newer version of the theme you installed |
-| [`rollback`](#fxcss-upgrade) | Put the previous version back |
-| [`adopt`](#fxcss-adopt) | Take over a theme installed some other way |
-| [`profiles`](#fxcss-profiles) | List every Firefox profile and what is themed in it |
-| [`watch`](#fxcss-watch) | Edit CSS and see it live, no restart |
-| [`pick`](#fxcss-pick) | Click any part of the UI to get its CSS selector |
-| [`inspect`](#fxcss-inspect) | Look up a selector you already have |
-| [`init`](#fxcss-init) | Add PR previews and CI checks to your theme repo |
-| [`tweaks`](#fxcss-tweaks) | Screenshot every install option into a committable doc |
-| [`audit`](#fxcss-audit) | Find every selector that no longer matches, and suggest fixes |
-| [`changelog`](#fxcss-changelog) | Diff two Firefox builds to see what chrome changed |
-| [`snapshot`](#fxcss-changelog) | Record a Firefox's chrome names, to diff against later |
-| [`catalogue`](#fxcss-catalogue) | Build a directory of themeable UI parts |
-| [`shot`](#fxcss-shot) / [`compare`](#fxcss-compare) | Screenshot and diff two versions |
-| [`doctor`](#fxcss-doctor) | Report what your Firefox supports |
+| [Using and managing themes](#using-and-managing-themes) | Preview, install, adopt, update, roll back and remove themes; see what is installed in each profile. |
+| [Building and inspecting themes](#building-and-inspecting-themes) | Start a theme, reload CSS live and find the selectors and rules behind the UI. |
+| [Testing appearance](#testing-appearance) | Run saved project checks, capture browser states and review visual differences. |
+| [Tracking Firefox compatibility](#tracking-firefox-compatibility) | Save structural snapshots, compare Firefox builds and audit theme breakage. |
+| [GitHub Actions workflows](#github-actions-workflows) | Automate PR previews, Firefox checks and screenshot publishing. |
+| [Documenting and showcasing themes](#documenting-and-showcasing-themes) | Explain install options with images and generate a visual UI reference. |
+| [Troubleshooting and configuration](#troubleshooting-and-configuration) | Diagnose setup problems, choose installation options and understand capture limits. |
+| [Commands](#commands) | Jump directly to any command. |
+
+Previewing, editing and browser testing use disposable profiles. The theme
+management commands `install`, `adopt`, `upgrade`, `rollback` and `uninstall`
+work on a selected real profile; `profiles` only reads it.
+
+## Using and managing themes
+
+Start with a preview, then install into the profile you choose. fxcss records
+what it installs, checks for local edits before upgrades and keeps backups
+when replacing an existing theme. Already have a manually installed theme?
+Use `adopt` to bring it under management.
+
+Looking for a theme? Browse the [Firefox CSS Store](https://firefoxcss-store.github.io/)
+or [r/FirefoxCSS](https://www.reddit.com/r/FirefoxCSS/), then pass its GitHub
+repository to `fxcss try`.
 
 ### fxcss try
 
@@ -209,11 +132,10 @@ download behind so you can start editing it with `watch`.
 
 #### It does not run the theme's install script
 
-That is deliberate, and worth being plain about: fetching a shell script from a
-URL and executing it to preview a stylesheet is a bad trade. Those scripts are,
-in substance, `cp -r chrome/ <profile>/` plus flipping a pref — which fxcss
-already does. So it finds the script, tells you it exists, parses the options its
-README documents, and then installs the files itself.
+fxcss installs the theme's files and supported preferences itself. It reports
+any installer it finds and reads the options documented in the theme's README.
+A theme that requires additional setup outside those files and preferences may
+still need manual steps.
 
 What is left is the theme's own content: CSS, SVG, and occasionally a `.js` file.
 Firefox does not execute a `.js` file sitting in a profile's chrome folder; that
@@ -232,7 +154,6 @@ fxcss install owner/theme                      # into your default profile
 fxcss install owner/theme --with compact-tabs  # optional sheets, permanently
 fxcss install ~/src/my-theme                   # a local checkout works too
 fxcss install --list-profiles                  # see what it found first
-fxcss uninstall                                # put everything back
 ```
 
 **Put a theme into the Firefox profile you actually use** — the cross-platform
@@ -345,10 +266,10 @@ wins, as before, with a one-line note that `--commit` exists.
 
 The install is what a theme's install script does, done carefully:
 
-- your existing `chrome/` is moved to a timestamped `chrome.backup-*` sibling
-  first — nothing is overwritten in place;
-- the theme's `chrome/` is copied in, along with any `--with` optional sheets
-  (placed where the theme's own `@import`s expect them);
+- the complete replacement is prepared before your existing `chrome/` moves
+  to a timestamped `chrome.backup-*` sibling; a failed swap restores it;
+- any `--with` optional sheets go where the theme's own `@import`s expect
+  them, or load after the base theme through an import-only wrapper;
 - `toolkit.legacyUserProfileCustomizations.stylesheets` is enabled in
   `user.js` — inside a clearly marked block, so it can be removed cleanly —
   together with any `configuration/user.js` the theme ships;
@@ -356,105 +277,8 @@ The install is what a theme's install script does, done carefully:
   sha256, and where the theme came from — which repo, which ref, and whether
   that ref was a release or a branch.
 
-`fxcss uninstall` reads that manifest, removes exactly the files it lists,
-restores the backup, and strips the `user.js` block. Files it cannot prove
-fxcss wrote are never deleted — they are kept, or moved aside, never removed.
-Restart Firefox after either command; it reads `userChrome.css` at startup.
-
-> **Changed in 0.13:** before 0.13, `fxcss install` was an alias for `try`
-> and touched nothing real. The throwaway test-drive lives on, unchanged, as
-> `fxcss try`.
-
-### fxcss upgrade
-
-```bash
-fxcss upgrade                        # take the newest version of what you have
-fxcss upgrade --check                # report only; exit code says what it found
-fxcss upgrade --audit                # check the new version against your Firefox first
-fxcss upgrade --compare              # see it before deciding: installed vs new, rendered
-fxcss upgrade --ref v2.1.0           # somewhere specific
-fxcss rollback                       # …and back again
-```
-
-`upgrade` re-installs the theme the profile already has, at whatever is newest
-*of the kind it tracks*: an install that took a release moves to the newest
-tag, one that followed a branch moves to that branch's current commit, and one
-pinned with `--ref` does not move at all unless you say so.
-
-It stops rather than surprise you, in three places:
-
-- **Files you edited yourself.** Every install records a sha256 per file, so
-  an upgrade knows which ones you have since changed and refuses to write over
-  them until `--force`. Files you *added* are never touched either way.
-- **Options that vanished.** If you installed `--with theme-nord` and the new
-  version renamed or dropped that sheet, the `@import` would simply stop
-  resolving and the option would turn itself off. `upgrade` names the loss and
-  makes you choose instead.
-- **Selectors the new version needs and your Firefox lacks** — with `--audit`,
-  which runs the same check as [`fxcss audit`](#fxcss-audit) against the
-  fetched copy *before* anything is installed.
-
-`--compare` renders what is installed and what the upgrade would install —
-the profile's own `chrome/`, local edits and carried-over sheets included, not
-a re-fetch of what the manifest says — and diffs them before the confirmation
-prompt, printing where the before/after images landed. It completes the three
-questions an upgrade can answer about a theme with no API: do the selectors
-still exist (`--audit`), has the user edited anything (always checked), and
-what actually changes on screen (`--compare`). Needs Pillow and a local
-Firefox, like `shot`.
-
-`--check` changes nothing and answers with its exit code, for cron, launchd or
-CI: **0** up to date, **1** an upgrade is available, **2** it cannot be told
-(no install here, an unreachable repo, or a manifest too old to say what it
-tracked). fxcss deliberately ships no scheduler of its own — this is the piece
-you point yours at.
-
-```console
-$ fxcss upgrade
-
-  profile: default-release  (~/Library/…/8f2h1kqp.default-release)
-  installed: AdamXweb/WhiteSurFirefoxThemeMacOS @ v1.6.3
-  upstream:  v2.0.0  — 2026-08-16
-
-  fetching v2.0.0 …
-  keeping optional sheets: theme-nord
-
-  Upgrade to v2.0.0? [Y/n]
-
-  upgraded to v2.0.0
-  the previous version is kept as chrome.backup-20260817014202
-
-  Restart Firefox to see it. `fxcss rollback` puts the previous version back.
-```
-
-#### Going back
-
-Every install and every upgrade leaves a `chrome.backup-*` behind, and the
-manifest travels inside `chrome/` — so each backup can say what it holds:
-
-```console
-$ fxcss rollback --list
-
-  Backups, newest first:
-
-    chrome.backup-20260817014202
-      AdamXweb/WhiteSurFirefoxThemeMacOS@v1.6.3
-    chrome.backup-20260817014143  (the original)
-      your own chrome/, from before fxcss
-```
-
-`fxcss rollback` restores the most recent, or `--to <name>` any of them.
-What was installed becomes a backup in its turn, so a rollback can itself be
-rolled back, and `user.js` follows: each version records the prefs it asked
-for, and rolling back to the original — the one backup with no manifest in it,
-because it is *your* chrome folder from before any of this — takes the fxcss
-pref block out with it.
-
-That original is the reason upgrades chain rather than stack blindly. After
-five upgrades the newest backup holds *the theme*, not your files, so the
-manifest carries the original's name forward and `fxcss uninstall` still
-restores what you had before you ever ran fxcss. `--keep N` (default 3) prunes
-older backups; the original is never one of them.
+Restart Firefox after installation; it reads `userChrome.css` at startup.
+See [uninstall](#fxcss-uninstall) to remove a theme later.
 
 ### fxcss adopt
 
@@ -568,68 +392,180 @@ The same reservation covers local edits: installs from before 0.16 recorded no
 file hashes, so `fxcss profiles` reports them as *not checked for edits*
 rather than as unmodified. Reinstalling records them.
 
-### fxcss completions
+### fxcss upgrade
 
 ```bash
-eval "$(fxcss completions bash)"     # add to ~/.bashrc
-eval "$(fxcss completions zsh)"      # add to ~/.zshrc
-fxcss completions fish | source      # add to config.fish
+fxcss upgrade                        # take the newest version of what you have
+fxcss upgrade --check                # report only; exit code says what it found
+fxcss upgrade --audit                # check the new version against your Firefox first
+fxcss upgrade --compare              # see it before deciding: installed vs new, rendered
+fxcss upgrade --ref v2.1.0           # somewhere specific
+fxcss rollback                       # …and back again
 ```
 
-Tab-completes subcommands, the flags each one takes, `--firefox` channel names
-— and, reading the theme in front of it, the names of its optional stylesheets:
+`upgrade` updates the installed theme, not Firefox itself. It re-installs the theme the profile already has, at whatever is newest
+*of the kind it tracks*: an install that took a release moves to the newest
+tag, one that followed a branch moves to that branch's current commit, and one
+pinned with `--ref` does not move at all unless you say so.
 
-```console
-$ fxcss install ~/src/whitesur --with theme-mat<TAB>
-theme-material-ocean  theme-material-palenight
-```
+It stops rather than surprise you, in three places:
 
-Comma-separated lists complete element by element, and values already chosen
-are not offered twice. The candidates are read off the real argument parser, so
-a command or flag becomes completable the moment it exists rather than when
-someone remembers to update a shell script. Completion never touches the
-network: sheet names for a remote `owner/repo` are not known locally, and a Tab
-that pauses to talk to GitHub would be worse than no completion at all — the
-picker during `install` covers that case instead.
+- **Files you edited yourself.** Every install records a sha256 per file, so
+  an upgrade knows which ones you have since changed and refuses to write over
+  them until `--force`. Files you *added* are never touched either way.
+- **Options that vanished.** If you installed `--with theme-nord` and the new
+  version renamed or dropped that sheet, the `@import` would simply stop
+  resolving and the option would turn itself off. `upgrade` names the loss and
+  makes you choose instead.
+- **Selectors the new version needs and your Firefox lacks** — with `--audit`,
+  which runs the same check as [`fxcss audit`](#fxcss-audit) against the
+  fetched copy *before* anything is installed.
 
-### fxcss watch
+`--compare` renders what is installed and what the upgrade would install —
+the profile's own `chrome/`, local edits and carried-over sheets included, not
+a re-fetch of what the manifest says — and diffs them before the confirmation
+prompt, printing where the before/after images landed. It completes the three
+questions an upgrade can answer about a theme with no API: do the selectors
+still exist (`--audit`), has the user edited anything (always checked), and
+what actually changes on screen (`--compare`). Needs Pillow and a local
+Firefox, like `shot`.
 
-```bash
-fxcss watch
-```
+`--check` changes nothing and answers with its exit code, for cron, launchd or
+CI: **0** up to date, **1** an upgrade is available, **2** it cannot be told
+(no install here, an unreachable repo, or a manifest too old to say what it
+tracked). fxcss deliberately ships no scheduler of its own — this is the piece
+you point yours at.
 
-Opens Firefox with your theme applied and watches `chrome/` and `custom/`. Save
-a file in your editor and the running window updates in about 50ms.
+```console
+$ fxcss upgrade
 
-The window is yours to drive — open menus, resize it, type in the address bar,
-right-click things. Nothing is scripted.
+  profile: default-release  (~/Library/…/8f2h1kqp.default-release)
+  installed: AdamXweb/WhiteSurFirefoxThemeMacOS @ v1.6.3
+  upstream:  v2.0.0  — 2026-08-16
 
-Reloads reach every chrome document, not just the browser window: new windows,
-and separate documents like the window-modal dialog (the quit prompt), pick up
-your edits too — the same reach an installed `userChrome.css` has.
+  fetching v2.0.0 …
+  keeping optional sheets: theme-nord
 
-![The example theme rendered in light and dark](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch.png)
+  Upgrade to v2.0.0? [Y/n]
 
-| flag | effect |
-| --- | --- |
-| `--dark` | start in dark mode, for testing `prefers-color-scheme` rules |
-| `--native-menus=false` | make right-click menus themeable (see [Context menus](#context-menus-are-native-on-macos)) |
-| `--shot out.png` | write a screenshot after every reload |
-| `--no-devtools` | don't enable the Browser Toolbox |
+  upgraded to v2.0.0
+  the previous version is kept as chrome.backup-20260817014202
 
-### fxcss pick
+  Restart Firefox to see it. `fxcss rollback` puts the previous version back.
+```
+
+### fxcss rollback
+
+Restore the newest backup, or choose one by name:
 
 ```bash
-fxcss pick
+fxcss rollback
+fxcss rollback --list
+fxcss rollback --to chrome.backup-20260817014202
 ```
 
-**The answer to "what is this thing called?"** Move the mouse over the browser
-window and the element under the cursor is outlined, with its selector shown in
-a label:
+Installs and upgrades that replace an existing `chrome/` keep it as a
+`chrome.backup-*`. Managed backups include the installation record, so the
+list can show what each one holds:
 
-![The picker outlining the address bar, labelled #urlbar](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/pick.png)
+```console
+$ fxcss rollback --list
 
-Click it and your terminal prints everything you need:
+  Backups, newest first:
+
+    chrome.backup-20260817014202
+      AdamXweb/WhiteSurFirefoxThemeMacOS@v1.6.3
+    chrome.backup-20260817014143  (the original)
+      your own chrome/, from before fxcss
+```
+
+`fxcss rollback` restores the most recent, or `--to <name>` any of them.
+What was installed becomes a backup in its turn, so a rollback can itself be
+rolled back, and `user.js` follows: each version records the prefs it asked
+for, and rolling back to the original — the one backup with no manifest in it,
+because it is *your* chrome folder from before any of this — takes the fxcss
+pref block out with it.
+
+That original is the reason upgrades chain rather than stack blindly. After
+five upgrades the newest backup holds *the theme*, not your files, so the
+manifest carries the original's name forward and `fxcss uninstall` still
+restores what you had before you ever ran fxcss. `--keep N` (default 3) prunes
+older backups; the original is never one of them.
+
+### fxcss uninstall
+
+```bash
+fxcss uninstall
+fxcss uninstall --profile default-release
+```
+
+Removes the managed theme and its `user.js` preference block. Recorded files
+are removed only when their hashes still match; added, edited, unreadable or
+unverifiable files are kept. If nothing needs to be retained, the original
+`chrome/` backup is restored. Otherwise the backup stays alongside the retained
+files so it cannot overwrite your work.
+
+If the profile originally had no `chrome/`, uninstalling after an upgrade
+returns it to that state when no files need to be kept. Restart Firefox to see
+the result.
+
+## Building and inspecting themes
+
+Work on Firefox's tabs, toolbars and other browser UI with a live preview.
+Use the picker to find an element, then inspect the rules behind it. All of
+these browser sessions use disposable profiles.
+
+### fxcss new
+
+```bash
+fxcss new my-theme
+cd my-theme
+fxcss watch
+```
+
+Creates a small working theme you can edit immediately. Save changes to
+`chrome/userChrome.css` while `watch` is running to see them in Firefox. Stop
+with Ctrl-C when you want to run another command. The starter is also used by
+fxcss's own browser tests; an existing non-empty directory is left alone.
+
+### fxcss watch
+
+```bash
+fxcss watch
+```
+
+Opens Firefox with your theme applied and watches `chrome/` and `custom/`. Save
+a CSS file in your editor and the running window reloads it automatically.
+
+The window is yours to drive — open menus, resize it, type in the address bar,
+right-click things. Nothing is scripted.
+
+Reloads reach every chrome document, not just the browser window: new windows,
+and separate documents like the window-modal dialog (the quit prompt), pick up
+your edits too — the same reach an installed `userChrome.css` has.
+
+![Three saved edits in fxcss watch, each recolouring the chrome](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch-loop.gif)
+
+| flag | effect |
+| --- | --- |
+| `--dark` | start in dark mode, for testing `prefers-color-scheme` rules |
+| `--native-menus=false` | make right-click menus themeable (see [Context menus](#context-menus-are-native-on-macos)) |
+| `--shot out.png` | write a screenshot after every reload |
+| `--no-devtools` | don't enable the Browser Toolbox |
+
+### fxcss pick
+
+```bash
+fxcss pick
+```
+
+**The answer to "what is this thing called?"** Move the mouse over the browser
+window and the element under the cursor is outlined, with its selector shown in
+a label:
+
+![The picker outlining the address bar, labelled #urlbar](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/pick.png)
+
+Click it and your terminal prints everything you need:
 
 ```
   toolbarbutton  →  #back-button
@@ -672,83 +608,299 @@ styled `#urlbar-background` by id, which many older themes still do. The id was
 replaced by a class, so the rule silently did nothing and the address bar
 rendered unstyled. One command found it; the fix was `.urlbar-background`.
 
-### fxcss init
+### Inspecting the UI with devtools
+
+Firefox's normal inspector only sees page content. The **Browser Toolbox** is
+the version that can inspect the browser's own UI, and it's off by default
+behind four prefs. fxcss turns them on in its throwaway profile, so in `watch`
+and `pick` you can just press:
+
+- **macOS** — `Cmd+Opt+Shift+I`
+- **Windows / Linux** — `Ctrl+Alt+Shift+I`
+
+You get a full inspector over the browser chrome: hover to highlight, read
+computed styles, and live-edit rules to try things before committing them to
+your CSS. `fxcss pick` is the fast path for "what is this called"; the Browser
+Toolbox is the thorough one for "why is this rule not winning".
+
+## Testing appearance
+
+Use [`fxcss check`](#fxcss-check) for an audit, screenshots and a combined
+report. Use `shot` and `compare` separately when you want to control each step.
+
+Capture the same browser states before and after a theme change, then inspect
+what moved or changed colour:
 
 ```bash
-fxcss init                       # before/after previews on every PR
-fxcss init --watch --showcase    # plus the weekly Firefox audit + capture
-                                 # canary, and release screenshots
-fxcss init --previews            # plus README screenshots that keep themselves
-                                 # current: every view and variant, re-rendered
-                                 # on each change and pushed to a previews branch
+fxcss shot --out shots/before --variants all
+# Edit your theme, then capture it again.
+fxcss shot --out shots/after --variants all
+fxcss compare --base shots/before --head shots/after --out diff/
 ```
 
-**Turn any theme repository into one with CI.** Run it from your theme's root
-and it writes the preview workflows into `.github/workflows/`, ready to commit:
-every pull request then gets a comment showing the browser chrome before and
-after the change, with changed pixels highlighted — rendered on macOS, Windows
-and Linux, across twenty views and every variant stylesheet you ship.
-
-The generation is the point, not a convenience: the fxcss version is pinned to
-the one doing the generating, and the publish allowlist is enumerated from
-*your* theme's variant folder — the two things that had to be hand-edited, and
-the second one silently drops views when forgotten. Existing files are never
-overwritten without `--force`, and the output tells you the things that
-otherwise surprise people (the comment starts after the workflows reach your
-default branch; first-time contributors need one approval click).
-
-Each render captures the base branch and the pull request and diffs them. The
-base half is cached: its captures are deterministic — that is the contract
-fxcss's own CI asserts — so after a pull request's first push, later pushes
-render only the change. The key names everything that could alter a pixel
-(base commit, runner image, Firefox version, fxcss version, the workflow file
-itself), and a miss on any of them re-renders rather than falling back to a
-near match. GitHub scopes caches to the branch that made them, so this helps
-the second push onward, not the first: a pull request that takes six pushes
-to land renders the base once, not six times.
-
-If you'd like people to know:
+Keep the Firefox build, operating system and capture settings the same when
+reviewing a CSS change. For a Firefox update, keep the theme unchanged and
+capture each browser build with `--firefox`.
 
-[![theme previews by fxcss](https://img.shields.io/badge/theme%20previews-fxcss-ff7139)](https://github.com/AdamXweb/fxcss)
+### fxcss check
 
-### fxcss tweaks
+```bash
+fxcss check
+```
+
+Runs a compatibility audit and captures the theme in a disposable Firefox
+profile. It writes a Markdown report, a machine-readable `summary.json`, logs
+and screenshots into a fresh run folder under `.fxcss/checks/`. Without a
+configuration file, it uses installed Stable, captures all optional
+stylesheets and fails on actionable selector findings. Visual comparison is
+enabled when you supply a baseline.
+
+Save settings in `.fxcss.json` at the theme's root to use the same checks
+locally and in CI:
+
+```json
+{
+  "firefox": ["stable"],
+  "variants": "all",
+  "baseline": ".fxcss/baseline",
+  "out": ".fxcss/checks",
+  "strict": true,
+  "strict_vars": false,
+  "max_changed_percent": 0.1
+}
+```
+
+Create a baseline explicitly, then compare later runs against it:
 
 ```bash
-fxcss tweaks
-fxcss tweaks --combo compact-tabs+tabs-swapclose
+fxcss check --update-baseline
+# Edit the theme, then review the combined report.
+fxcss check
 ```
 
-**Document your install options with screenshots.** Themes describe their
-optional stylesheets in prose — accordions of flags, `install.sh -c -n -s`
-incantations — and a user assembles their preferred setup in their head. This
-renders the answer instead: the base theme, every optional stylesheet, and any
-combination you bless with `--combo`, each with a labelled **before/after crop
-of the region it actually changes** and how much of the chrome it touches.
+`--update-baseline` accepts new captures only when every configured browser's
+audit and capture succeed under your settings. It skips comparison with the
+old baseline during that run. Existing baselines are preserved on a failed
+check; normal runs never replace them. Review the new captures when accepting
+a baseline. Existing directories not created by `check` are not replaced.
+Every standard view and selected option must be accounted for in
+`capture-coverage.json`: captured, explicitly unsupported, or failed. A missing
+view or failed browser state prevents baseline updates, even on the first run.
+Baselines made before coverage reports were added must be captured again.
+
+Add installed channels such as `"beta"` or `"nightly"` to the browser list;
+each gets a separate baseline. Missing browsers are reported as errors while
+the remaining browsers are still checked. Keep baselines for different
+operating systems separate. `--firefox beta` overrides the list for one run.
+
+| Setting or option | Behavior |
+| --- | --- |
+| `strict` / `--strict` | Fail on actionable selector findings; `--no-strict` makes them advisory. |
+| `strict_vars` / `--strict-vars` | Also fail on dead custom properties; deliberate `fxcss-keep` overrides remain exempt. |
+| `max_changed_percent` / `--max-changed-percent` | Fail when any view exceeds this percentage, or a new view has no baseline. Set the saved value to `null` for advisory pixel differences. Missing baseline views always need attention. |
+| `variants` / `--variants` | Capture `all`, named stylesheets or combinations such as `compact+dark`. Set the saved value to `null` to capture the base theme only. |
+| `toolbar` / `--toolbar` | Apply a toolbar arrangement to the toolbar capture. |
+| `baseline`, `out` | Paths relative to the theme root; absolute paths also work. `baseline: null` runs audits and captures without visual comparison. |
+| `--config FILE` | Read a different JSON settings file. Command-line options override saved values. |
+
+Exit codes are **0** for completed checks within the configured policy,
+**1** for findings, and **2** for configuration, browser, capture or comparison
+errors. A configured baseline that is missing is an error, not an unchanged
+result. Invalid settings fail before Firefox is started.
+
+For a custom GitHub workflow with Firefox and a display already available,
+run `fxcss check` and upload `.fxcss/checks/` even when the check fails. Keep the
+baseline available in the checkout or download it before checking; update it
+explicitly when accepting a theme change. Use `--firefox "$FIREFOX_BIN"` when a
+runner installs Firefox outside the usual locations. Add generated check reports to your
+theme repository's `.gitignore` if you do not intend to commit them.
 
-A `--combo` is also judged against its own parts: if `a+b` renders
-pixel-identically to `b` alone, then `a` did nothing in that combination, and
-TWEAKS.md says so rather than presenting the pair as a real option. That is
-the check the static conflict analysis in `install` cannot make — two sheets
-can fight over the same pixels through entirely different rules — and the
-rendered images settle it as a fact rather than a judgement.
+### fxcss shot
 
-The crop is built from the changed pixels, so it needs no per-option
-configuration and cannot drift when Firefox moves something. It centres on the
-busiest *cluster* of changes rather than the bounding box of all of them,
-which is what makes the common cases readable: swapping the tab close button
-changes every tab, and a crop of all of them is the tab strip again, shrunk
-until nothing is visible. One tab, magnified, shows the option. Panels scale up
-as well as down for the same reason — a correctly cropped 16px button is still
-a 16px button.
+```bash
+fxcss shot --out shots/before
+```
 
-The output is a folder of PNGs plus `TWEAKS.md`, written to be committed:
-relative links, and a `<details>` accordion per option so a long list stays
-scannable on GitHub. If your README documents installer flags, they are parsed
-and included as a table.
+Captures the standard set of views as PNGs: browser window, focused address bar,
+find bar and the window-modal dialog in light and dark, then playing and muted
+audio tab indicators, container tabs, an overflowing tab strip, a private window,
+compact density, the sidebar, right-to-left chrome, and customize mode.
 
-A tweak that changes nothing is reported as exactly that — *"changes nothing on
-current Firefox, possibly stale"*. Optional sheets rot at least as fast as
-selectors do, and nobody notices because nobody has them enabled.
+Audio views set Firefox's playing and muted tab attributes directly. They test
+the appearance of those indicators without requiring a sound device or playing
+a tone. CI also verifies that CSS targeting each state changes its screenshot.
+
+The dialog view is the quit-confirmation prompt (commonDialog), opened for
+real. It is its own chrome document, painted from different rules than the
+window around it, which is why themes break it without noticing — a dark theme
+whose dialog body renders white shows up here and nowhere else.
+
+The captures land **flat** in `--out`, one file per view (`shots/before/light-01-window.png`);
+`--url` captures go to `<out>/live/`. This is the directory to publish from if
+you want plain screenshots — `fxcss compare` writes a different shape, below.
+
+```bash
+fxcss shot --out shots --variants all
+```
+
+`--variants` additionally captures one view per optional stylesheet the theme
+ships (`custom/`, `optional/`, `variants/`…), each loaded on its own and removed
+again — so `tabs-swapclose` or `compact-tabs` are checked by CI without a
+separate install. Name specific ones (`--variants a,b`) or take them all.
+
+#### Browser states it captures
+
+`fxcss shot` renders a standard set of views, so a change is judged against the
+states people actually use rather than one idle window: light and dark, the
+focused address bar, find bar, modal dialog, audio and muted tabs, container
+tabs, an overflowing tab strip, a private window, compact density,
+right-to-left chrome, Customize
+mode — and three that a theme is most likely to have never been tested in:
+
+- **Sidebar — bookmarks and history.** Both panels, with their trees expanded,
+  because a fresh profile shows them collapsed and a collapsed panel has almost
+  nothing in it to style.
+- **Vertical tabs.** Firefox 133+ does not restyle the tab strip here, it
+  *moves* it: `#tabbrowser-tabs` leaves `#TabsToolbar` for `#vertical-tabs`, so
+  every `#TabsToolbar > …` rule a theme owns silently stops matching while its
+  unscoped `.tabbrowser-tab` rules keep applying horizontal geometry to a
+  vertical column. Older builds without vertical tabs skip the view.
+- **Customised toolbar.** The nav bar with widgets moved into it — by default
+  including the new tab button, which is the rearrangement plenty of theme
+  READMEs ask users to make by hand and which nothing could test until now.
+
+Set your own arrangement with `--toolbar`, on `shot`, `watch` or `try`:
+
+```bash
+fxcss watch --toolbar "new-tab-button>nav-bar, -downloads-button"
+fxcss shot  --toolbar "home-button>nav-bar@0" --out shots/
+```
+
+`widget>area` moves a widget (optionally `@position`), `-widget` removes one.
+Areas are `nav-bar`, `TabsToolbar`, `PersonalToolbar`, `vertical-tabs`,
+`unified-extensions-area`. A widget id Firefox does not recognise is reported
+rather than ignored — Firefox itself accepts any string and then quietly
+renders nothing.
+
+Some states depend on the Firefox build; unavailable states are reported and
+skipped rather than treated as captured.
+
+### fxcss compare
+
+```bash
+fxcss compare --base shots/before --head shots/after --out diff/
+```
+
+Diffs two sets and writes one stacked **before / after / changed-pixels** image
+per view that differs. Views that render identically are reported rather than
+pictured, so you only look at what actually changed.
+
+`--out` therefore holds comparison images for changed views only, plus a
+`summary.json` and a `full/` directory carrying a normalised copy of *every*
+head capture, changed or not. So `<out>/full/` is what a preview comment shows
+when nothing differs — and `shot`'s own `--out` (flat, no `full/`) is what to
+read when you just want the screenshots.
+
+![Before, after and changed-pixels panels for a one-line accent colour change](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/compare.png)
+
+<p align="center"><sub>One changed value — the accent colour behind the active tab. The bottom panel
+highlights the 0.09% of pixels that moved.</sub></p>
+
+This is what makes it useful in CI: render your theme at the base commit and at
+a pull request, and the diff shows a reviewer exactly what the change does. See
+[Using it in CI](#using-it-in-ci).
+
+A successful comparison reports differences; changed pixels alone do not make
+`compare` fail. Review the images to decide whether a change is intended. If
+your project needs a pass/fail threshold, use `fxcss check` or a custom check
+using `summary.json`. Added and missing views are reported as changes. Missing,
+empty or unreadable screenshot inputs return an error. Reusing an output
+directory clears the previous report's generated images so stale comparisons
+do not survive into a new result.
+
+## Tracking Firefox compatibility
+
+Firefox changes can leave a theme partly unstyled even when its CSS still
+loads. These tools help you inspect the browser you have and prepare for the
+builds your users will get next.
+
+| Tool | What it tells you |
+| --- | --- |
+| `snapshot` | Which browser UI IDs and classes were observed in a Firefox build; saves a JSON baseline. |
+| `changelog` | Which names changed between that baseline and another build, and which removals the theme uses. |
+| `audit` | Which selectors and custom properties need attention in the selected Firefox, with suggested fixes. |
+
+A snapshot records structure; `shot` records appearance. Neither is a profile
+backup. Use audits and visual comparisons together: a selector can still
+exist while its layout looks wrong.
+
+### Testing against Nightly, Developer Edition, ESR — or a fork
+
+Every command that opens a browser takes a channel name as well as a path:
+
+```bash
+fxcss watch --firefox nightly
+fxcss audit --firefox dev          # what will break before it ships
+fxcss shot  --firefox esr --out shots/esr
+```
+
+Recognised names: `stable`, `beta`, `dev`, `nightly`, `esr`, and the Gecko
+forks theme users actually run — `librewolf`, `floorp`, `waterfox`, `zen`.
+They resolve against what is installed in the usual places; a build kept
+somewhere unusual can be added with `FXCSS_FIREFOX_ROOTS=/path/to/dir`.
+
+With **several builds installed and no `--firefox` given**, interactive
+commands show a picker — press Enter for stable, or a number for another
+build. CI and scripts are never prompted: non-interactive runs keep the old
+behaviour exactly.
+
+These names select browsers already installed on your machine. The local
+commands do not install or update Firefox.
+
+### fxcss snapshot
+
+```bash
+fxcss snapshot --firefox stable --out .fxcss/firefox-baseline.json
+```
+
+Saves the UI IDs and classes observed in the collected browser states, along
+with the Firefox version, build ID and operating system. Keep this JSON file
+with your theme to compare later, without keeping the old browser installed:
+
+```bash
+fxcss changelog --baseline .fxcss/firefox-baseline.json --firefox beta
+```
+
+The snapshot covers the states fxcss collected; it is not a full DOM archive
+or a guarantee that every Firefox UI element was observed.
+
+### fxcss changelog
+
+```bash
+fxcss changelog --against /path/to/old/firefox --firefox /path/to/new/firefox
+```
+
+**What actually changed between two Firefox releases.** Compares the chrome IDs
+and classes collected from both builds and tells you which of the removals your
+theme depends on:
+
+```
+  Firefox 140.13.0 → 153.0.3
+    52 chrome names gone, 221 new
+
+  2 of them are used by this theme:
+    #urlbar-background          chrome/parts/headerbar-urlbar.css:52
+    #urlbar-go-button           chrome/parts/buttons-fixes.css:202
+```
+
+Point it at an ESR build and current release to see what a year of Firefox did
+to your theme, or at a Beta to find out what is about to break before your users
+do. `--show-all` lists every name that changed, not just the ones you use.
+
+`--against` supplies the older baseline; `--firefox` supplies the newer target.
+Use `--baseline` with a [saved snapshot](#fxcss-snapshot) when the old build is
+no longer installed. Run `fxcss audit --firefox beta` to investigate findings
+against a selected channel.
 
 ### fxcss audit
 
@@ -774,19 +926,18 @@ to change — with the real line from your file and the replacement applied:
     - #urlbar-background {
     + .urlbar-background {
 
-  SIMILAR  #appMenu-fullscreen-button  →  #appMenu-fullscreen-button2
+  SIMILAR  #appMenu-fullscreen-button  →  #appMenu-fullscreen-button2  (a guess, not applied)
            no exact match; closest live name is #appMenu-fullscreen-button2
 
     chrome/parts/icons.css:198
-    - #appMenu-fullscreen-button {
-    + #appMenu-fullscreen-button2 {
+      #appMenu-fullscreen-button {
 ```
 
-That output is real — it is what this finds in a long-running theme. The
+These examples come from findings in a long-running theme. The
 `…-button2` pattern is how Firefox has been versioning app-menu controls, and it
 breaks menu styling silently.
 
-Findings come in three kinds:
+Findings are grouped as follows:
 
 | | meaning |
 | --- | --- |
@@ -804,7 +955,10 @@ Firefox versions, so they keep working for releases that came out after this
 tool did.
 
 `--patch` writes a unified diff of the **RENAMED** findings only — the ones where
-the replacement is certain. Review it, then `git apply`. SIMILAR findings are
+the replacement is certain. If a replacement would repeat another selector in
+the same rule, that occurrence is left out of the patch and the report asks
+you to remove the redundant selector manually. Other safe occurrences are
+still patched. Review the diff, then `git apply`. SIMILAR findings are
 deliberately excluded: they are usually right, but "usually" is not good enough
 to rewrite your CSS unattended.
 
@@ -816,96 +970,205 @@ parsing, keeps resolving, and paints nothing — `--in-content-page-background`
 did exactly that, and a theme's dialog body silently rendered white under its
 dark palettes for months.
 
-When fxcss can find this Firefox's `omni.ja` archives (it can, for every
-packaged build), the audit reads the shipped chrome directly and separates
-three cases a live probe cannot tell apart:
+When fxcss can find this Firefox's `omni.ja` archives (it can, for every
+packaged build), the audit reads the shipped chrome directly and separates
+three cases a live probe cannot tell apart:
+
+- **set and read by Firefox** — a working override, counted quietly;
+- **SET, NEVER READ** — this Firefox still declares the name but no rule or
+  script consumes it any more, so the override changes nothing;
+- **DEFINED ONLY** — the shipped chrome neither declares nor reads the name,
+  with the closest consumed name suggested when there is one
+  (`--panel-background` → `--panel-background-color`).
+
+Reading the shipped sources also covers documents the live audit cannot open —
+dialogs, DevTools, in-content pages — and replaces the second, unthemed
+Firefox launch the probe needed.
+
+A name you keep deliberately — for an ESR that still reads it, say — gets an
+inline pragma rather than a CI flag nobody finds later:
+
+```css
+--in-content-page-background: var(--gnome-menu-background) !important; /* fxcss-keep: ESR 140 reads it */
+```
+
+`--strict-vars` turns dead and stale overrides into a non-zero exit for CI;
+`fxcss-keep` lines are exempt.
+
+#### Unused and unreachable code
+
+`audit` also reports housekeeping, in its own section, separate from breakage:
+
+- **Stylesheets nothing imports.** Files under `chrome/` unreachable by
+  following `@import` from `userChrome.css`. Sheets in a `custom/` or
+  `optional/` folder are excluded — being opt-in is the point of those.
+- **Custom properties used but never set**, where an unthemed Firefox does not
+  provide them either. These are usually typos: the `var()` silently falls back.
+- **Custom properties set but read nowhere.** Reported cautiously — setting
+  `--arrowpanel-background` exists precisely so Firefox's own rules pick it up,
+  so this section excludes every name an unthemed Firefox resolves.
+
+The audit reads Firefox's shipped sources where available. Otherwise it uses
+a second, unthemed browser to distinguish theme-defined properties from those
+Firefox provides.
+
+Pass `--no-unused` to skip the section.
+
+Use `--strict` to fail on actionable selector findings and `--strict-vars`
+for dead custom properties. Unreachable stylesheet reports remain advisory;
+`/* fxcss-keep */` marks deliberate property overrides.
+
+## GitHub Actions workflows
+
+Give reviewers images of a proposed change, check upcoming Firefox builds and
+keep published screenshots current. Generate the workflows from your theme's
+root, then commit them to its GitHub repository.
+
+### fxcss init
+
+```bash
+fxcss init                               # PR previews
+fxcss init --watch                       # also check Firefox weekly
+fxcss init --showcase --previews          # also publish screenshots
+fxcss init --watch --showcase --previews  # generate all six workflow files
+```
+
+`init` writes to `.github/workflows/`. Existing files are preserved unless you
+pass `--force`; review regenerated files before committing, especially if you
+have customised them. Generation pins the installed fxcss version. The preview publisher validates
+variant filenames and PNG headers, including options added by later PRs.
+Updating fxcss locally does not update workflows already in a repository.
+
+| Feature | Enable with | When it runs | What readers see |
+| --- | --- | --- | --- |
+| PR previews | `init` | Relevant pull request changes; macOS, Windows and Linux. | A comment showing before/after views and highlighted differences, including optional stylesheets. |
+| Firefox watch | `init --watch` | Weekly on Mondays, or manually; Release, Beta and Nightly on macOS. | Fix PRs or issues for actionable selector findings, plus a separate issue if screenshot capture fails. |
+| README previews | `init --previews` | Matching theme changes on `main`/`master`, or manually; macOS. | Refreshed standard and variant screenshots plus cropped option comparisons on the `previews` branch. |
+| Release showcase | `init --showcase` | A release is published, or manually; macOS. | Light/dark screenshots against live websites on the `showcase` branch. |
+
+The workflows download Firefox on their runners. Generated preview triggers
+cover `chrome/`, `configuration/`, `custom/`, `optional/`, `options/`, `extras/`
+and `variants/`. Review the filters if you keep theme assets elsewhere.
+Re-run generation and review the changes to update the pinned fxcss version
+or adopt improvements to the workflow templates. New variants are included automatically.
+
+### Pull request previews
+
+The default setup writes three cooperating workflows:
+
+1. **Render:** capture the base and proposed theme revisions on each operating
+   system, compare them and upload the images. Matching base captures are
+   cached for later pushes to the same PR.
+2. **Publish:** validate the artifacts, publish images to `ci-previews`, and
+   create or update the preview comment. Unchanged views remain available as
+   full screenshots.
+3. **Clean up:** remove a PR's published images when it closes.
+
+Preview comments start once the workflows are on the default branch.
+First-time contributor runs may need GitHub's approval step. Rendering PR
+content uses read-only permissions; the separate publisher can post comments
+but does not execute PR code.
+
+The preview shows what changed, leaving the reviewer to decide whether it is
+correct. It does not reject a PR simply because the screenshots differ.
 
-- **set and read by Firefox** — a working override, counted quietly;
-- **SET, NEVER READ** — this Firefox still declares the name but no rule or
-  script consumes it any more, so the override changes nothing;
-- **DEFINED ONLY** — the shipped chrome neither declares nor reads the name,
-  with the closest consumed name suggested when there is one
-  (`--panel-background` → `--panel-background-color`).
+### Watching Firefox for breakage
 
-Reading the shipped sources also covers documents the live audit cannot open —
-dialogs, DevTools, in-content pages — and replaces the second, unthemed
-Firefox launch the probe needed.
+The weekly watch checks two things independently:
 
-A name you keep deliberately — for an ESR that still reads it, say — gets an
-inline pragma rather than a CI flag nobody finds later:
+- **Theme selectors:** run an audit against each channel. If exact ID/class
+  replacements can be patched, open a PR with those fixes and the full report.
+  Otherwise, actionable findings open or update an issue for that channel.
+- **Screenshot capture:** run the standard capture to detect Firefox changes
+  that stop previews from rendering at all. Failures get a separate issue.
 
-```css
---in-content-page-background: var(--gnome-menu-background) !important; /* fxcss-keep: ESR 140 reads it */
-```
+Issues close when the associated check is healthy again. Proposed fixes still
+need review and merging. The default audit uses `--strict --no-unused`, so
+custom-property failure checks are not enabled in this workflow.
 
-`--strict-vars` turns dead and stale overrides into a non-zero exit for CI;
-`fxcss-keep` lines are exempt.
+The generated watch does not save structural snapshots or compare screenshots
+across Firefox releases. To add that history, compose `snapshot`, `changelog`,
+`shot` and `compare` in a custom workflow.
 
-### fxcss changelog
+### Keeping README and release images current
 
-```bash
-fxcss changelog --firefox /path/to/old/firefox --against /path/to/new/firefox
-```
+Embed the generated image links in your README once; subsequent workflow runs
+refresh the images behind those links. The workflows do not edit the README's
+text.
 
-**What actually changed between two Firefox releases.** Collects every chrome id
-and class from both builds, diffs them, and tells you which of the removals your
-theme depends on:
+- **README previews** publish the current standard views, individual optional
+  stylesheet captures and cropped option comparisons to `previews`, replacing
+  the previous images.
+- **Release showcase** publishes live-website captures under
+  `showcase/screenshots/`, with URLs printed in the workflow summary.
 
-```
-  Firefox 140.13.0 → 153.0.3
-    52 chrome names gone, 221 new
+### Using it in CI
 
-  2 of them are used by this theme:
-    #urlbar-background          chrome/parts/headerbar-urlbar.css:52
-    #urlbar-go-button           chrome/parts/buttons-fixes.css:202
+For a custom workflow, the core capture-and-compare steps are:
+
+```yaml
+- run: pip install "fxcss[images]==0.22.0"
+- run: fxcss shot --theme base --out shots/base
+- run: fxcss shot --theme head --out shots/head
+- run: fxcss compare --base shots/base --head shots/head --out out/ --platform ${{ runner.os }}
 ```
 
-Point it at an ESR build and current release to see what a year of Firefox did
-to your theme, or at a Beta to find out what is about to break before your users
-do. `--show-all` lists every name that changed, not just the ones you use.
+These steps assume the two theme revisions are checked out, Firefox is
+installed and a display is available. Browser chrome requires a rendered
+window: macOS and Windows runners have a display; Linux needs Xvfb. Firefox's
+headless mode does not render the browser chrome.
 
-You do not need to keep an old browser around. `fxcss snapshot --out
-baseline.json` records what a Firefox has; commit that file and compare later
-with `--baseline`:
+Start with `fxcss init` for the complete setup. The
+[workflow examples](examples/README.md) explain the generated files. If your
+project needs a visual pass/fail policy, read `compare`'s `summary.json` and
+apply its chosen threshold.
 
-```bash
-fxcss snapshot --out .fxcss/firefox-140.json     # once
-fxcss changelog --baseline .fxcss/firefox-140.json
-```
+[![theme previews by fxcss](https://img.shields.io/badge/theme%20previews-fxcss-ff7139)](https://github.com/AdamXweb/fxcss)
 
-#### Watching Firefox for breakage
+## Documenting and showcasing themes
 
-Firefox ships every few weeks, and a theme does not break loudly when it
-renames something. A scheduled job can audit each channel and tell you before
-your users find out — Beta and Nightly give weeks of warning.
+Help users see what they are choosing. Generate images of install options,
+explore the UI parts a theme can style, or capture the theme against websites
+for a README or release announcement.
 
-`examples/firefox-watch.yml` is a working workflow that does this: it downloads
-release, beta and nightly, audits the theme against each, opens a **pull
-request** when the fixes are ones `--patch` is certain about, opens an issue
-when they are not, and closes the issue once the channel is clean again.
+### fxcss tweaks
 
-#### Unused and unreachable code
+```bash
+fxcss tweaks
+fxcss tweaks --combo compact-tabs+tabs-swapclose
+```
 
-`audit` also reports housekeeping, in its own section, separate from breakage:
+**Document your install options with screenshots.** Themes describe their
+optional stylesheets in prose — accordions of flags, `install.sh -c -n -s`
+incantations — and a user assembles their preferred setup in their head. This
+renders the answer instead: the base theme, every optional stylesheet, and any
+combination you bless with `--combo`, each with a labelled **before/after crop
+of the region it actually changes** and how much of the chrome it touches.
 
-- **Stylesheets nothing imports.** Files under `chrome/` unreachable by
-  following `@import` from `userChrome.css`. Sheets in a `custom/` or
-  `optional/` folder are excluded — being opt-in is the point of those.
-- **Custom properties used but never set**, where an unthemed Firefox does not
-  provide them either. These are usually typos: the `var()` silently falls back.
-- **Custom properties set but read nowhere.** Reported cautiously — setting
-  `--arrowpanel-background` exists precisely so Firefox's own rules pick it up,
-  so this section excludes every name an unthemed Firefox resolves.
+A `--combo` is also judged against its own parts: if `a+b` renders
+pixel-identically to `b` alone, then `a` did nothing in that combination, and
+TWEAKS.md says so rather than presenting the pair as a real option. That is
+the check the static conflict analysis in `install` cannot make — two sheets
+can fight over the same pixels through entirely different rules — and the
+rendered images settle it as a fact rather than a judgement.
 
-That last check is why `audit` briefly starts a second, unthemed browser: asked
-of the themed one, every name resolves, because the theme set it.
+The crop is built from the changed pixels, so it needs no per-option
+configuration and cannot drift when Firefox moves something. It centres on the
+busiest *cluster* of changes rather than the bounding box of all of them,
+which is what makes the common cases readable: swapping the tab close button
+changes every tab, and a crop of all of them is the tab strip again, shrunk
+until nothing is visible. One tab, magnified, shows the option. Panels scale up
+as well as down for the same reason — a correctly cropped 16px button is still
+a 16px button.
 
-Pass `--no-unused` to skip the section.
+The output is a folder of PNGs plus `TWEAKS.md`, written to be committed:
+relative links, and a `<details>` accordion per option so a long list stays
+scannable on GitHub. If your README documents installer flags, they are parsed
+and included as a table.
 
-**Should it gate CI?** Report it, don't fail on it. `--strict` covers selectors
-that no longer match, which is real breakage. Unused code is tidiness, and a
-tidiness check that blocks merges gets disabled. The example CI here runs
-`audit --strict` and lets the unused section be advisory.
+A tweak that changes nothing in the captured state is reported as exactly that — *"changes nothing on
+current Firefox, possibly stale"*. Optional sheets rot at least as fast as
+selectors do, and nobody notices because nobody has them enabled.
 
 ### fxcss catalogue
 
@@ -927,36 +1190,7 @@ missing rather than quietly documented.
 Add `--self-contained` to also get a single `catalogue.html` with the images
 inlined, for attaching to an issue.
 
-### fxcss shot
-
-```bash
-fxcss shot --out shots/before
-```
-
-Captures the standard set of views as PNGs: browser window, focused address bar,
-find bar and the window-modal dialog in light and dark, then a tab playing
-audio, the same tab muted, container tabs, an overflowing tab strip, a private
-window, compact density, the sidebar, right-to-left chrome, and customize mode.
-
-The dialog view is the quit-confirmation prompt (commonDialog), opened for
-real. It is its own chrome document, painted from different rules than the
-window around it, which is why themes break it without noticing — a dark theme
-whose dialog body renders white shows up here and nowhere else.
-
-The captures land **flat** in `--out`, one file per view (`shots/before/light-01-window.png`);
-`--url` captures go to `<out>/live/`. This is the directory to publish from if
-you want plain screenshots — `fxcss compare` writes a different shape, below.
-
-```bash
-fxcss shot --out shots --variants all
-```
-
-`--variants` additionally captures one view per optional stylesheet the theme
-ships (`custom/`, `optional/`, `variants/`…), each loaded on its own and removed
-again — so `tabs-swapclose` or `compact-tabs` are checked by CI without a
-separate install. Name specific ones (`--variants a,b`) or take them all.
-
-#### Against real websites
+### Against real websites
 
 ```bash
 fxcss shot --out shots --url https://github.com/AdamXweb/WhiteSurFirefoxThemeMacOS
@@ -972,33 +1206,14 @@ content, title or favicon between two runs, and a theme pull request should not
 be blamed for it. `compare` only looks at PNGs at the top level, so they are
 excluded by construction rather than by a rule someone has to remember.
 
-`examples/showcase.yml` automates it — regenerate on every release, publish to a
-`showcase` branch, and link stable raw URLs from your README.
-
-### fxcss compare
-
-```bash
-fxcss compare --base shots/before --head shots/after --out diff/
-```
-
-Diffs two sets and writes one stacked **before / after / changed-pixels** image
-per view that differs. Views that render identically are reported rather than
-pictured, so you only look at what actually changed.
-
-`--out` therefore holds comparison images for changed views only, plus a
-`summary.json` and a `full/` directory carrying a normalised copy of *every*
-head capture, changed or not. So `<out>/full/` is what a preview comment shows
-when nothing differs — and `shot`'s own `--out` (flat, no `full/`) is what to
-read when you just want the screenshots.
-
-![Before, after and changed-pixels panels for a one-line accent colour change](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/compare.png)
+Generate the [release showcase workflow](#keeping-readme-and-release-images-current)
+with `fxcss init --showcase` to refresh these images when a release is published.
 
-<p align="center"><sub>One changed value — the accent colour behind the active tab. The bottom panel
-highlights the 0.09% of pixels that moved.</sub></p>
+## Troubleshooting and configuration
 
-This is what makes it useful in CI: render your theme at the base commit and at
-a pull request, and the diff shows a reviewer exactly what the change does. See
-[Using it in CI](#using-it-in-ci).
+Start with `doctor` when a browser or theme does not behave as expected. This
+section also covers installation alternatives, shell completion and the limits
+of browser chrome capture.
 
 ### fxcss doctor
 
@@ -1011,104 +1226,92 @@ context menus are themeable on your platform, how many stylesheets your theme
 has — and **every Gecko build installed on the machine**, with versions. Start
 here if something isn't behaving.
 
-#### Browser states it captures
+### Requirements
 
-`fxcss shot` renders 18 views, so a change is judged against the states people
-actually use rather than one idle window: light and dark, the focused address
-bar, the find bar, audio and muted tabs, container tabs, an overflowing tab
-strip, a private window, compact density, right-to-left chrome, Customize
-mode — and three that a theme is most likely to have never been tested in:
+- Python 3.9+
+- Firefox (any recent release; the toolkit finds it automatically on macOS,
+  Windows and Linux, or set `FIREFOX_BIN`)
+- Pillow for `catalogue`, `compare`, `check`, `tweaks` and `upgrade --compare`.
+  The `fxcss[images]` extra includes it; add it later with
+  `pipx inject fxcss pillow`. Other commands use the Python standard library.
 
-- **Sidebar — bookmarks and history.** Both panels, with their trees expanded,
-  because a fresh profile shows them collapsed and a collapsed panel has almost
-  nothing in it to style.
-- **Vertical tabs.** Firefox 133+ does not restyle the tab strip here, it
-  *moves* it: `#tabbrowser-tabs` leaves `#TabsToolbar` for `#vertical-tabs`, so
-  every `#TabsToolbar > …` rule a theme owns silently stops matching while its
-  unscoped `.tabbrowser-tab` rules keep applying horizontal geometry to a
-  vertical column. Older builds without vertical tabs skip the view.
-- **Customised toolbar.** The nav bar with widgets moved into it — by default
-  including the new tab button, which is the rearrangement plenty of theme
-  READMEs ask users to make by hand and which nothing could test until now.
+### Installation
 
-Set your own arrangement with `--toolbar`, on `shot`, `watch` or `try`:
+fxcss is [on PyPI](https://pypi.org/project/fxcss/). Install it with **pipx**,
+which gives it its own environment and puts `fxcss` on your PATH:
 
 ```bash
-fxcss watch --toolbar "new-tab-button>nav-bar, -downloads-button"
-fxcss shot  --toolbar "home-button>nav-bar@0" --out shots/
+pipx install "fxcss[images]"
 ```
 
-`widget>area` moves a widget (optionally `@position`), `-widget` removes one.
-Areas are `nav-bar`, `TabsToolbar`, `PersonalToolbar`, `vertical-tabs`,
-`unified-extensions-area`. A widget id Firefox does not recognise is reported
-rather than ignored — Firefox itself accepts any string and then quietly
-renders nothing.
+No pipx yet? `brew install pipx` (macOS), `sudo apt install pipx` (Debian and
+Ubuntu), or `python3 -m pip install --user pipx` elsewhere.
 
-#### Testing against Nightly, Developer Edition, ESR — or a fork
+> **Why not plain pip?** On current Homebrew, Debian and Ubuntu Pythons,
+> `python3 -m pip install` refuses with `error: externally-managed-environment`
+> — that's [PEP 668](https://peps.python.org/pep-0668/) protecting your system
+> Python, not fxcss being broken. pipx is the intended answer for installing an
+> application. pip still works fine *inside a virtual environment*:
+>
+> ```bash
+> python3 -m venv ~/.venvs/fxcss && ~/.venvs/fxcss/bin/pip install "fxcss[images]"
+> ```
 
-Every command that opens a browser takes a channel name as well as a path:
+For CI, or anywhere a surprise upgrade would be unwelcome, pin the release —
+the [releases page](https://github.com/AdamXweb/fxcss/releases) has the latest.
+CI runners' Pythons are not externally managed, so plain pip is fine there:
 
 ```bash
-fxcss watch --firefox nightly
-fxcss audit --firefox dev          # what will break before it ships
-fxcss shot  --firefox esr --out shots/esr
+pip install "fxcss[images]==0.22.0"
 ```
 
-Recognised names: `stable`, `beta`, `dev`, `nightly`, `esr`, and the Gecko
-forks theme users actually run — `librewolf`, `floorp`, `waterfox`, `zen`.
-They resolve against what is installed in the usual places; a build kept
-somewhere unusual can be added with `FXCSS_FIREFOX_ROOTS=/path/to/dir`.
-
-With **several builds installed and no `--firefox` given**, interactive
-commands show a picker — press Enter for stable, or a number for another
-build. CI and scripts are never prompted: non-interactive runs keep the old
-behaviour exactly.
+Upgrade an existing pipx installation with `pipx upgrade fxcss`.
 
-## Inspecting the UI with devtools
+### Upgrading to 0.22
 
-Firefox's normal inspector only sees page content. The **Browser Toolbox** is
-the version that can inspect the browser's own UI, and it's off by default
-behind four prefs. fxcss turns them on in its throwaway profile, so in `watch`
-and `pick` you can just press:
+The new `check` command requires baselines with a complete capture coverage
+report. To start using it with an older collection of screenshots, choose a
+fresh baseline directory, then review the new images:
 
-- **macOS** — `Cmd+Opt+Shift+I`
-- **Windows / Linux** — `Ctrl+Alt+Shift+I`
+```bash
+fxcss check --baseline .fxcss/baseline-0.22 --update-baseline
+```
 
-You get a full inspector over the browser chrome: hover to highlight, read
-computed styles, and live-edit rules to try things before committing them to
-your CSS. `fxcss pick` is the fast path for "what is this called"; the Browser
-Toolbox is the thorough one for "why is this rule not winning".
+Save that path as `baseline` in `.fxcss.json` for subsequent checks. Existing
+directories not managed by `check` are preserved. Missing views and failed
+browser states prevent a baseline update. You can still use `compare` directly
+with older screenshots.
 
-## Using it in CI
+Theme repositories keep their generated workflows and pinned fxcss version
+until you update those files. To pick up the capture fixes and workflow
+improvements, [regenerate the workflows](#github-actions-workflows) with
+your existing options and review the changes before committing them. The
+generator skips existing files unless you pass `--force`; preserve any custom
+workflow edits when reviewing the regenerated files.
 
-`shot` and `compare` are designed to run on a hosted runner. The shape is:
-check out the base revision and the pull request revision, render both, compare,
-and publish the result.
+### fxcss completions
 
-```yaml
-- run: pip install "fxcss[images]==0.20.0"   # pin: your CI, your upgrades
-- run: fxcss shot --theme base --out shots/base
-- run: fxcss shot --theme head --out shots/head
-- run: fxcss compare --base shots/base --head shots/head --out out/ --platform ${{ runner.os }}
+```bash
+eval "$(fxcss completions bash)"     # add to ~/.bashrc
+eval "$(fxcss completions zsh)"      # add to ~/.zshrc
+fxcss completions fish | source      # add to config.fish
 ```
 
-Two things to know before wiring this up:
-
-- **Don't use headless mode.** Firefox headless renders no browser chrome at
-  all, so a headless screenshot is an empty window. Runners need a real display;
-  macOS and Windows runners have one, Linux needs `xvfb-run`.
-- **Pull requests from forks get a read-only token.** If you want the result
-  posted as a comment, build the images in the `pull_request` job (no write
-  permissions, no secrets) and publish from a separate `workflow_run` job.
+Tab-completes subcommands, the flags each one takes, `--firefox` channel names
+— and, reading the theme in front of it, the names of its optional stylesheets:
 
-Don't copy workflow files by hand — `fxcss init` generates them for your theme,
-allowlist and version pin included. [`examples/README.md`](examples/README.md)
-explains the shape of what it writes, most importantly why the preview is two
-workflows (fork PRs get a read-only token, so the half that runs their code
-cannot be the half that posts the comment). This repo's own CI runs the full
-pipeline against the packaged starter theme on macOS, Windows and Linux.
+```console
+$ fxcss install ~/src/whitesur --with theme-mat<TAB>
+theme-material-ocean  theme-material-palenight
+```
 
-## Things worth knowing
+Comma-separated lists complete element by element, and values already chosen
+are not offered twice. The candidates are read off the real argument parser, so
+a command or flag becomes completable the moment it exists rather than when
+someone remembers to update a shell script. Completion never touches the
+network: sheet names for a remote `owner/repo` are not known locally, and a Tab
+that pauses to talk to GitHub would be worse than no completion at all — the
+picker during `install` covers that case instead.
 
 ### Context menus are native on macOS
 
@@ -1130,7 +1333,8 @@ stacking and picks up whatever else is on your desktop. Every view `shot`
 captures is therefore an in-document surface.
 
 You can still *look* at popups in `watch`, and inspect them with the Browser
-Toolbox. They just can't be captured.
+Toolbox. These separate popup windows cannot be captured. The standard
+screenshot set does include the window-modal quit-confirmation dialog.
 
 ### Why not Selenium?
 
@@ -1160,12 +1364,87 @@ Each session also picks its own Marionette port. Firefox's fixed default of 2828
 means a browser leaked by an earlier run would silently accept the next
 session's connection, which shows up as your theme mysteriously not applying.
 
+## Commands
+
+| Command | What it's for |
+| --- | --- |
+| [`new`](#fxcss-new) | Start a theme from a small, working scaffold |
+| [`try`](#fxcss-try) | Download a theme from GitHub and test-drive it |
+| [`install`](#fxcss-install) | Install a theme into your real Firefox profile |
+| [`uninstall`](#fxcss-uninstall) | Remove managed files while preserving local changes |
+| [`upgrade`](#fxcss-upgrade) | Fetch a newer version of the theme you installed |
+| [`rollback`](#fxcss-rollback) | Put the previous version back |
+| [`adopt`](#fxcss-adopt) | Take over a theme installed some other way |
+| [`profiles`](#fxcss-profiles) | List every Firefox profile and what is themed in it |
+| [`watch`](#fxcss-watch) | Edit CSS and see it live, no restart |
+| [`pick`](#fxcss-pick) | Click any part of the UI to get its CSS selector |
+| [`inspect`](#fxcss-inspect) | Look up a selector you already have |
+| [`init`](#fxcss-init) | Add PR previews and CI checks to your theme repo |
+| [`tweaks`](#fxcss-tweaks) | Screenshot every install option into a committable doc |
+| [`audit`](#fxcss-audit) | Check selectors and custom properties for compatibility findings |
+| [`changelog`](#fxcss-changelog) | Diff two Firefox builds to see what chrome changed |
+| [`snapshot`](#fxcss-snapshot) | Record a Firefox's chrome names, to diff against later |
+| [`catalogue`](#fxcss-catalogue) | Build a directory of themeable UI parts |
+| [`shot`](#fxcss-shot) / [`compare`](#fxcss-compare) | Screenshot and diff two versions |
+| [`check`](#fxcss-check) | Run saved audit, capture and comparison settings with one combined report |
+| [`doctor`](#fxcss-doctor) | Report what your Firefox supports |
+| [`completions`](#fxcss-completions) | Enable Bash, Zsh or Fish tab completion |
+
 ## Contributing
 
 Issues and pull requests welcome — particularly landmark definitions for UI
 parts the catalogue doesn't cover yet, and reports of selectors that changed in
 a new Firefox release.
 
+To work on fxcss itself, clone and install it in an editable environment:
+
+```bash
+git clone https://github.com/AdamXweb/fxcss.git
+cd fxcss && python3 -m pip install -e ".[images]"
+```
+
+And if you would rather install nothing at all, the repo runs as-is:
+
+```bash
+python3 -m fxcss <command>
+```
+
+### Testing fxcss itself
+
+The toolkit's own CI runs unit tests on Python 3.9, 3.12 and 3.14. Profile
+installation, upgrade, rollback, removal and failure recovery are checked on
+macOS, Windows and Linux, including edited files and paths with spaces and
+non-ASCII characters. Real Firefox checks cover Stable on all three platforms
+and ESR on Linux, repeated capture consistency, deliberate CSS changes,
+nested imports, content stylesheets and stacked optional stylesheets.
+
+A separate compatibility workflow checks Stable, ESR, Beta and Nightly on Linux
+every Monday and Thursday, or on demand. Failed audits, incomplete captures and
+rendering differences fail the run; reports and screenshots are retained as
+workflow artifacts. These checks help detect browser changes between releases.
+To test a development branch before merging, manually run **CI** on that branch
+and enable **compatibility** to include all four channels. Normal PR CI runs
+Stable and ESR; the additional channels are optional for manual runs.
+
+Package publishing is gated on CI and checks of the exact wheel and source
+archive being published. Clean environments outside the checkout test the
+base install, optional image dependencies, generated workflows and profile
+compatibility with the latest released fxcss. Package checks run on all three
+operating systems with Python 3.9 and 3.14; the release tag must also match the
+built package version. These are fxcss's own checks; `init` generates the theme
+repository workflows described above.
+
+Run the checks locally with:
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 -m tests.smoke_themes       # requires Firefox and a display
+python3 -m tests.smoke_variants     # requires Firefox and a display
+python3 -m pip install build
+python3 -m build
+python3 scripts/package_smoke.py --dist dist  # downloads the released package and image dependencies
+```
+
 ## How this was built
 
 fxcss was written with the assistance of **Claude** (Anthropic's Claude Opus 5),
@@ -1186,14 +1465,6 @@ git log --format='%an'                        # who authored each commit
 git log --format='%b' | grep Co-Authored-By   # which were AI-assisted
 ```
 
-Behaviour is not taken on trust either. CI runs on macOS and Windows on every
-push and asserts the comparison in **both** directions: an unchanged theme must
-render identically across runs, and an obvious CSS change must be detected.
-That check found most of the real bugs in this tool — a random temp path leaking
-into the address bar, Firefox flashing the find bar yellow as it opens, a
-scrollbar appearing in one private-window capture and not the next — none of
-which review had caught.
-
 ## Credits
 
 Built while adding visual PR previews to