fxcss 0.7.0__tar.gz → 0.8.0__tar.gz

{fxcss-0.7.0 → fxcss-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxcss
-Version: 0.7.0
+Version: 0.8.0
 Summary: Live-reload, inspect and screenshot-test Firefox userChrome.css themes
 Author: AdamXweb
 License: MIT
@@ -29,6 +29,14 @@ Edit your CSS and see it live, click any part of the UI to get its selector,
 and screenshot-test changes in CI.
 </p>
 
+**Three ways in:**
+
+| You are… | Start with |
+| --- | --- |
+| **Building a theme** | `fxcss watch` — edit CSS, see it 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. |
+| **Maintaining a theme repo** | `fxcss init` — before/after screenshots on every pull request, on macOS, Windows and Linux. |
+
 ## Description
 
 Working on a Firefox theme normally means: edit CSS, restart Firefox, squint,
@@ -41,10 +49,10 @@ gives you a live-reload loop, an element picker, and a screenshot differ.
 
 Your real Firefox profile is never touched.
 
-![The example theme rendered in light and dark](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch.png)
+![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><code>examples/minimal-theme</code>, light and dark — every screenshot in this
-README was generated by fxcss itself.</sub></p>
+<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
 
@@ -93,6 +101,7 @@ at it with `--theme /path/to/theme`.
 | [`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 |
 | [`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 |
@@ -171,6 +180,8 @@ a file in your editor and the running window updates in about 50ms.
 The window is yours to drive — open menus, resize it, type in the address bar,
 right-click things. Nothing is scripted.
 
+![The example theme rendered in light and dark](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch.png)
+
 | flag | effect |
 | --- | --- |
 | `--dark` | start in dark mode, for testing `prefers-color-scheme` rules |
@@ -233,6 +244,32 @@ 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
+
+```bash
+fxcss init                       # before/after previews on every PR
+fxcss init --watch --showcase    # plus the weekly Firefox audit and
+                                 # release screenshots
+```
+
+**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 sixteen 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).
+
+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)
+
 ### fxcss audit
 
 ```bash
@@ -480,11 +517,12 @@ Two things to know before wiring this up:
   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.
 
-`examples/` has working workflows to copy — the pull request preview pair, the
-scheduled Firefox-channel watcher, and the showcase capture. See
-[`examples/README.md`](examples/README.md) for which to start with and why the
-preview is split into two files. This repo's own `.github/workflows/ci.yml`
-runs the whole thing against `examples/minimal-theme` on macOS and Windows.
+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 `examples/minimal-theme` on macOS, Windows and Linux.
 
 ## Things worth knowing
 

{fxcss-0.7.0 → fxcss-0.8.0}/README.md

@@ -8,6 +8,14 @@ Edit your CSS and see it live, click any part of the UI to get its selector,
 and screenshot-test changes in CI.
 </p>
 
+**Three ways in:**
+
+| You are… | Start with |
+| --- | --- |
+| **Building a theme** | `fxcss watch` — edit CSS, see it 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. |
+| **Maintaining a theme repo** | `fxcss init` — before/after screenshots on every pull request, on macOS, Windows and Linux. |
+
 ## Description
 
 Working on a Firefox theme normally means: edit CSS, restart Firefox, squint,
@@ -20,10 +28,10 @@ gives you a live-reload loop, an element picker, and a screenshot differ.
 
 Your real Firefox profile is never touched.
 
-![The example theme rendered in light and dark](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch.png)
+![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><code>examples/minimal-theme</code>, light and dark — every screenshot in this
-README was generated by fxcss itself.</sub></p>
+<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
 
@@ -72,6 +80,7 @@ at it with `--theme /path/to/theme`.
 | [`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 |
 | [`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 |
@@ -150,6 +159,8 @@ a file in your editor and the running window updates in about 50ms.
 The window is yours to drive — open menus, resize it, type in the address bar,
 right-click things. Nothing is scripted.
 
+![The example theme rendered in light and dark](https://raw.githubusercontent.com/AdamXweb/fxcss/main/docs/watch.png)
+
 | flag | effect |
 | --- | --- |
 | `--dark` | start in dark mode, for testing `prefers-color-scheme` rules |
@@ -212,6 +223,32 @@ 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
+
+```bash
+fxcss init                       # before/after previews on every PR
+fxcss init --watch --showcase    # plus the weekly Firefox audit and
+                                 # release screenshots
+```
+
+**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 sixteen 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).
+
+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)
+
 ### fxcss audit
 
 ```bash
@@ -459,11 +496,12 @@ Two things to know before wiring this up:
   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.
 
-`examples/` has working workflows to copy — the pull request preview pair, the
-scheduled Firefox-channel watcher, and the showcase capture. See
-[`examples/README.md`](examples/README.md) for which to start with and why the
-preview is split into two files. This repo's own `.github/workflows/ci.yml`
-runs the whole thing against `examples/minimal-theme` on macOS and Windows.
+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 `examples/minimal-theme` on macOS, Windows and Linux.
 
 ## Things worth knowing
 

{fxcss-0.7.0 → fxcss-0.8.0}/fxcss/__init__.py

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

{fxcss-0.7.0 → fxcss-0.8.0}/fxcss/cli.py

@@ -2,6 +2,7 @@
 """fxcss - a testing toolkit for Firefox userChrome.css themes.
 
     fxcss try          download a theme from GitHub and test-drive it
+    fxcss init         add PR previews and CI checks to your theme repo
     fxcss watch        edit CSS and see it live, no restart
     fxcss pick         click any part of the UI to get its CSS selector
     fxcss inspect      look up a selector you already have
@@ -26,6 +27,22 @@ from pathlib import Path
 from . import core
 from . import __version__
 
+LANDING = """fxcss - a testing toolkit for Firefox userChrome.css themes
+
+  Building a theme?
+    fxcss watch                    edit CSS, see it live, no restart
+    fxcss pick                     click any part of the UI to get its selector
+
+  Trying someone else's theme?
+    fxcss try owner/repo           test-drive it in a throwaway profile
+
+  Maintaining a theme repository?
+    fxcss init                     add before/after PR previews and CI checks
+    fxcss audit                    find selectors Firefox has renamed
+
+Run `fxcss --help` for the full command list, or `fxcss <command> --help`
+for one command. Nothing here ever touches your real Firefox profile."""
+
 TOOLBOX_KEY = {
     "darwin": "Cmd+Opt+Shift+I",
 }.get(sys.platform, "Ctrl+Alt+Shift+I")
@@ -159,6 +176,20 @@ def cmd_try(args):
         shutil.rmtree(workdir, ignore_errors=True)
 
 
+def cmd_init(args):
+    from . import scaffold
+    theme = args.theme.resolve()
+    if not (theme / "chrome" / "userChrome.css").exists():
+        print(f"error: no chrome/userChrome.css under {theme} - run this from "
+              f"your theme's root, or pass --theme", file=sys.stderr)
+        return 2
+    slugs = sorted(core.find_variant_sheets(theme))
+    written, skipped = scaffold.write_workflows(
+        theme, slugs, watch=args.watch, showcase=args.showcase, force=args.force)
+    print(scaffold.next_steps(written, skipped, slugs, args.watch, args.showcase))
+    return 0
+
+
 def cmd_watch(args):
     theme = args.theme.resolve()
     firefox = core.find_firefox(args.firefox)
@@ -442,6 +473,8 @@ def cmd_doctor(args):
     print(f"\ntheme: {len(sheets)} stylesheets, {total:,} bytes")
     missing = [p for p in ("chrome/userChrome.css",) if not (theme / p).exists()]
     print("missing expected files: " + (", ".join(missing) if missing else "none"))
+    print("\nnew here? `fxcss try owner/repo` test-drives a theme; `fxcss init`")
+    print("adds PR previews to yours.")
     return 0
 
 
@@ -468,7 +501,7 @@ def main(argv=None):
         prog="fxcss", description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--version", action="version", version=f"fxcss {__version__}")
-    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub = ap.add_subparsers(dest="cmd", required=False)
 
     for verb, helptext in (("try", "download a theme from GitHub and test-drive it"),
                            ("install", "alias for try")):
@@ -492,6 +525,17 @@ def main(argv=None):
         _menus(tr)
         tr.set_defaults(func=cmd_try)
 
+    ini = sub.add_parser("init", help="add PR previews and CI checks to your theme repo")
+    ini.add_argument("--theme", type=Path, default=Path.cwd(),
+                     help="theme root, the folder containing chrome/ (default: cwd)")
+    ini.add_argument("--watch", action="store_true",
+                     help="also add the weekly Firefox release/beta/nightly audit")
+    ini.add_argument("--showcase", action="store_true",
+                     help="also add the on-release showcase screenshot workflow")
+    ini.add_argument("--force", action="store_true",
+                     help="replace workflow files that already exist")
+    ini.set_defaults(func=cmd_init)
+
     w = sub.add_parser("watch", help="live-reload the theme as you edit")
     _common(w); _menus(w)
     w.add_argument("--dark", action="store_true", help="start in dark mode")
@@ -577,6 +621,12 @@ def main(argv=None):
     d.set_defaults(func=cmd_doctor)
 
     args = ap.parse_args(argv)
+    if args.cmd is None:
+        # Bare `fxcss` used to be an argparse error. Greet by task instead:
+        # the three reasons someone installs this are not obvious from a
+        # subcommand list.
+        print(LANDING)
+        return 0
     # Long-running commands are a live log; keep them readable when piped.
     try:
         sys.stdout.reconfigure(line_buffering=True)

{fxcss-0.7.0 → fxcss-0.8.0}/fxcss/compare.py

@@ -73,9 +73,19 @@ def normalise(im, width=PANEL_WIDTH):
 
 
 def diff_stats(base, head):
-    """Return (changed_pixel_count, total, mask) ignoring sub-threshold noise."""
-    delta = ImageChops.difference(base, head).convert("L")
-    mask = delta.point(lambda v: 255 if v >= NOISE_THRESHOLD else 0)
+    """Return (changed_pixel_count, total, mask) ignoring sub-threshold noise.
+
+    Thresholds the per-channel *maximum* difference, not the luminance of the
+    difference. Luminance averages the channels, so a chroma-only shift -- a
+    toolbar tinted from blue-grey to peach, say -- can slide under the
+    threshold while being plainly visible. Recolouring is exactly the kind of
+    change a theme differ exists to catch.
+    """
+    delta = ImageChops.difference(base, head)
+    channel_max = delta.split()[0]
+    for channel in delta.split()[1:]:
+        channel_max = ImageChops.lighter(channel_max, channel)
+    mask = channel_max.point(lambda v: 255 if v >= NOISE_THRESHOLD else 0)
     changed = mask.histogram()[255]
     return changed, base.width * base.height, mask
 

fxcss-0.8.0/fxcss/scaffold.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Generate CI workflows for a theme repository: the machinery behind
+`fxcss init`.
+
+The templates ship inside the package, so a `pipx install fxcss` user gets
+them without ever visiting the repository. Three things are substituted per
+theme, which is exactly the hand-editing that used to trip people up:
+
+* the fxcss version pin, set to the version doing the generating
+* the publish allowlist's variant names, enumerated from the theme's own
+  optional stylesheets -- an allowlist someone has to remember to extend is
+  an allowlist that silently drops views
+* the showcase URL, taken from the repository's origin remote
+"""
+
+import re
+import subprocess
+from importlib import resources
+from pathlib import Path
+
+from . import __version__
+
+PREVIEW_FILES = ("pr-preview.yml", "pr-preview-publish.yml", "pr-preview-cleanup.yml")
+WATCH_FILE = "firefox-watch.yml"
+SHOWCASE_FILE = "showcase.yml"
+
+
+def variant_alternation(slugs):
+    """The regex fragment that admits this theme's variant captures.
+
+    Empty when there are no variants, so the allowlist stays as tight as the
+    theme is simple.
+    """
+    names = sorted(s for s in slugs if re.fullmatch(r"[a-z0-9-]+", s))
+    if not names:
+        return ""
+    return "|variant-(?:" + "|".join(names) + ")"
+
+
+def https_repo_url(remote):
+    """Normalise a git remote to a browsable https URL, or None."""
+    if not remote:
+        return None
+    remote = remote.strip()
+    match = re.match(r"^git@([^:]+):(.+?)(?:\.git)?$", remote)
+    if match:
+        return f"https://{match.group(1)}/{match.group(2)}"
+    match = re.match(r"^(https?://[^ ]+?)(?:\.git)?/?$", remote)
+    if match:
+        return match.group(1)
+    return None
+
+
+def detect_repo_url(theme: Path):
+    try:
+        raw = subprocess.run(
+            ["git", "-C", str(theme), "config", "--get", "remote.origin.url"],
+            capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.SubprocessError):
+        raw = ""
+    return https_repo_url(raw)
+
+
+def render_template(text, version, variant_alt, repo_url):
+    text = text.replace("__FXCSS_VERSION__", version)
+    text = text.replace("__FXCSS_VARIANT_ALT__", variant_alt)
+    text = text.replace("__FXCSS_REPO_URL__", repo_url or "https://example.com")
+    return text
+
+
+def _template(name):
+    return (resources.files("fxcss") / "templates" / name).read_text(encoding="utf-8")
+
+
+def write_workflows(theme: Path, variant_slugs, watch=False, showcase=False,
+                    force=False, version=None):
+    """Write the chosen workflows into <theme>/.github/workflows.
+
+    Returns (written, skipped) lists of paths relative to the theme. Existing
+    files are never overwritten unless force is set -- a repo's workflows may
+    carry local edits, and clobbering them silently would be worse than making
+    someone pass --force.
+    """
+    version = version or f"v{__version__}"
+    alt = variant_alternation(variant_slugs)
+    repo_url = detect_repo_url(theme)
+
+    wanted = list(PREVIEW_FILES)
+    if watch:
+        wanted.append(WATCH_FILE)
+    if showcase:
+        wanted.append(SHOWCASE_FILE)
+
+    outdir = theme / ".github" / "workflows"
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    written, skipped = [], []
+    for name in wanted:
+        target = outdir / name
+        rel = target.relative_to(theme)
+        if target.exists() and not force:
+            skipped.append(rel)
+            continue
+        target.write_text(render_template(_template(name), version, alt, repo_url),
+                          encoding="utf-8")
+        written.append(rel)
+    return written, skipped
+
+
+BADGE = ("[![theme previews by fxcss]"
+         "(https://img.shields.io/badge/theme%20previews-fxcss-ff7139)]"
+         "(https://github.com/AdamXweb/fxcss)")
+
+
+def next_steps(written, skipped, variant_slugs, watch, showcase):
+    """Human instructions for what was generated. Returned, not printed, so it
+    is unit-testable and the CLI owns all output."""
+    lines = []
+    if written:
+        lines.append("Wrote:")
+        lines += [f"  {p}" for p in written]
+    if skipped:
+        lines.append("Left alone (already exist; rerun with --force to replace):")
+        lines += [f"  {p}" for p in skipped]
+    if variant_slugs:
+        lines.append("")
+        lines.append(f"Publish allowlist covers {len(variant_slugs)} variant "
+                     f"stylesheet(s): {', '.join(sorted(variant_slugs))}.")
+        lines.append("Adding a variant later? Re-run `fxcss init --force`, or add it "
+                     "to the NAME regex by hand.")
+    lines += [
+        "",
+        "Worth knowing before the first pull request:",
+        "  - The preview comment only starts appearing once these files are on",
+        "    your default branch: workflow_run always uses the default-branch copy.",
+        "  - A first-time contributor's run waits for your 'Approve and run",
+        "    workflows' click. That is GitHub policy, not a misconfiguration.",
+        "  - Images are published to an orphan ci-previews branch and cleaned up",
+        "    when each pull request closes.",
+    ]
+    if watch:
+        lines.append("  - firefox-watch runs Mondays and needs no further setup.")
+    if showcase:
+        lines.append("  - showcase publishes to a `showcase` branch on each release.")
+    lines += [
+        "",
+        "If you would like to say so in your README:",
+        f"  {BADGE}",
+    ]
+    return "\n".join(lines)

fxcss-0.8.0/fxcss/templates/firefox-watch.yml

@@ -0,0 +1,180 @@
+name: Firefox watch
+
+# Firefox ships every few weeks and quietly renames parts of its UI. A theme
+# does not break loudly when that happens -- the rule simply stops matching and
+# that piece of styling disappears, with nothing logged anywhere.
+#
+# This runs fxcss audit against each Firefox channel on a schedule. Beta and
+# Nightly are the point of the exercise: they show what is coming weeks before
+# it reaches the people using the theme.
+#
+# When there are confident fixes it opens a pull request with them. When there
+# are findings it cannot fix for you, it opens (or updates) one issue per
+# channel instead, and closes it again once the channel comes back clean.
+
+on:
+  schedule:
+    # Mondays, 06:20 UTC. Off the hour because scheduled jobs bunch there.
+    - cron: '20 6 * * 1'
+  workflow_dispatch:
+    inputs:
+      channel:
+        description: 'Single channel to check (blank = all)'
+        required: false
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+env:
+  FXCSS_VERSION: __FXCSS_VERSION__
+
+jobs:
+  check:
+    name: ${{ matrix.channel }}
+    runs-on: macos-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        channel: [release, beta, nightly]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install fxcss
+        run: >-
+          python -m pip install --disable-pip-version-check
+          "fxcss[images] @ git+https://github.com/AdamXweb/fxcss@${{ env.FXCSS_VERSION }}"
+
+      - name: Install Firefox (${{ matrix.channel }})
+        if: ${{ github.event.inputs.channel == '' || github.event.inputs.channel == matrix.channel }}
+        run: |
+          set -euo pipefail
+          case "${{ matrix.channel }}" in
+            release) product=firefox-latest-ssl ;;
+            beta)    product=firefox-beta-latest-ssl ;;
+            nightly) product=firefox-nightly-latest-ssl ;;
+            esr)     product=firefox-esr-latest-ssl ;;
+            *) echo "unknown channel"; exit 1 ;;
+          esac
+          curl -sSL -o firefox.dmg \
+            "https://download.mozilla.org/?product=${product}&os=osx&lang=en-US"
+          hdiutil attach -nobrowse -quiet -mountpoint /Volumes/ffwatch firefox.dmg
+          cp -R /Volumes/ffwatch/*.app "$RUNNER_TEMP/Firefox.app"
+          hdiutil detach /Volumes/ffwatch -quiet
+          echo "FIREFOX_BIN=$RUNNER_TEMP/Firefox.app/Contents/MacOS/firefox" >> "$GITHUB_ENV"
+
+      - name: Audit
+        id: audit
+        if: ${{ github.event.inputs.channel == '' || github.event.inputs.channel == matrix.channel }}
+        run: |
+          set +e
+          # Note the redirect rather than a pipe into tee: after a pipeline $?
+          # is tee's status, which is always 0, so findings would never be seen.
+          fxcss audit --no-colour --no-unused --strict --patch fxcss-fix.patch > audit.txt 2>&1
+          status=$?
+          cat audit.txt
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+          version=$(fxcss doctor 2>/dev/null \
+            | sed -n 's/^version: *\([0-9][^ ]*\).*/\1/p' | head -1)
+          echo "version=${version:-unknown}" >> "$GITHUB_OUTPUT"
+          if [ -s fxcss-fix.patch ]; then echo "patch=yes" >> "$GITHUB_OUTPUT"; fi
+
+      - name: Open a pull request with the confident fixes
+        if: steps.audit.outputs.status != '0' && steps.audit.outputs.patch == 'yes'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ matrix.channel }}
+          VERSION: ${{ steps.audit.outputs.version }}
+        run: |
+          set -euo pipefail
+          branch="fxcss/firefox-${CHANNEL}-${VERSION}"
+          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+            echo "branch $branch already exists; nothing new to open"
+            exit 0
+          fi
+          git config user.name  'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git checkout -b "$branch"
+          git apply fxcss-fix.patch
+          git add -A ':!audit.txt' ':!fxcss-fix.patch'
+          git commit -m "fix(css): update selectors renamed in Firefox ${VERSION}"
+          git push origin "$branch"
+          {
+            echo "Firefox **${CHANNEL}** is now **${VERSION}**, and some selectors this"
+            echo "theme uses no longer match anything in it."
+            echo
+            echo "The changes here are the ones fxcss is certain about — a name that moved"
+            echo "between an id and a class. Anything it was less sure of is listed below"
+            echo "but **not** changed."
+            echo
+            echo '```'
+            cat audit.txt
+            echo '```'
+            echo
+            echo "Worth previewing before merging: the PR preview workflow will render"
+            echo "before and after on this pull request."
+          } > body.md
+          gh pr create --base "${GITHUB_REF_NAME}" --head "$branch" \
+            --title "Firefox ${CHANNEL} ${VERSION}: update renamed selectors" \
+            --body-file body.md
+
+      - name: Open or update the heads-up issue
+        if: steps.audit.outputs.status != '0' && steps.audit.outputs.patch != 'yes'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ matrix.channel }}
+          VERSION: ${{ steps.audit.outputs.version }}
+        run: |
+          set -euo pipefail
+          title="Firefox ${CHANNEL}: selectors need attention"
+          {
+            echo "Firefox **${CHANNEL}** is now **${VERSION}**. Some selectors this theme"
+            echo "uses no longer match anything, and fxcss was not confident enough to"
+            echo "propose a replacement automatically."
+            echo
+            echo '```'
+            cat audit.txt
+            echo '```'
+            echo
+            echo "_Updated automatically. This closes itself when the channel is clean._"
+          } > 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 body.md
+          else
+            gh issue create --title "$title" --body-file body.md
+          fi
+
+      - name: Close the issue if this channel is clean again
+        if: steps.audit.outputs.status == '0'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ matrix.channel }}
+        run: |
+          set -euo pipefail
+          title="Firefox ${CHANNEL}: selectors need attention"
+          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} audits clean again — closing."
+          fi
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: audit-${{ matrix.channel }}
+          path: |
+            audit.txt
+            fxcss-fix.patch
+          if-no-files-found: ignore
+          retention-days: 30