[adamXbot]

Follows #105, which is merged; rebased onto main after that squash merge, with no change in content.

Data safety (first commit)

Seven ways install, upgrade, adopt and uninstall could lose or overwrite something that was not fxcss's to touch. The four checked against 0.25.0 (original backup, hook, pins, OS litter) happen there too.

• The original chrome/ backup could be pruned. Install over your own chrome/, install again, upgrade three times: the backup holding your files was deleted and uninstall restored the first theme instead. The origin is now carried through repeat installs and rollbacks, and manifests 0.25 already mis-recorded are followed back to the real original when read.
• customChrome.css. fxcss recorded its own placeholder as a theme file, so a filled-in hook blocked upgrades and --force replaced it with a new placeholder. A hook you have written in is now yours and is carried across.
• --ref pins. A bare fxcss upgrade re-downloaded and reinstalled the same ref and made a backup each time. It now says it is pinned and does nothing; --ref and --commit still move it.
• OS litter. .DS_Store, Thumbs.db and desktop.ini no longer stop uninstall restoring the original.
• adopt. Files the matched version does not ship are recorded as yours and survive upgrades, instead of being dropped by the next one.
• user.js. A stray BEGIN marker can no longer claim a later block's END and take your lines with it.
• Pref listing. Every pref fxcss will write is named before you confirm, user_pref ("x", …) is recognised, and control characters are escaped.

Behaviour change: --keep prunes only backups that hold an fxcss install record. A hand-made chrome.backup-* folder is never deleted or counted.

Terminal polish and README (second commit)

• A menu whose prompt wraps is redrawn in place. The same keystrokes in a 62-column terminal left 86 screen lines before and 30 now.
• upgrade, rollback, adopt, uninstall and init open and close the way install does. upgrade --no-colour holds for the whole command.
• fxcss doctor outside a theme folder reports on Firefox alone instead of exiting 2.
• A console code page with no arrow or tick gets ASCII stand-ins instead of a UnicodeEncodeError.
• Colour on a Windows console enables VT processing first. Not run on Windows.
• init warns about an unpublished pin only when fxcss was not installed from PyPI.
• Wording: "1 element matches", "1 token out of reach", no empty audit heading, no "0 KB".
• README: seven sample outputs are real 0.26 output; the notes on pins, hooks, backups and doctor match what now happens.

How it was tested

• Unit tests: 864 pass on Python 3.9, 3.12, 3.14 and 3.15, under FORCE_COLOR=1, at 40 and 60 columns, and inside a terminal. The first commit alone passes 845.
• tests/test_data_safety.py (38 tests) fails 31 ways on main.
• Each data-safety case was reproduced in a scratch profile before the fix and re-run after.
• Live Firefox 158 on macOS: doctor, theme layouts, startup, audio, variants, capture, determinism, real-change, audit and inspect pass. Determinism differed in one view on one run while the machine was busy and was identical on a clean re-run.
• The website's docs build from this README: 48 pages, site tests pass.

Not covered

• Windows and Linux were not run locally.
• rollback with no --to still takes the newest chrome.backup-* by name, which can be a hand-made folder.
• Symlinked user.js or chrome/, flat layouts with asset folders used only by optional sheets, and fetch tracebacks on truncated downloads are unchanged.

🤖 Generated with Claude Code