fxcss 0.7.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxcss
-Version: 0.7.0
+Version: 0.9.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,8 @@ 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 |
+| [`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 |
@@ -171,6 +181,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 +245,55 @@ 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 tweaks
+
+```bash
+fxcss tweaks
+fxcss tweaks --combo compact-tabs+tabs-swapclose
+```
+
+**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.
+
+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.
+
+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.
+
 ### fxcss audit
 
 ```bash
@@ -480,11 +541,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.9.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,8 @@ 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 |
+| [`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 |
@@ -150,6 +160,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 +224,55 @@ 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 tweaks
+
+```bash
+fxcss tweaks
+fxcss tweaks --combo compact-tabs+tabs-swapclose
+```
+
+**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.
+
+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.
+
+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.
+
 ### fxcss audit
 
 ```bash
@@ -459,11 +520,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.9.0}/fxcss/__init__.py

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

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

@@ -2,6 +2,8 @@
 """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 tweaks       screenshot every install option, into a committable doc
     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 +28,23 @@ 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 tweaks                   screenshot every install option for your README
+    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 +178,54 @@ def cmd_try(args):
         shutil.rmtree(workdir, ignore_errors=True)
 
 
+def cmd_tweaks(args):
+    from . import tweaks
+    theme = args.theme.resolve()
+    if not (theme / "chrome" / "userChrome.css").exists():
+        print(f"error: no chrome/userChrome.css under {theme}", file=sys.stderr)
+        return 2
+    available = core.find_variant_sheets(theme)
+    if not available:
+        print("This theme ships no optional stylesheets (looked in custom/, "
+              "optional/, options/, extras/, variants/), so there is nothing "
+              "to document.", file=sys.stderr)
+        return 2
+    variants = {slug: [path] for slug, path in available.items()}
+    for combo in args.combo or []:
+        try:
+            variants.update(core.parse_variant_spec(combo, available))
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+
+    firefox = core.find_firefox(args.firefox)
+    out = args.out.resolve()
+    print(f"fxcss tweaks\n  theme: {theme}\n  out:   {out}\n")
+    with core.Session(theme, firefox, dark=args.dark) as session:
+        entries = tweaks.build(session, theme, out, variants, tweaks.readme_flags(theme))
+    stale = [e["slug"] for e in entries if not e["image"]]
+    print(f"\n  wrote {out / 'TWEAKS.md'} with {len(entries)} option(s)")
+    if stale:
+        print(f"  note: {', '.join(stale)} changed nothing — possibly stale, "
+              f"worth a look")
+    print("  Commit the folder and link TWEAKS.md from your README.")
+    return 0
+
+
+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)
@@ -361,21 +428,13 @@ def cmd_shot(args):
     variants = {}
     spec = getattr(args, "variants", None)
     if spec:
-        available = core.find_variant_sheets(theme)
-        if spec.strip().lower() == "all":
-            variants = available
-            if not variants:
-                print("  note: --variants all found no optional stylesheets",
-                      flush=True)
-        else:
-            wanted = [w.strip().lower() for w in spec.split(",") if w.strip()]
-            missing = [w for w in wanted if w not in available]
-            if missing:
-                print("error: no optional stylesheet named "
-                      + ", ".join(missing) + "; available: "
-                      + (", ".join(sorted(available)) or "none"), file=sys.stderr)
-                return 2
-            variants = {w: available[w] for w in wanted}
+        try:
+            variants = core.parse_variant_spec(spec, core.find_variant_sheets(theme))
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        if not variants:
+            print("  note: --variants all found no optional stylesheets", flush=True)
 
     firefox = core.find_firefox(args.firefox)
     with core.Session(theme, firefox) as session:
@@ -442,6 +501,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 +529,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 +553,31 @@ def main(argv=None):
         _menus(tr)
         tr.set_defaults(func=cmd_try)
 
+    tw = sub.add_parser("tweaks",
+                        help="screenshot every install option into a committable doc")
+    tw.add_argument("--theme", type=Path, default=Path.cwd(),
+                    help="theme root, the folder containing chrome/ (default: cwd)")
+    tw.add_argument("--firefox", default=None,
+                    help="path to the firefox binary (default: autodetect)")
+    tw.add_argument("--out", type=Path, default=Path("docs/tweaks"),
+                    help="output folder (default: docs/tweaks)")
+    tw.add_argument("--combo", action="append", metavar="NAME+NAME",
+                    help="also render options together, e.g. --combo "
+                         "compact-tabs+tabs-swapclose; repeatable")
+    tw.add_argument("--dark", action="store_true", help="render in dark mode")
+    tw.set_defaults(func=cmd_tweaks)
+
+    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 +663,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.9.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.7.0 → fxcss-0.9.0}/fxcss/core.py

@@ -634,21 +634,19 @@ return true;
 LOAD_VARIANT_SHEET = """
 const win = Services.wm.getMostRecentWindow("navigator:browser");
 const u = win.windowUtils;
-if (win._fxcssVariantSheet) {
-  try { u.removeSheetUsingURIString(win._fxcssVariantSheet, u.USER_SHEET); } catch (e) {}
-}
+if (!win._fxcssVariantSheets) { win._fxcssVariantSheets = []; }
 u.loadSheetUsingURIString(arguments[0], u.USER_SHEET);
-win._fxcssVariantSheet = arguments[0];
-return true;
+win._fxcssVariantSheets.push(arguments[0]);
+return win._fxcssVariantSheets.length;
 """
 
-UNLOAD_VARIANT_SHEET = """
+UNLOAD_VARIANT_SHEETS = """
 const win = Services.wm.getMostRecentWindow("navigator:browser");
 const u = win.windowUtils;
-if (win._fxcssVariantSheet) {
-  try { u.removeSheetUsingURIString(win._fxcssVariantSheet, u.USER_SHEET); } catch (e) {}
-  win._fxcssVariantSheet = null;
+for (const uri of (win._fxcssVariantSheets || [])) {
+  try { u.removeSheetUsingURIString(uri, u.USER_SHEET); } catch (e) {}
 }
+win._fxcssVariantSheets = [];
 return true;
 """
 
@@ -981,11 +979,14 @@ def capture_views(session: Session, outdir: Path, modes=("light", "dark"),
     # Optional stylesheets, one capture per variant. Loaded live as a user
     # sheet by file URI -- relative url()s inside the sheet keep resolving --
     # then removed, so variants never contaminate each other.
-    for slug, sheet in sorted((variants or {}).items()):
-        m.script(LOAD_VARIANT_SHEET, [sheet.resolve().as_uri()])
+    for slug, sheets in sorted((variants or {}).items()):
+        # A value may be one sheet or several: a combo loads them together, the
+        # way a user stacking install options would run them.
+        for sheet in ([sheets] if isinstance(sheets, Path) else sheets):
+            m.script(LOAD_VARIANT_SHEET, [sheet.resolve().as_uri()])
         time.sleep(1.5)
         _shot(m, outdir, "variant-" + slug)
-        m.script(UNLOAD_VARIANT_SHEET)
+        m.script(UNLOAD_VARIANT_SHEETS)
         time.sleep(0.8)
 
     (outdir / "render-info.json").write_text(json.dumps(info, indent=2), encoding="utf-8")
@@ -1069,6 +1070,39 @@ def find_variant_sheets(theme: Path):
     return sheets
 
 
+def parse_variant_spec(spec, available):
+    """Turn a --variants value into {slug: [sheet, ...]}.
+
+    Commas separate captures; a plus combines sheets within one capture, the
+    way a user stacking install options would run them:
+
+        all                     every optional sheet, one capture each
+        a,b                     two captures
+        a+b,c                   a and b together, then c alone
+
+    Raises ValueError naming anything unknown, listing what exists.
+    """
+    if not spec:
+        return {}
+    spec = spec.strip()
+    if spec.lower() == "all":
+        return {slug: [path] for slug, path in available.items()}
+    chosen = {}
+    unknown = []
+    for part in (p.strip().lower() for p in spec.split(",") if p.strip()):
+        names = [n.strip() for n in part.split("+") if n.strip()]
+        missing = [n for n in names if n not in available]
+        if missing:
+            unknown += missing
+            continue
+        chosen["+".join(names)] = [available[n] for n in names]
+    if unknown:
+        raise ValueError(
+            "no optional stylesheet named " + ", ".join(sorted(set(unknown)))
+            + "; available: " + (", ".join(sorted(available)) or "none"))
+    return chosen
+
+
 def find_firefox(explicit=None):
     """Locate a Firefox binary, preferring an explicit path.