fxcss 0.16.2__tar.gz → 0.18.0__tar.gz

{fxcss-0.16.2 → fxcss-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxcss
-Version: 0.16.2
+Version: 0.18.0
 Summary: Live-reload, inspect and screenshot-test Firefox userChrome.css themes
 Author: AdamXweb
 License: MIT
@@ -122,7 +122,7 @@ 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.16.2"
+pip install "fxcss[images]==0.18.0"
 ```
 
 Either gives you an `fxcss` command. To hack on it, clone and install editable:
@@ -322,9 +322,11 @@ screenshotting a `--combo` that cannot take effect.
 > fighting over the same property. Two sheets that rearrange the same area
 > through *different* selectors — WhiteSur's `tabs-swapclose` and
 > `windows-swapclose` both move a close button and share no declarations at
-> all — are invisible to it. `fxcss tweaks --combo a+b` is what proves those:
-> if `a+b` renders identically to `b` alone, `a` was overridden. Silence here
-> is "nothing measurable", never "verified compatible".
+> all — are invisible to it. `fxcss tweaks --combo a+b` proves those from
+> the rendered pixels — and says so itself: a combo that renders identically
+> to one of its parts alone is called out in TWEAKS.md as not a real
+> combination on that Firefox. Silence from the static check is "nothing
+> measurable", never "verified compatible"; the pixels are the judge.
 
 When the theme's default branch has moved on since its newest release, that
 choice is put to you as well — a tag can be a year behind a fix you are
@@ -369,6 +371,7 @@ Restart Firefox after either command; it reads `userChrome.css` at startup.
 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
 ```
@@ -391,6 +394,15 @@ It stops rather than surprise you, in three places:
   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
@@ -681,6 +693,16 @@ 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:
 
 [![theme previews by fxcss](https://img.shields.io/badge/theme%20previews-fxcss-ff7139)](https://github.com/AdamXweb/fxcss)
@@ -699,6 +721,13 @@ 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.
 
+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.
+
 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,
@@ -1013,7 +1042,7 @@ check out the base revision and the pull request revision, render both, compare,
 and publish the result.
 
 ```yaml
-- run: pip install "fxcss[images]==0.16.2"   # pin: your CI, your upgrades
+- run: pip install "fxcss[images]==0.18.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 }}

{fxcss-0.16.2 → fxcss-0.18.0}/README.md

@@ -99,7 +99,7 @@ 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.16.2"
+pip install "fxcss[images]==0.18.0"
 ```
 
 Either gives you an `fxcss` command. To hack on it, clone and install editable:
@@ -299,9 +299,11 @@ screenshotting a `--combo` that cannot take effect.
 > fighting over the same property. Two sheets that rearrange the same area
 > through *different* selectors — WhiteSur's `tabs-swapclose` and
 > `windows-swapclose` both move a close button and share no declarations at
-> all — are invisible to it. `fxcss tweaks --combo a+b` is what proves those:
-> if `a+b` renders identically to `b` alone, `a` was overridden. Silence here
-> is "nothing measurable", never "verified compatible".
+> all — are invisible to it. `fxcss tweaks --combo a+b` proves those from
+> the rendered pixels — and says so itself: a combo that renders identically
+> to one of its parts alone is called out in TWEAKS.md as not a real
+> combination on that Firefox. Silence from the static check is "nothing
+> measurable", never "verified compatible"; the pixels are the judge.
 
 When the theme's default branch has moved on since its newest release, that
 choice is put to you as well — a tag can be a year behind a fix you are
@@ -346,6 +348,7 @@ Restart Firefox after either command; it reads `userChrome.css` at startup.
 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
 ```
@@ -368,6 +371,15 @@ It stops rather than surprise you, in three places:
   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
@@ -658,6 +670,16 @@ 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:
 
 [![theme previews by fxcss](https://img.shields.io/badge/theme%20previews-fxcss-ff7139)](https://github.com/AdamXweb/fxcss)
@@ -676,6 +698,13 @@ 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.
 
+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.
+
 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,
@@ -990,7 +1019,7 @@ check out the base revision and the pull request revision, render both, compare,
 and publish the result.
 
 ```yaml
-- run: pip install "fxcss[images]==0.16.2"   # pin: your CI, your upgrades
+- run: pip install "fxcss[images]==0.18.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 }}

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss/__init__.py

@@ -1,3 +1,3 @@
 """fxcss — a testing toolkit for Firefox userChrome.css themes."""
 
-__version__ = "0.16.2"
+__version__ = "0.18.0"

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss/cli.py

@@ -1048,6 +1048,31 @@ def cmd_upgrade(args):
                       "upgrade anyway.", file=sys.stderr)
                 return 1
 
+        if args.compare:
+            # Seeing beats being told: render what is installed and what the
+            # upgrade would install, and diff them, before the question is
+            # asked. The profile itself is the theme root for the installed
+            # side -- its chrome/ IS the theme as the user actually has it,
+            # local edits and carried-over sheets included, which no re-fetch
+            # of the recorded ref could reproduce.
+            try:
+                from . import compare as compare_mod
+            except ImportError as exc:
+                return _needs_pillow("upgrade --compare", exc)
+            import tempfile
+            firefox = choose_firefox(args.firefox)
+            outdir = Path(tempfile.mkdtemp(prefix="fxcss-upgrade-compare-"))
+            print("\n  rendering what is installed now …")
+            with core.Session(Path(picked["path"]), firefox) as session:
+                core.capture_views(session, outdir / "installed")
+            print(f"\n  rendering {why} …")
+            with core.Session(theme_root, firefox) as session:
+                core.capture_views(session, outdir / "new")
+            print()
+            compare_mod.run(outdir / "installed", outdir / "new",
+                            outdir / "diff", "upgrade")
+            print(f"  before/after images: {outdir / 'diff'}")
+
         if install.firefox_running(picked["path"]):
             print("\n  note: Firefox appears to be running — the change will "
                   "only show after a restart.")
@@ -1778,6 +1803,10 @@ def build_parser():
                     help="report only, changing nothing. Exit 0 when up to "
                          "date, 1 when an upgrade is available, 2 when it "
                          "cannot be told — for cron and CI")
+    up.add_argument("--compare", action="store_true",
+                    help="render the installed theme and the new version, "
+                         "and show what changes, before asking (needs Pillow "
+                         "and a local Firefox)")
     up.add_argument("--audit", action="store_true",
                     help="before installing, check the new version's "
                          "selectors against a real Firefox")

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss/templates/firefox-watch.yml

@@ -91,6 +91,74 @@ jobs:
           echo "version=${version:-unknown}" >> "$GITHUB_OUTPUT"
           if [ -s fxcss-fix.patch ]; then echo "patch=yes" >> "$GITHUB_OUTPUT"; fi
 
+      # The audit sees selectors; it does not see the capture pipeline. When
+      # Firefox 154 moved a module out from under fxcss, every preview render
+      # broke on release day while a (then healthy) audit-only watch would
+      # have stayed green -- beta had the breakage four days early and nothing
+      # could say so. One standard capture per channel is the canary for that:
+      # if this fails on beta, PR previews fail when that Firefox reaches
+      # release, and the usual fix is an fxcss update rather than a theme one.
+      - name: Capture smoke
+        id: smoke
+        if: ${{ github.event.inputs.channel == '' || github.event.inputs.channel == matrix.channel }}
+        run: |
+          set +e
+          fxcss shot --out "$RUNNER_TEMP/smoke" > smoke.txt 2>&1
+          status=$?
+          tail -40 smoke.txt
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+      - name: Open or update the capture-pipeline issue
+        if: steps.smoke.outputs.status != '0'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ matrix.channel }}
+          VERSION: ${{ steps.audit.outputs.version }}
+        run: |
+          set -euo pipefail
+          title="Firefox ${CHANNEL}: the capture pipeline broke"
+          {
+            echo "Rendering this theme against Firefox **${CHANNEL}** (**${VERSION}**) crashed"
+            echo "outright -- not a styling regression, the capture itself. When this"
+            echo "Firefox reaches release, the PR preview and README preview workflows"
+            echo "will fail the same way."
+            echo
+            echo "This is usually Firefox moving something out from under fxcss (as"
+            echo "Firefox 154 did), so the fix is typically a newer fxcss release and a"
+            echo "pin bump here -- check https://github.com/AdamXweb/fxcss/releases and"
+            echo "open an issue there if nothing newer exists."
+            echo
+            echo "The last lines of the failed capture:"
+            echo
+            echo '```'
+            tail -40 smoke.txt
+            echo '```'
+            echo
+            echo "_Updated automatically. This closes itself when the channel is clean._"
+          } > smoke-body.md
+          existing=$(gh issue list --state open --search "$title in:title" \
+            --json number,title --jq "[.[] | select(.title == \"$title\")][0].number")
+          if [ -n "$existing" ] && [ "$existing" != "null" ]; then
+            gh issue edit "$existing" --body-file smoke-body.md
+          else
+            gh issue create --title "$title" --body-file smoke-body.md
+          fi
+
+      - name: Close the capture-pipeline issue if this channel is clean again
+        if: steps.smoke.outputs.status == '0'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ matrix.channel }}
+        run: |
+          set -euo pipefail
+          title="Firefox ${CHANNEL}: the capture pipeline broke"
+          existing=$(gh issue list --state open --search "$title in:title" \
+            --json number,title --jq "[.[] | select(.title == \"$title\")][0].number")
+          if [ -n "$existing" ] && [ "$existing" != "null" ]; then
+            gh issue close "$existing" \
+              --comment "Firefox ${CHANNEL} captures cleanly again -- closing."
+          fi
+
       - name: Open a pull request with the confident fixes
         if: steps.audit.outputs.status != '0' && steps.audit.outputs.patch == 'yes'
         env:
@@ -182,6 +250,7 @@ jobs:
           name: audit-${{ matrix.channel }}
           path: |
             audit.txt
+            smoke.txt
             fxcss-fix.patch
           if-no-files-found: ignore
           retention-days: 30

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss/templates/pr-preview.yml

@@ -122,9 +122,58 @@ jobs:
       - name: Environment
         run: fxcss doctor --theme head
 
+      # The base branch renders identically every time -- that determinism is
+      # the contract fxcss's own CI asserts -- so after the first push to a
+      # pull request there is no reason to render it again. The key names
+      # everything that could change the pixels: the base commit, the runner
+      # image, the Firefox that happened to be current, the fxcss release and
+      # this workflow file. A miss on any of them re-renders; there is no
+      # restore-keys fallback, because a near-match is a different render.
+      #
+      # GitHub scopes caches to the branch that made them, so this helps the
+      # second and later pushes of a pull request, not its first.
+      - name: Base render cache key
+        id: basekey
+        shell: bash
+        run: |
+          firefox=$(python - <<'EOF'
+          import configparser, os, pathlib
+          binary = pathlib.Path(os.environ["FIREFOX_BIN"])
+          for ini in (binary.parent / "application.ini",
+                      binary.parent.parent / "Resources" / "application.ini"):
+              if ini.is_file():
+                  cfg = configparser.ConfigParser(); cfg.read(ini, encoding="utf-8")
+                  print(cfg.get("App", "Version", fallback="unknown")); break
+          else:
+              print("unknown")
+          EOF
+          )
+          echo "firefox=$firefox" >> "$GITHUB_OUTPUT"
+          echo "image=${ImageVersion:-unknown}" >> "$GITHUB_OUTPUT"
+          echo "base render key: firefox=$firefox image=${ImageVersion:-unknown}"
+
+      - name: Restore base render
+        id: basecache
+        uses: actions/cache/restore@v5
+        with:
+          path: shots/base
+          key: >-
+            base-render-${{ matrix.label }}-${{ github.event.pull_request.base.sha }}-ff${{ steps.basekey.outputs.firefox }}-img${{ steps.basekey.outputs.image }}-fxcss${{ env.FXCSS_VERSION }}-${{ hashFiles('head/.github/workflows/pr-preview.yml') }}
+
       - name: Render base revision
+        if: steps.basecache.outputs.cache-hit != 'true'
         run: fxcss shot --theme base --out shots/base --variants all
 
+      # Saved the moment the base render succeeds rather than when the job
+      # ends: a push that supersedes this run cancels it, and the base is
+      # usually done by then -- which is exactly the run the next push wants.
+      - name: Save base render
+        if: steps.basecache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: shots/base
+          key: ${{ steps.basecache.outputs.cache-primary-key }}
+
       - name: Render pull request revision
         run: fxcss shot --theme head --out shots/head --variants all
 

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss/tweaks.py

@@ -200,6 +200,7 @@ def build(session, theme: Path, outdir: Path, variants, flags):
     _shrink(base, FULL_WIDTH).save(outdir / "base.png", optimize=True)
 
     entries = []
+    captures = {}
     for slug, sheets in sorted(variants.items()):
         for sheet in sheets:
             session.m.script(core.LOAD_VARIANT_SHEET, [sheet.resolve().as_uri()])
@@ -218,15 +219,55 @@ def build(session, theme: Path, outdir: Path, variants, flags):
         else:
             (outdir / f"{slug}.png").unlink()
         entries.append(entry)
+        captures[slug] = after
         state = f"{pct:.2f}% of the chrome" if changed else "nothing on this Firefox"
         print(f"  {slug}: changes {state}", flush=True)
 
+    for entry in entries:
+        matched = combo_verdict(entry, captures)
+        if matched:
+            entry["same_as"] = matched
+            print(f"  {entry['slug']}: renders identically to {matched} alone "
+                  "— the other sheet(s) have no effect in this combination",
+                  flush=True)
+
     info = session.info()
     markdown = render_markdown(theme, entries, flags, info["version"])
     (outdir / "TWEAKS.md").write_text(markdown, encoding="utf-8")
     return entries
 
 
+def combo_verdict(entry, captures):
+    """The single option a combo capture is pixel-identical to, or None.
+
+    Static analysis can say two sheets set the same declarations; it cannot
+    see two sheets that fight over the same pixels through different rules --
+    WhiteSur's tabs-swapclose and windows-swapclose both move the tab close
+    button while sharing no declarations at all. The rendered images settle
+    it: if `a+b` is identical to `b` alone, then `a` did nothing in that
+    combination, and that is a fact about pixels rather than a judgement.
+    Identical means what it means everywhere else in fxcss -- zero pixels
+    changed above diff_stats' noise threshold.
+
+    Only combinations are judged, and only against their own constituents:
+    `a+b` matching some unrelated option c would be a coincidence worth
+    nothing. Returns the constituent's slug, or None when the combo really is
+    more than any one of its parts.
+    """
+    parts = entry["slug"].split("+")
+    if len(parts) < 2 or entry["slug"] not in captures:
+        return None
+    combo = captures[entry["slug"]]
+    for part in parts:
+        single = captures.get(part)
+        if single is None or single.size != combo.size:
+            continue
+        changed, _, _ = diff_stats(single, combo)
+        if changed == 0:
+            return part
+    return None
+
+
 def render_markdown(theme: Path, entries, flags, firefox_version):
     """The committable document. Pure, so it is unit-testable."""
     lines = [
@@ -261,6 +302,13 @@ def render_markdown(theme: Path, entries, flags, firefox_version):
             lines.append("")
             lines.append(f"Full window: [{slug}.png]({slug}.png)")
             lines.append("")
+        if entry.get("same_as"):
+            others = " + ".join(part for part in slug.split("+")
+                                if part != entry["same_as"]) or "the rest"
+            lines.append(f"**Not a real combination on this Firefox:** it "
+                         f"renders pixel-identically to `{entry['same_as']}` "
+                         f"alone — `{others}` has no effect here.")
+            lines.append("")
         enable = ", ".join(f"`{sheet_path_for_doc(theme, s)}`" for s in entry["sheets"])
         lines.append(f"Enable by copying {enable} into your profile's `chrome/` "
                      f"folder (or with the installer flags below, if the theme "

{fxcss-0.16.2 → fxcss-0.18.0}/fxcss.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxcss
-Version: 0.16.2
+Version: 0.18.0
 Summary: Live-reload, inspect and screenshot-test Firefox userChrome.css themes
 Author: AdamXweb
 License: MIT
@@ -122,7 +122,7 @@ 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.16.2"
+pip install "fxcss[images]==0.18.0"
 ```
 
 Either gives you an `fxcss` command. To hack on it, clone and install editable:
@@ -322,9 +322,11 @@ screenshotting a `--combo` that cannot take effect.
 > fighting over the same property. Two sheets that rearrange the same area
 > through *different* selectors — WhiteSur's `tabs-swapclose` and
 > `windows-swapclose` both move a close button and share no declarations at
-> all — are invisible to it. `fxcss tweaks --combo a+b` is what proves those:
-> if `a+b` renders identically to `b` alone, `a` was overridden. Silence here
-> is "nothing measurable", never "verified compatible".
+> all — are invisible to it. `fxcss tweaks --combo a+b` proves those from
+> the rendered pixels — and says so itself: a combo that renders identically
+> to one of its parts alone is called out in TWEAKS.md as not a real
+> combination on that Firefox. Silence from the static check is "nothing
+> measurable", never "verified compatible"; the pixels are the judge.
 
 When the theme's default branch has moved on since its newest release, that
 choice is put to you as well — a tag can be a year behind a fix you are
@@ -369,6 +371,7 @@ Restart Firefox after either command; it reads `userChrome.css` at startup.
 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
 ```
@@ -391,6 +394,15 @@ It stops rather than surprise you, in three places:
   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
@@ -681,6 +693,16 @@ 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:
 
 [![theme previews by fxcss](https://img.shields.io/badge/theme%20previews-fxcss-ff7139)](https://github.com/AdamXweb/fxcss)
@@ -699,6 +721,13 @@ 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.
 
+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.
+
 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,
@@ -1013,7 +1042,7 @@ check out the base revision and the pull request revision, render both, compare,
 and publish the result.
 
 ```yaml
-- run: pip install "fxcss[images]==0.16.2"   # pin: your CI, your upgrades
+- run: pip install "fxcss[images]==0.18.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 }}

{fxcss-0.16.2 → fxcss-0.18.0}/tests/test_units.py

@@ -2440,7 +2440,9 @@ class TemplateActionVersionTests(unittest.TestCase):
     two to each other turns the next Dependabot bump into a failing test.
     """
 
-    PIN = re.compile(r"uses:\s*actions/([a-z-]+)@v(\d+)")
+    # `actions/cache/restore@v5` is actions/cache: the sub-path is not a
+    # separate action and is versioned with its parent.
+    PIN = re.compile(r"uses:\s*actions/([a-z-]+)(?:/[a-z-]+)?@v(\d+)")
 
     def versions(self, paths):
         found = {}
@@ -2473,9 +2475,75 @@ class TemplateActionVersionTests(unittest.TestCase):
         """
         root = Path(__file__).resolve().parent.parent
         floors = {"checkout": 5, "setup-python": 6, "upload-artifact": 6,
-                  "download-artifact": 7, "github-script": 8}
+                  "download-artifact": 7, "github-script": 8, "cache": 5}
         shipped = self.versions((root / "fxcss" / "templates").glob("*.yml"))
         for name, floor in floors.items():
             for major in shipped.get(name, ()):
                 self.assertGreaterEqual(
                     major, floor, f"actions/{name}@v{major} runs on Node 20")
+
+
+class ComboVerdictTests(unittest.TestCase):
+    """`a+b` rendering identically to `b` alone proves `a` did nothing there.
+
+    This is the pixel half of the sheet-conflict story: sheets.py sees two
+    sheets fighting over the same declarations, and cannot see two sheets
+    fighting over the same pixels through different rules (tabs-swapclose vs
+    windows-swapclose share no declarations at all). The rendered images are
+    the honest judge, with "identical" meaning the same thing it means in
+    compare: zero pixels changed above the noise threshold.
+    """
+
+    def image(self, colour):
+        from PIL import Image
+        return Image.new("RGB", (24, 16), colour)
+
+    def entry(self, slug):
+        return {"slug": slug, "sheets": [], "percent": 0.0, "image": None}
+
+    def test_a_combo_identical_to_one_part_names_that_part(self):
+        from fxcss.tweaks import combo_verdict
+        captures = {"a": self.image((200, 50, 50)),
+                    "b": self.image((100, 100, 100)),
+                    "a+b": self.image((100, 100, 100))}
+        self.assertEqual(combo_verdict(self.entry("a+b"), captures), "b")
+
+    def test_noise_below_the_diff_threshold_still_counts_as_identical(self):
+        from fxcss.tweaks import combo_verdict
+        near = self.image((100, 100, 110))       # the DiffStats noise case
+        captures = {"a": self.image((200, 50, 50)),
+                    "b": self.image((100, 100, 100)), "a+b": near}
+        self.assertEqual(combo_verdict(self.entry("a+b"), captures), "b")
+
+    def test_a_combo_that_is_more_than_its_parts_matches_nothing(self):
+        from fxcss.tweaks import combo_verdict
+        captures = {"a": self.image((200, 50, 50)),
+                    "b": self.image((100, 100, 100)),
+                    "a+b": self.image((50, 200, 50))}
+        self.assertIsNone(combo_verdict(self.entry("a+b"), captures))
+
+    def test_single_options_are_never_judged(self):
+        from fxcss.tweaks import combo_verdict
+        captures = {"a": self.image((1, 2, 3)), "b": self.image((1, 2, 3))}
+        self.assertIsNone(combo_verdict(self.entry("a"), captures))
+
+    def test_a_window_that_changed_size_is_not_compared(self):
+        from PIL import Image
+        from fxcss.tweaks import combo_verdict
+        captures = {"a": Image.new("RGB", (10, 10), (1, 2, 3)),
+                    "a+b": self.image((1, 2, 3))}
+        self.assertIsNone(combo_verdict(self.entry("a+b"), captures))
+
+    def test_the_markdown_carries_the_verdict(self):
+        from fxcss.tweaks import render_markdown
+        with tempfile.TemporaryDirectory() as td:
+            entries = [
+                {"slug": "a+b", "sheets": [], "percent": 1.0,
+                 "image": None, "same_as": "b"},
+                {"slug": "compact-tabs", "sheets": [], "percent": 1.0,
+                 "image": None},
+            ]
+            text = render_markdown(Path(td), entries, [], "154.0")
+            self.assertIn("renders pixel-identically to `b` alone", text)
+            self.assertIn("`a` has no effect here", text)
+            self.assertEqual(text.count("Not a real combination"), 1)