monocoat 1.2.0__py3-none-any.whl

monocoat/__init__.py

@@ -0,0 +1,9 @@
+"""monocoat — one TOML, every Linux theming surface.
+
+One config drives every visual layer (GTK 2/3/4, settings broadcast, window
+manager, Qt/Kvantum, notifications, cursor, fonts, palette, terminals,
+wallpaper, panel, launcher, dock, remote overlay). The TOML is canon; every
+layer is re-derived from it, idempotently, with drift detection.
+"""
+
+__version__ = "1.2.0"

monocoat/__main__.py

@@ -0,0 +1,4 @@
+from monocoat.cli import main
+
+if __name__ == "__main__":
+    main()

monocoat/acceptance/__init__.py

@@ -0,0 +1,21 @@
+"""Acceptance tools — opt-in, isolated from the live desktop.
+
+`python -m monocoat.acceptance` runs the preset-switch acceptance test (see
+docs/acceptance/preset-switch.md): it builds a throwaway world (temp HOME,
+every XDG dir, a private Xvfb + D-Bus session inside a fresh PID namespace),
+switches that world to a generated preset, starts the themed surfaces, and
+classifies screenshots for pixels still holding the old preset's colours.
+
+Nothing in this package touches the live session: the runner refuses to start
+unless HOME/XDG_*/DISPLAY/DBUS_SESSION_BUS_ADDRESS already point into the temp
+world, and re-executes itself under `bwrap --unshare-pid` before anything
+starts. It is never imported by the monocoat CLI; it is run as its own tool.
+
+The pure pieces (palettes, known_failures, safety) have unit tests in
+tests/test_acceptance_*.py; the world/session/screenshot machinery is exercised
+by the opt-in run only.
+"""
+
+from __future__ import annotations
+
+__all__ = ["palettes", "known_failures", "safety"]

monocoat/acceptance/__main__.py

@@ -0,0 +1,51 @@
+"""python -m monocoat.acceptance — the preset-switch acceptance test entry.
+
+The tool re-executes itself twice (see preset_switch.py):
+  plain                  build the world, then re-exec under bwrap
+  --run WORLD            inside bwrap: safety gates + dbus-run-session
+  --runner WORLD         inside dbus-run-session: the actual run
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from monocoat import exit_codes as rc
+from monocoat.acceptance import preset_switch
+from monocoat.acceptance.shots import ShotError
+
+_MODE_FLAGS = ("--run", "--runner")
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    for flag in _MODE_FLAGS:
+        if flag in argv:
+            idx = argv.index(flag)
+            if idx + 1 >= len(argv):
+                print(f"{flag} needs the world path argument", file=sys.stderr)
+                return rc.USAGE
+            world = Path(argv[idx + 1])
+            rest = [a for a in argv if a != flag and a != str(world)]
+            args = preset_switch.parse_args(rest)
+            # A setup error anywhere inside the inner modes (missing
+            # Xvfb/xauth, a bad --image, an unreadable known-failures
+            # file, a failed capture, a missing dbus-run-session) must be
+            # the documented exit-3 refusal, never a traceback: exit 1 is
+            # reserved for unexpected FAILs, so a scripted --json consumer
+            # could not tell a refusal from a real failure run. The
+            # runner's own finally already terminated the daemons during
+            # unwinding; the bwrap/dbus wrappers reap the rest.
+            try:
+                if flag == "--run":
+                    return preset_switch._run_mode(world, args)
+                return preset_switch._runner(world, args)
+            except (preset_switch.WorldError, ShotError, ValueError, OSError) as e:
+                print(f"preset-switch: {e}", file=sys.stderr)
+                return rc.CONFIG_ERROR
+    return preset_switch.main(argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

monocoat/acceptance/gtk3_review.py

@@ -0,0 +1,204 @@
+"""Opt-in old/new Settings pixel review, inside the certified switch world.
+
+Uses the shipped Settings screenshot driver with its fake engine: no UI
+operation can apply a look. Only this runner's isolated CLI writes the world.
+The capability is added to COPIED manifests, never to the owner's bundle.
+"""
+from __future__ import annotations
+
+import json
+import re
+import runpy
+import subprocess
+import sys
+import tomllib
+
+from monocoat import exit_codes as rc
+from monocoat.acceptance import preset_switch as ps
+from monocoat.acceptance.surfaces import GTK3_APP, load_preset_cfg
+from monocoat.acceptance.world import WorldError
+
+
+def run(world, display, out, generated):
+    from tests import _apps_world, _theme_world
+
+    folder = out / "gtk3-review"
+    folder.mkdir()
+    apps = _apps_world.mockup_world(_apps_world.make_apps_world(world.root / "review-apps"))
+    roots_file = world.root / "review-apps.json"
+    roots_file.write_text(_apps_world.roots_json(apps.roots))
+    icons = world.root / "review-icons"
+    _theme_world.build(icons)
+    driver = runpy.run_path(str(ps.REPO / "scripts/settings-screenshots.py"))["CHILD"]
+    steps = [("fonts", "win.show_page('fonts')", 900)]
+    env = world.env(display) | {"PYTHONPATH": str(ps.REPO / "src") + ":" + str(ps.REPO),
+                                "MONOCOAT_SHOTS_APPS_ROOTS": str(roots_file),
+                                "MONOCOAT_SHOTS_ICON_ROOTS": str(icons), "NO_AT_BRIDGE": "1"}
+    results = []
+    raw = tomllib.loads((world.config_home / "monocoat/monocoat.toml").read_text())
+    base = ((raw.get("meta") or {}).get("generated") or {}).get("base", "adaptive")
+    for name in (base, generated):
+        code, output, error = ps._monocoat(world, display, "set", name, "--json")
+        if code not in (rc.OK, rc.PARTIAL):
+            raise WorldError(f"GTK3 review could not set {name}: {error or output}")
+        # Resolve through the same child config path as all acceptance surfaces.
+        preset = world.config_home / "monocoat/presets" / f"{name}.toml"
+        cfg = load_preset_cfg(preset)
+        # Generated bundles use the default path; Adaptive can carry assets_dir.
+        from monocoat.paths import expand
+        assets = expand((cfg.get("paths") or {}).get("assets_dir")
+                        or str(world.data_home / "monocoat/themes" / name))
+        manifest = assets / "monocoat-bindings.toml"
+        shots = []
+        for mode in ("before", "after"):
+            if mode == "after":
+                text = manifest.read_text()
+                data = tomllib.loads(text)
+                capabilities = sorted(set(data.get("capabilities", [])) | {"gtk3-theme-palette"})
+                line = "capabilities = " + json.dumps(capabilities)
+                if "capabilities" in data:
+                    text = re.sub(r"(?ms)^capabilities\s*=\s*\[.*?\]", line, text, count=1)
+                else:
+                    text = line + "\n" + text
+                manifest.write_text(text)
+                code, output, error = ps._monocoat(world, display, "apply", "--json")
+                if code not in (rc.OK, rc.PARTIAL):
+                    raise WorldError(f"GTK3 review apply failed: {error or output}")
+                from monocoat.gtk3theme import STABLE_MARKER
+                if STABLE_MARKER not in (world.config_home / "gtk-3.0/gtk.css").read_text():
+                    raise WorldError(f"GTK3 review did not migrate {name}: {output}")
+            prefix = f"{name}-{mode}"
+            proc = subprocess.run([sys.executable, "-c", driver.replace("%STEPS%", repr(steps)),
+                                   str(folder), prefix], env=env, capture_output=True,
+                                  text=True, timeout=45)
+            (folder / f"{prefix}.log").write_text(proc.stdout + proc.stderr)
+            image = folder / f"{prefix}-fonts.png"
+            if proc.returncode or not image.is_file():
+                raise WorldError(f"GTK3 review screenshot failed: {proc.stderr[-1000:]}")
+            shots.append(image)
+            # Settings has its own provider; sample ordinary GTK3 widgets too.
+            widget = folder / f"{prefix}-widgets.png"
+            save = """
+def save():
+    import sys
+    pixbuf = Gdk.pixbuf_get_from_window(w.get_window(), 0, 0, 680, 400)
+    pixbuf.savev(sys.argv[1], 'png', [], [])
+    Gtk.main_quit()
+    return False
+"""
+            code = GTK3_APP.replace("GLib.timeout_add(1500, pop)",
+                                    save + "\nGLib.timeout_add(900, save)")
+            proc = subprocess.run([sys.executable, "-c", code, str(widget)], env=env,
+                                  capture_output=True, text=True, timeout=15)
+            if proc.returncode or not widget.exists():
+                raise WorldError(f"GTK3 widget capture failed: {proc.stderr}")
+        for surface, pair_shots in (("settings", shots),
+                                    ("widgets", [folder / f"{name}-{mode}-widgets.png"
+                                                 for mode in ("before", "after")])):
+            diff = folder / f"{name}-{surface}-difference.png"
+            pair = folder / f"{name}-{surface}-comparison.png"
+            for argv in (("magick", *map(str, pair_shots), "-compose", "difference", "-composite", str(diff)),
+                         ("magick", *map(str, pair_shots), "+append", str(pair))):
+                subprocess.run(argv, env=env, check=True, capture_output=True)
+            metric = subprocess.run(["magick", "compare", "-metric", "AE", *map(str, pair_shots),
+                                     "null:"], env=env, capture_output=True, text=True)
+            if metric.returncode not in (0, 1):
+                raise WorldError(f"GTK3 pixel comparison failed: {metric.stderr}")
+            results.append({"preset": name, "surface": surface, "before": str(pair_shots[0]), "after": str(pair_shots[1]),
+                            "comparison": str(pair), "difference": str(diff),
+                            "changed_pixels": metric.stderr.strip()})
+    (folder / "review.json").write_text(json.dumps(results, indent=2) + "\n")
+    live_apps(world, display, folder, base, generated)
+    return results
+
+
+def live_apps(world, display, folder, base, generated):
+    """A settled switch with GTK3 and Thunar ALREADY RUNNING, no new apps."""
+    import dataclasses
+    import shutil
+    import time
+
+    from monocoat.acceptance import palettes, shots
+
+    ps._monocoat(world, display, "set", base)
+    env = world.env(display) | {"NO_AT_BRIDGE": "1", "GIO_USE_VFS": "local"}
+    state_path = world.root / "gtk3-live-state.json"
+    state_code = '''
+def record_named():
+    import json, os
+    from pathlib import Path
+    colors = {}
+    for name in ('theme_bg_color', 'theme_selected_bg_color'):
+        found, rgba = w.get_style_context().lookup_color(name)
+        colors[name] = ('#%02x%02x%02x' % tuple(round(c * 255) for c in
+                        (rgba.red, rgba.green, rgba.blue))) if found else None
+    target = Path(os.environ['MC_GTK_STATE'])
+    temp = target.with_suffix('.tmp')
+    temp.write_text(json.dumps(colors))
+    os.replace(temp, target)
+    return True
+GLib.timeout_add(100, record_named)
+'''
+    code = GTK3_APP.replace("GLib.timeout_add(1500, pop)", state_code)
+    env["MC_GTK_STATE"] = str(state_path)
+    procs = []
+    rows = []
+    try:
+        procs.append(subprocess.Popen([sys.executable, "-c", code], env=env,
+                                      stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL))
+        windows = {"gtk3": shots.wait_window(env, "--name", "^mc-psw gtk3$")}
+        if shutil.which("thunar"):
+            child = subprocess.Popen(["thunar", "--window", str(world.home)], env=env,
+                                      stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            procs.append(child)
+            windows["thunar"] = shots.wait_window(env, "--class", "Thunar")
+        time.sleep(.8)
+        old = palettes.palette_tokens((world.config_home / "monocoat/presets" / f"{base}.toml").read_text())
+        new = palettes.palette_tokens((world.config_home / "monocoat/presets" / f"{generated}.toml").read_text())
+        before = {}
+        for label, wid in windows.items():
+            if not wid:
+                raise WorldError(f"live GTK3 review missing {label} window")
+            png = folder / f"live-{label}-before.png"
+            subprocess.run(["import", "-window", wid, str(png)], env=env, check=True,
+                           capture_output=True)
+            before[label] = dataclasses.asdict(palettes.analyze(
+                palettes.parse_histogram(shots.histogram(env, png)), old, new))
+        named_before = json.loads(state_path.read_text())
+        pids = {label: shots.run(env, "xprop", "-id", wid, "_NET_WM_PID")
+                for label, wid in windows.items()}
+        started = time.perf_counter()
+        code, output, error = ps._monocoat(world, display, "set", generated, "--json")
+        cost = (time.perf_counter() - started) * 1000
+        if code not in (rc.OK, rc.PARTIAL):
+            raise WorldError(f"live GTK3 switch failed: {error or output}")
+        time.sleep(.8)
+        named_after = json.loads(state_path.read_text())
+        if named_after['theme_selected_bg_color'] != new['accent'].lower():
+            raise WorldError(f"running GTK3 app kept stale named colours: {named_after}")
+        for label, wid in windows.items():
+            png = folder / f"live-{label}-after.png"
+            subprocess.run(["import", "-window", wid, str(png)], env=env, check=True,
+                           capture_output=True)
+            pid_after = shots.run(env, "xprop", "-id", wid, "_NET_WM_PID")
+            if not re.search(r"= [0-9]+", pids[label]) or pid_after != pids[label]:
+                raise WorldError(f"running {label} PID changed during switch")
+            after = palettes.analyze(palettes.parse_histogram(shots.histogram(env, png)), old, new)
+            rows.append({"app": label, "pid_property": pid_after.strip(), "switch_ms": cost,
+                         "before": before[label], "after": dataclasses.asdict(after),
+                         "recoloured": ((named_before != named_after) if label == "gtk3" else
+                                        before[label]['stale'] > 0 and not palettes.failed(after)),
+                         "verification": "named colours" if label == "gtk3" else "pixel classifier"})
+        payload = {"apps": rows, "named_before": named_before, "named_after": named_after,
+                   "apply": json.loads(output)}
+        (folder / "live-apps.json").write_text(json.dumps(payload, indent=2) + "\n")
+        return payload
+    finally:
+        for child in reversed(procs):
+            if child.poll() is None:
+                child.terminate()
+                try:
+                    child.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    child.kill()
+                    child.wait(timeout=5)

monocoat/acceptance/known_failures.py

@@ -0,0 +1,81 @@
+"""Expected-failures bookkeeping for the preset-switch acceptance test.
+
+The owner maintains docs/acceptance/preset-switch-known.toml listing the
+surfaces KNOWN to keep old-preset colours until in-flight work lands (user
+gtk.css ownership, raster recolor). A failed surface that matches an entry
+prints as XFAIL and does not fail the run; an unexpected FAIL, or an
+unexpected PASS of an XFAIL entry (the gap healed but the file still lists
+it), is reported loudly. The run exits 0 only when there are no unexpected
+failures.
+
+Format:
+
+    version = 1
+
+    [[expected-failures]]
+    surface = "gtk3-*"          # fnmatch pattern against the surface name
+    reason = "user gtk.css hard-codes the old palette hexes (ownership in flight)"
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Entry:
+    surface: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class KnownFailures:
+    entries: tuple[Entry, ...] = ()
+
+    def match(self, name: str) -> Entry | None:
+        for entry in self.entries:
+            if fnmatch.fnmatchcase(name, entry.surface):
+                return entry
+        return None
+
+
+def load(path: Path | str) -> KnownFailures:
+    """Read the known-failures TOML. A missing file is an empty list (nothing
+    is known to fail); an unreadable or malformed one raises ValueError with
+    the file name — a broken expectation file must fail the run loudly."""
+    p = Path(path)
+    if not p.exists():
+        return KnownFailures()
+    try:
+        raw = tomllib.loads(p.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as e:
+        raise ValueError(f"{p}: cannot read expected-failures file: {e}") from e
+    entries = []
+    for item in raw.get("expected-failures", []):
+        if not isinstance(item, dict) or not item.get("surface"):
+            raise ValueError(f"{p}: expected-failures entry without a surface")
+        entries.append(Entry(str(item["surface"]), str(item.get("reason", ""))))
+    return KnownFailures(tuple(entries))
+
+
+def verdict(status: str, entry: Entry | None) -> str:
+    """Turn a raw surface status into its reported verdict.
+
+    FAIL + known entry → XFAIL; PASS + known entry → XPASS (reported loudly:
+    the entry should be removed); anything else passes through."""
+    if entry is None:
+        return status
+    if status == "FAIL":
+        return "XFAIL"
+    if status == "PASS":
+        return "XPASS"
+    return status
+
+
+def exit_code(verdicts: list[str]) -> int:
+    """0 when nothing failed unexpectedly, 1 otherwise (XPASS is loud but not
+    an unexpected failure — see the module docstring)."""
+    return 1 if "FAIL" in verdicts else 0

monocoat/acceptance/palettes.py

@@ -0,0 +1,154 @@
+"""Pure pixel classification for the preset-switch acceptance test.
+
+A screenshot is reduced to a weighted color histogram (by the runner, via
+ImageMagick); this module decides which pixels "stayed on the old preset".
+The rule (owner-specified):
+
+    a pixel is STALE when its OKLab distance to the nearest OLD palette token
+    is <= 0.04, its distance to the nearest NEW token is > 0.08, and it is
+    not near-neutral (OKLCH chroma > 0.03 — eggshell, greys and black don't
+    count). A surface FAILS when stale pixels exceed a small share of its
+    area (default 0.5%) or 50 pixels.
+
+No I/O, no subprocess; the OKLab math lives in surfaces.palettemath (pure).
+The histogram text format is ImageMagick's `%c histogram:info:-`:
+
+      1234: ( 23, 45, 67) #172D43 srgb(23,45,67)
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+
+from monocoat.surfaces.palettemath import delta_e, parse_hex, to_oklch
+
+RGB = tuple[int, int, int]
+
+# Classification thresholds (owner-specified; see module docstring).
+STALE_DELTA_OLD = 0.04
+STALE_DELTA_NEW = 0.08
+NEUTRAL_CHROMA = 0.03
+# Failure thresholds: share of the surface area / absolute pixel count.
+FAIL_SHARE = 0.005
+FAIL_PIXELS = 50
+
+_HIST_LINE = re.compile(r"^\s*(\d+):\s*\([^)]*\)\s*(#[0-9A-Fa-f]{6})\b", re.M)
+
+
+def palette_tokens(preset_text: str) -> dict[str, str]:
+    """The `[palette]` hex tokens of a preset TOML file, {token: "#RRGGBB"}.
+
+    Raises ValueError for invalid TOML; a missing [palette] table (or missing
+    file content) yields {}. Non-hex values are skipped — they cannot match a
+    screenshot pixel."""
+    raw = tomllib.loads(preset_text)
+    pal = raw.get("palette")
+    if not isinstance(pal, dict):
+        return {}
+    return {k: v for k, v in pal.items() if isinstance(v, str) and _is_hex(v)}
+
+
+def _is_hex(value: str) -> bool:
+    try:
+        parse_hex(value)
+    except ValueError:
+        return False
+    return True
+
+
+def parse_histogram(text: str) -> list[tuple[RGB, int]]:
+    """Parse ImageMagick `%c histogram:info:-` output into [(rgb, count), ...].
+
+    Unparseable lines are skipped; the counts are the caller's pixel weights."""
+    out: list[tuple[RGB, int]] = []
+    for count, hexv in _HIST_LINE.findall(text):
+        try:
+            out.append((parse_hex(hexv), int(count)))
+        except ValueError:
+            continue
+    return out
+
+
+def nearest(pixel: RGB, tokens: dict[str, str]) -> tuple[float, str]:
+    """(distance, token name) of the nearest token in OKLab, or (inf, "")."""
+    if not tokens:
+        return float("inf"), ""
+    best, name = float("inf"), ""
+    for token, value in tokens.items():
+        d = delta_e(value, _to_hex(pixel))
+        if d < best:
+            best, name = d, token
+    return best, name
+
+
+def _to_hex(pixel: RGB) -> str:
+    return f"#{pixel[0]:02x}{pixel[1]:02x}{pixel[2]:02x}"
+
+
+def is_stale(pixel: RGB, old: dict[str, str], new: dict[str, str], *,
+             old_delta: float = STALE_DELTA_OLD,
+             new_delta: float = STALE_DELTA_NEW,
+             neutral_chroma: float = NEUTRAL_CHROMA) -> bool:
+    """The single-pixel rule: close to an old token, far from every new one,
+    and colourful enough that greys/eggshell/black are not counted."""
+    d_old, _ = nearest(pixel, old)
+    if d_old > old_delta:
+        return False
+    d_new, _ = nearest(pixel, new)
+    if d_new <= new_delta:
+        return False
+    _, chroma, _ = to_oklch(_to_hex(pixel))
+    return chroma > neutral_chroma
+
+
+@dataclass(frozen=True)
+class StaleAnalysis:
+    """The stale-pixel verdict for one surface region."""
+
+    total: int                 # pixels classified (sum of histogram counts)
+    stale: int                 # stale pixels
+    share: float               # stale / total (0.0 when total == 0)
+    dominant: str | None       # the most common stale colour, "#rrggbb"
+    matched_token: str | None  # the old token that colour is nearest to
+
+
+def analyze(histogram: list[tuple[RGB, int]], old: dict[str, str],
+            new: dict[str, str], **thresholds) -> StaleAnalysis:
+    """Classify a weighted histogram against the old and new palettes.
+
+    `thresholds` forwards to is_stale (old_delta/new_delta/neutral_chroma)."""
+    total = sum(count for _, count in histogram)
+    stale_px = 0
+    dominant: tuple[int, str, str] | None = None   # (count, hex, token)
+    for pixel, count in histogram:
+        if not is_stale(pixel, old, new, **thresholds):
+            continue
+        stale_px += count
+        d, token = nearest(pixel, old)
+        if dominant is None or count > dominant[0]:
+            dominant = (count, _to_hex(pixel), token)
+    share = stale_px / total if total else 0.0
+    if dominant is None:
+        return StaleAnalysis(total, 0, share, None, None)
+    _, hexv, token = dominant
+    return StaleAnalysis(total, stale_px, share, hexv, token)
+
+
+def failed(analysis: StaleAnalysis, *, fail_share: float = FAIL_SHARE,
+           fail_pixels: int = FAIL_PIXELS) -> bool:
+    """Whether a StaleAnalysis counts as a surface failure."""
+    return (analysis.total > 0
+            and (analysis.share > fail_share or analysis.stale > fail_pixels))
+
+
+def has_chroma(histogram: list[tuple[RGB, int]],
+               *, limit: float = NEUTRAL_CHROMA) -> bool:
+    """Whether any histogram colour is colourful (OKLCH chroma > limit).
+
+    A crop of a blank root is all-neutral: the desktop-backdrop surface
+    must SKIP it (the renderer drew nothing) rather than PASS it — the
+    same false-PASS class the menu probes exist to prevent."""
+    return any(to_oklch(_to_hex(pixel))[1] > limit
+               for pixel, count in histogram if count > 0)