@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/scripts/theme/extract-theme.py

@@ -1,1020 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Apache-2.0 OR MIT
-# Copyright (c) 2015-2026 Sebastien Rousseau
-# extract-theme.py — Generate a terminal theme from wallpaper dominant colors.
-#
-# Uses K-Means clustering in CIELAB color space for perceptually accurate
-# dominant color extraction. No external dependencies — stdlib only.
-# ImageMagick is used for image downsampling and pixel extraction.
-#
-# Usage:
-#   python3 extract-theme.py <image-path> [--name <theme-name>] [--format toml|json]
-#   python3 extract-theme.py /System/Library/Desktop\ Pictures/Sonoma.heic
-#   python3 extract-theme.py ~/Pictures/Wallpapers/macos-tahoe-dark.heic --name macos-tahoe-dark
-
-import sys
-import subprocess  # nosec B404 — used only with fixed magick command, no shell
-import math
-import random  # nosec B311 — used for K-Means seeding, not security
-import json
-import os
-from typing import List, Tuple, Dict
-
-# ---------------------------------------------------------------------------
-# Color space conversions (RGB ↔ XYZ ↔ CIELAB)
-# ---------------------------------------------------------------------------
-
-def srgb_to_linear(c: float) -> float:
-    """Linearize an sRGB component (0-1)."""
-    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
-
-
-def linear_to_srgb(c: float) -> float:
-    """Gamma-compress a linear component to sRGB (0-1)."""
-    c = max(0.0, min(1.0, c))
-    return 12.92 * c if c <= 0.0031308 else 1.055 * (c ** (1.0 / 2.4)) - 0.055
-
-
-def rgb_to_xyz(r: int, g: int, b: int) -> Tuple[float, float, float]:
-    """Convert sRGB (0-255) to CIE XYZ (D65 illuminant)."""
-    rl = srgb_to_linear(r / 255.0)
-    gl = srgb_to_linear(g / 255.0)
-    bl = srgb_to_linear(b / 255.0)
-    x = 0.4124564 * rl + 0.3575761 * gl + 0.1804375 * bl
-    y = 0.2126729 * rl + 0.7151522 * gl + 0.0721750 * bl
-    z = 0.0193339 * rl + 0.1191920 * gl + 0.9503041 * bl
-    return x, y, z
-
-
-def xyz_to_lab(x: float, y: float, z: float) -> Tuple[float, float, float]:
-    """Convert CIE XYZ to CIELAB (D65 reference white)."""
-    xn, yn, zn = 0.95047, 1.00000, 1.08883
-
-    def f(t):
-        return t ** (1.0 / 3.0) if t > 0.008856 else 7.787 * t + 16.0 / 116.0
-
-    fx, fy, fz = f(x / xn), f(y / yn), f(z / zn)
-    L = 116.0 * fy - 16.0
-    a = 500.0 * (fx - fy)
-    b = 200.0 * (fy - fz)
-    return L, a, b
-
-
-def lab_to_xyz(L: float, a: float, b: float) -> Tuple[float, float, float]:
-    """Convert CIELAB to CIE XYZ (D65 reference white)."""
-    xn, yn, zn = 0.95047, 1.00000, 1.08883
-    fy = (L + 16.0) / 116.0
-    fx = a / 500.0 + fy
-    fz = fy - b / 200.0
-
-    def inv_f(t):
-        return t ** 3 if t ** 3 > 0.008856 else (t - 16.0 / 116.0) / 7.787
-
-    return inv_f(fx) * xn, inv_f(fy) * yn, inv_f(fz) * zn
-
-
-def xyz_to_rgb(x: float, y: float, z: float) -> Tuple[int, int, int]:
-    """Convert CIE XYZ to sRGB (0-255)."""
-    rl = 3.2404542 * x - 1.5371385 * y - 0.4985314 * z
-    gl = -0.9692660 * x + 1.8760108 * y + 0.0415561 * z
-    bl = 0.0556434 * x - 0.2040259 * y + 1.0572252 * z
-    r = int(round(linear_to_srgb(rl) * 255))
-    g = int(round(linear_to_srgb(gl) * 255))
-    b = int(round(linear_to_srgb(bl) * 255))
-    return max(0, min(255, r)), max(0, min(255, g)), max(0, min(255, b))
-
-
-def rgb_to_lab(r: int, g: int, b: int) -> Tuple[float, float, float]:
-    return xyz_to_lab(*rgb_to_xyz(r, g, b))
-
-
-def lab_to_rgb(L: float, a: float, b: float) -> Tuple[int, int, int]:
-    return xyz_to_rgb(*lab_to_xyz(L, a, b))
-
-
-def rgb_to_hex(r: int, g: int, b: int) -> str:
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def hex_to_rgb(h: str) -> Tuple[int, int, int]:
-    h = h.lstrip("#")
-    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
-
-
-# ---------------------------------------------------------------------------
-# Perceptual utilities
-# ---------------------------------------------------------------------------
-
-def lab_distance(a: Tuple[float, ...], b: Tuple[float, ...]) -> float:
-    """Euclidean distance in CIELAB (ΔE*ab)."""
-    return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))
-
-
-def relative_luminance(r: int, g: int, b: int) -> float:
-    """WCAG relative luminance from sRGB."""
-    def ch(c):
-        s = c / 255.0
-        return s / 12.92 if s <= 0.03928 else ((s + 0.055) / 1.055) ** 2.4
-    return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b)
-
-
-def contrast_ratio(c1: Tuple[int, int, int], c2: Tuple[int, int, int]) -> float:
-    l1 = relative_luminance(*c1)
-    l2 = relative_luminance(*c2)
-    return (max(l1, l2) + 0.05) / (min(l1, l2) + 0.05)
-
-
-def lab_chroma(L: float, a: float, b: float) -> float:
-    """Chroma (saturation) in CIELAB."""
-    return math.sqrt(a * a + b * b)
-
-
-def lab_hue(L: float, a: float, b: float) -> float:
-    """Hue angle in CIELAB (0-360)."""
-    h = math.degrees(math.atan2(b, a))
-    return h if h >= 0 else h + 360.0
-
-
-# ---------------------------------------------------------------------------
-# K-Means clustering in CIELAB
-# ---------------------------------------------------------------------------
-
-def _kmeans_init(pixels, k, rng):
-    """Initialize k centroids using K-Means++ seeding."""
-    n = len(pixels)
-    centroids = [pixels[rng.randint(0, n - 1)]]
-    for _ in range(1, k):
-        dists = [min(lab_distance(p, c) ** 2 for c in centroids) for p in pixels]
-        total = sum(dists)
-        if total == 0:
-            centroids.append(pixels[rng.randint(0, n - 1)])
-            continue
-        r = rng.random() * total
-        cumulative = 0.0
-        for i, d in enumerate(dists):
-            cumulative += d
-            if cumulative >= r:
-                centroids.append(pixels[i])
-                break
-    return centroids
-
-
-def _assign_labels(pixels, centroids, labels):
-    """Assign each pixel to its nearest centroid. Returns number of changed labels."""
-    changed = 0
-    for i, p in enumerate(pixels):
-        best_j = 0
-        best_d = lab_distance(p, centroids[0])
-        for j in range(1, len(centroids)):
-            d = lab_distance(p, centroids[j])
-            if d < best_d:
-                best_d = d
-                best_j = j
-        if labels[i] != best_j:
-            changed += 1
-        labels[i] = best_j
-    return changed
-
-
-def _update_centroids(pixels, labels, centroids):
-    """Recompute centroids as the mean of assigned pixels."""
-    n = len(pixels)
-    for j, _ in enumerate(centroids):
-        members = [pixels[i] for i in range(n) if labels[i] == j]
-        if members:
-            centroids[j] = tuple(
-                sum(m[d] for m in members) / len(members) for d in range(3)
-            )
-
-
-def _kmeans_single_run(pixels, k, max_iter, rng):
-    """Run one K-Means iteration loop. Returns (centroids, labels, inertia)."""
-    centroids = _kmeans_init(pixels, k, rng)
-    labels = [0] * len(pixels)
-    for _ in range(max_iter):
-        changed = _assign_labels(pixels, centroids, labels)
-        if changed == 0:
-            break
-        _update_centroids(pixels, labels, centroids)
-    inertia = sum(
-        lab_distance(pixels[i], centroids[labels[i]]) ** 2 for i in range(len(pixels))
-    )
-    return centroids, labels, inertia
-
-
-def kmeans_lab(
-    pixels: List[Tuple[float, float, float]],
-    k: int = 8,
-    max_iter: int = 20,
-    runs: int = 3,
-) -> List[Tuple[Tuple[float, float, float], int]]:
-    """Run K-Means clustering in CIELAB space with best-of-N initialization."""
-    n = len(pixels)
-    if n == 0:
-        return []
-
-    best_centroids = None
-    best_labels = None
-    best_inertia = float("inf")
-
-    for run_idx in range(runs):
-        rng = random.Random(run_idx * 42 + 7)  # nosec B311
-        centroids, labels, inertia = _kmeans_single_run(pixels, k, max_iter, rng)
-        if inertia < best_inertia:
-            best_inertia = inertia
-            best_centroids = centroids[:]
-            best_labels = labels[:]
-
-    populations = [0] * k
-    for label in best_labels:
-        populations[label] += 1
-
-    result = [(best_centroids[j], populations[j]) for j in range(k)]
-    result.sort(key=lambda x: x[1], reverse=True)
-    return result
-
-
-# ---------------------------------------------------------------------------
-# Pixel extraction via ImageMagick
-# ---------------------------------------------------------------------------
-
-def extract_pixels(image_path: str, max_dim: int = 80) -> List[Tuple[int, int, int]]:
-    """Downsample image and extract RGB pixels using ImageMagick."""
-    # Validate path contains no shell metacharacters (defense in depth)
-    base_path = image_path.split("[")[0] if "[" in image_path else image_path
-    if not os.path.isfile(base_path):
-        raise FileNotFoundError(f"Image not found: {base_path}")
-    cmd = [
-        "magick", image_path,
-        "-resize", f"{max_dim}x{max_dim}>",
-        "-depth", "8",
-        "txt:-",
-    ]
-    # cmd is a fixed list with validated image_path, shell=False by default
-    result = subprocess.run(  # nosec B603
-        cmd, capture_output=True, text=True, timeout=30, check=False
-    )
-    if result.returncode != 0:
-        raise RuntimeError(f"ImageMagick failed: {result.stderr}")
-
-    pixels = []
-    for line in result.stdout.splitlines():
-        if line.startswith("#"):
-            continue
-        # Format: "x,y: (R,G,B)  #RRGGBB  srgb(R,G,B)" or with alpha
-        parts = line.split("(")
-        if len(parts) < 2:
-            continue
-        color_part = parts[1].split(")")[0]
-        components = [c.strip() for c in color_part.split(",")]
-        if len(components) >= 3:
-            try:
-                r, g, b = int(components[0]), int(components[1]), int(components[2])
-                pixels.append((r, g, b))
-            except ValueError:
-                continue
-    return pixels
-
-
-# ---------------------------------------------------------------------------
-# Theme generation from dominant colors
-# ---------------------------------------------------------------------------
-
-# ANSI hue targets in CIELAB hue angle
-ANSI_HUES = {
-    "red": 30.0,
-    "green": 145.0,
-    "yellow": 95.0,
-    "blue": 275.0,
-    "magenta": 330.0,
-    "cyan": 210.0,
-}
-
-
-def find_nearest_hue(hue: float) -> str:
-    """Map a CIELAB hue angle to the nearest ANSI color name."""
-    best_name = "red"
-    best_dist = 360.0
-    for name, target in ANSI_HUES.items():
-        dist = min(abs(hue - target), 360 - abs(hue - target))
-        if dist < best_dist:
-            best_dist = dist
-            best_name = name
-    return best_name
-
-
-def adjust_lightness(lab: Tuple[float, float, float], target_L: float) -> Tuple[float, float, float]:
-    """Adjust L* while preserving hue and chroma."""
-    L, a, b = lab
-    if L == 0:
-        return (target_L, a, b)
-    scale = target_L / L
-    return (target_L, a * min(scale, 1.5), b * min(scale, 1.5))
-
-
-def ensure_contrast(
-    fg_rgb: Tuple[int, int, int],
-    bg_rgb: Tuple[int, int, int],
-    min_ratio: float,
-    is_dark: bool,
-) -> Tuple[int, int, int]:
-    """Adjust fg lightness until contrast ratio meets min_ratio against bg."""
-    fl, fa, fb = rgb_to_lab(*fg_rgb)
-    for _ in range(80):
-        cr = contrast_ratio(lab_to_rgb(fl, fa, fb), bg_rgb)
-        if cr >= min_ratio:
-            break
-        fl += 2.0 if is_dark else -2.0
-        fl = max(0.0, min(100.0, fl))
-    return lab_to_rgb(fl, fa, fb)
-
-
-# VS Code theming — Catppuccin only.
-#
-# The label must match `contributes.themes[].label` in the extension's
-# package.json exactly, and the icon id must match `contributes.iconThemes[].id`.
-# VS Code cannot resolve an unknown name: it keeps whatever is active and logs
-# an error the user never sees, which is how three wrong values here survived.
-#
-# Verified against catppuccin.catppuccin-vsc 3.19.0 and
-# catppuccin.catppuccin-vsc-icons 1.26.0:
-#   themes      Catppuccin Mocha | Macchiato | Frappe | Latte
-#   iconThemes  catppuccin-mocha | -macchiato | -frappe | -latte
-#   productIconThemes  (none — the extension registers none at all)
-#
-# Neovim still picks per-family (tokyonight/everforest/catppuccin) from the
-# wallpaper hue; only the VS Code surface is pinned, because a single editor
-# theme that is always installed beats three that mostly are not.
-VSCODE_DARK = "Catppuccin Mocha"
-VSCODE_LIGHT = "Catppuccin Latte"
-VSCODE_ICONS_DARK = "catppuccin-mocha"
-VSCODE_ICONS_LIGHT = "catppuccin-latte"
-
-
-def _nvim_from_hue(hue: float, is_dark: bool) -> Tuple[str, str]:
-    """Map accent hue angle to nearest Neovim colorscheme."""
-    if 60 <= hue < 150:
-        return ("everforest", "hard" if is_dark else "soft")
-    if 210 <= hue < 270:
-        return ("tokyonight", "night" if is_dark else "day")
-    return ("catppuccin", "mocha" if is_dark else "latte")
-
-
-def _macos_accent_from_hue(hue: float) -> int:
-    """Map a CIELAB hue angle to a macOS accent-colour integer.
-
-    Boundaries are calibrated to the CIELAB hues of Apple's own accent
-    swatches (not HSL): red≈36°, orange≈67°, yellow≈87°, green≈144°,
-    blue≈287°, purple≈317°. The previous HSL-style cutoffs pushed blue
-    accents (~283°) into Purple and purple into Pink.
-    """
-    hue = hue % 360
-    if hue < 15 or hue >= 345:
-        return 6   # Pink / magenta
-    if hue < 50:
-        return 0   # Red
-    if hue < 77:
-        return 1   # Orange
-    if hue < 110:
-        return 2   # Yellow
-    if hue < 200:
-        return 3   # Green
-    if hue < 300:
-        return 4   # Blue (incl. teal-blue and navy)
-    return 5       # Purple / indigo (300–345)
-
-
-def _env_hex(key: str, fallback: str) -> str:
-    """A #rrggbb value from env, or the fallback when unset/invalid."""
-    v = os.environ.get(key, "")
-    if len(v) == 7 and v[0] == "#":
-        try:
-            hex_to_rgb(v)
-            return v
-        except ValueError:
-            pass
-    return fallback
-
-
-def _compute_bg_fg(clusters, is_dark):
-    """Terminal background/foreground — fixed, engineered neutrals per mode.
-
-    Deliberately NOT derived from the wallpaper: a terminal wants a
-    high-contrast, low-eye-strain surface that stays stable across themes.
-    Dark mode uses a deep neutral grey with off-white text; light mode a warm
-    paper cream with charcoal text. The wallpaper still drives the accent and
-    the 16 ANSI colours (which are computed against this bg for contrast).
-    Override per mode via DOTFILES_TERM_BG_DARK / _FG_DARK / _BG_LIGHT /
-    _FG_LIGHT.
-    """
-    if is_dark:
-        bg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_BG_DARK", "#1e1e2e"))
-        fg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_FG_DARK", "#d4d4d4"))
-    else:
-        bg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_BG_LIGHT", "#fbf1c7"))
-        fg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_FG_LIGHT", "#3c3836"))
-
-    # Tint the engineered neutral toward the wallpaper's dominant hue.
-    #
-    # The lightness stays exactly where it was — that is what the docstring
-    # above is protecting, and it is what keeps contrast and eye strain
-    # predictable. Only a*/b* move, and only to TINT_CHROMA, which is small
-    # enough to read as "this terminal belongs to that wallpaper" rather than
-    # as a coloured background.
-    #
-    # Without this, term.bg had exactly two values across 228 themes and every
-    # theme looked identical apart from one accent. Set DOTFILES_TERM_TINT=0
-    # for the previous flat neutrals.
-    if _env_hex("DOTFILES_TERM_TINT", "1") != "0":
-        ranked = sorted(clusters, key=lambda c: c[1] * lab_chroma(*c[0]), reverse=True)
-        src = ranked[0][0] if ranked and lab_chroma(*ranked[0][0]) >= 5.0 else None
-        if src is not None:
-            hue_c = lab_chroma(*src)
-            if hue_c > 0:
-                # Unit vector along the wallpaper's hue, scaled to a fixed,
-                # deliberately low chroma. Dark surfaces take a touch more:
-                # the same chroma reads weaker against a low-lightness ground.
-                bg_chroma = 4.5 if is_dark else 3.0
-                fg_chroma = 2.5 if is_dark else 2.0
-                ua, ub = src[1] / hue_c, src[2] / hue_c
-                bl = rgb_to_lab(*bg_rgb)[0]
-                fl = rgb_to_lab(*fg_rgb)[0]
-                bg_rgb = lab_to_rgb(bl, ua * bg_chroma, ub * bg_chroma)
-                fg_rgb = lab_to_rgb(fl, ua * fg_chroma, ub * fg_chroma)
-
-    bg_lab = rgb_to_lab(*bg_rgb)
-    return bg_lab, bg_rgb, fg_rgb
-
-
-def _compute_accent(clusters, is_dark):
-    """Select the accent from the wallpaper's DOMINANT chromatic colour.
-
-    Rank clusters by population x chroma so the accent follows the *main*
-    colour of the wallpaper (a large, colourful region) rather than the
-    single most-saturated cluster — which is often a tiny vivid splash
-    that doesn't represent the image. Near-neutral clusters score ~0 and
-    are skipped; if the whole image is neutral we fall back to the most
-    saturated cluster so the accent still carries a hue. The selected
-    colour is then AAA-darkened below (ADR-009 contrast requirement)."""
-    ranked = sorted(clusters, key=lambda c: c[1] * lab_chroma(*c[0]), reverse=True)
-    accent_lab = ranked[0][0]
-    if lab_chroma(*accent_lab) < 5.0:
-        accent_lab = max(clusters, key=lambda c: lab_chroma(*c[0]))[0]
-    if is_dark:
-        accent_lab = (max(accent_lab[0], 35.0), accent_lab[1], accent_lab[2])
-    else:
-        accent_lab = (min(accent_lab[0], 45.0), accent_lab[1], accent_lab[2])
-    # Darken until white text has 7:1 contrast (AAA)
-    al, aa, ab = accent_lab
-    for _ in range(80):
-        if contrast_ratio((255, 255, 255), lab_to_rgb(al, aa, ab)) >= 7.0:
-            break
-        al = max(0.0, al - 2.0)
-    return (al, aa, ab), lab_to_rgb(al, aa, ab)
-
-
-# A support colour that has to fall below this lightness to satisfy the 7:1
-# white-on-block requirement is not carrying colour any more. See the
-# rejection note in _compute_support_colours.
-SUPPORT_MIN_L = 25.0
-
-# Minimum perceptual distance between the three support colours, as dE*ab.
-#
-# This replaced a 12-degree hue-angle check, which let near-identical colours
-# through: hue angle is meaningless at low chroma, so three slate blues at
-# chroma ~13 could sit 12 degrees apart and still be the same colour to look
-# at. forest-dark's accent/secondary/tertiary measured dE 3.6 — against ~2.3
-# for "just noticeable" — while passing the hue rule comfortably.
-#
-# 10 is roughly where two colours read as clearly different rather than as
-# shades of one. Measured over the library, 68 of 228 themes had at least one
-# pair below it; those now reach further down the cluster ranking for a
-# candidate that is actually distinct, and only fall back to a synthetic
-# rotation when the wallpaper genuinely has nothing else to offer.
-SUPPORT_MIN_DE = 10.0
-
-
-def _aaa_darkened(lab, is_dark):
-    """Clamp lightness per mode, then darken until white sits on it at 7:1.
-
-    Shared by the selection filter and the final emission so a candidate is
-    judged on exactly the colour it will become, not on the one it started
-    as — checking the input and emitting the output was how a colour that
-    passed the chroma filter still arrived at L*=14.8.
-
-    A candidate that is ALREADY darker than SUPPORT_MIN_L is then lifted back
-    toward it, one step at a time, stopping the moment another step would
-    cost the 7:1 guarantee. Two different things can leave a support colour
-    too dark: the darkening loop travelling a long way (a low-chroma
-    candidate), and the cluster simply starting dark (dune-light's whole
-    palette sits near L*17 and holds 14.3:1, so the loop never ran). The
-    first is handled by rejecting the candidate; only the second can be
-    lifted, and only where there is contrast headroom to pay for it.
-    """
-    L = max(lab[0], 35.0) if is_dark else min(lab[0], 45.0)
-    a, b = lab[1], lab[2]
-    for _ in range(80):
-        if contrast_ratio((255, 255, 255), lab_to_rgb(L, a, b)) >= 7.0:
-            break
-        L = max(0.0, L - 2.0)
-    while L < SUPPORT_MIN_L:
-        nxt = min(SUPPORT_MIN_L, L + 1.0)
-        if contrast_ratio((255, 255, 255), lab_to_rgb(nxt, a, b)) < 7.0:
-            break
-        L = nxt
-    return (L, a, b)
-
-
-def _displayed(lab, is_dark):
-    """The LAB of the colour that will actually be SHOWN.
-
-    Cluster centroids routinely land outside sRGB — Tang's top three sit at
-    chroma 197, 119 and 98, where sRGB tops out near 130 — and `lab_to_rgb`
-    clamps them. Comparing the raw LAB values said those three were dE 79 and
-    49 apart; after clamping they were #a80000 and #b00000, dE 3.3. The
-    distance test has to run on the clamped colour or it is measuring
-    something the user never sees.
-    """
-    return rgb_to_lab(*lab_to_rgb(*_aaa_darkened(lab, is_dark)))
-
-
-def _compute_support_colours(clusters, accent_lab, is_dark):
-    """The wallpaper's SECOND and THIRD chromatic colours, as UI accents.
-
-    `_compute_accent` takes the top of the population x chroma ranking and
-    throws the rest away, so a wallpaper contributed exactly one colour to
-    the UI and everything else — status bars, separators, inactive states —
-    fell back to fixed neutrals. These are the next two ranked clusters,
-    put through the same AAA-darkening as the accent so white text sits on
-    them at 7:1.
-
-    Clusters within 12 degrees of a colour already chosen are skipped: two
-    near-identical blues give no more information than one, and the point of
-    a secondary is that it reads as different.
-    """
-    ranked = [c for c in sorted(clusters, key=lambda c: c[1] * lab_chroma(*c[0]), reverse=True)
-              if lab_chroma(*c[0]) >= 5.0]
-    # Compare the colours as they will be SHOWN, not as the clusters arrived:
-    # the AAA-darkening moves lightness, which moves perceptual distance too.
-    picked, chosen = [], [rgb_to_lab(*lab_to_rgb(*accent_lab))]
-    for lab, _pop in ranked:
-        final = _displayed(lab, is_dark)
-        if any(lab_distance(final, o) < SUPPORT_MIN_DE for o in chosen):
-            continue
-        # Reject a candidate that only reaches 7:1 by going almost black.
-        #
-        # The AAA-darkening below drives lightness down until white sits on
-        # the colour at 7:1. A low-chroma candidate has to travel a long way
-        # to get there: bauhaus-light's second cluster landed at L*=14.8,
-        # which reads as another shade of dark rather than as a colour, even
-        # though its chroma of 8.0 passed the filter above.
-        #
-        # Measured across the library this affected 7 themes, all light
-        # variants, where the surface is pale and the colours must darken to
-        # sit on it. Raising the chroma floor instead would have cost 34
-        # themes their support colours and fixed only one of these seven, so
-        # the constraint belongs on the OUTCOME, not on the input.
-        if final[0] < SUPPORT_MIN_L:
-            continue
-        picked.append(lab)
-        chosen.append(final)
-        if len(picked) == 2:
-            break
-    # A wallpaper with only one usable hue still needs two support colours, so
-    # the accent's hue is rotated to invent them. Rotating blindly does not
-    # work: a rotated hue at high chroma often falls outside sRGB, and
-    # lab_to_rgb clamps it. Two different angles then clamp to nearly the same
-    # colour — tang-light produced #695600 and #685600, dE 0.5 apart, both at
-    # chroma 45. The fallback was the one path not checking its own output.
-    #
-    # So search: walk angles away from the accent, and drop chroma until the
-    # result survives a round trip through sRGB (proof it is in gamut) and is
-    # far enough from everything already chosen.
-    while len(picked) < 2:
-        base = picked[-1] if picked else accent_lab
-        best = None
-        for deg in (120, 90, 150, 60, 180, 40, 210, 30, 240, 270, 300):
-            for scale in (1.0, 0.85, 0.7, 0.55, 0.4):
-                c = lab_chroma(*base) * scale
-                rad = math.radians((lab_hue(*base) + deg) % 360.0)
-                cand_lab = (base[0], math.cos(rad) * c, math.sin(rad) * c)
-                final = _displayed(cand_lab, is_dark)
-                rgb = lab_to_rgb(*_aaa_darkened(cand_lab, is_dark))
-                # Round trip: if the colour was out of gamut it was clamped,
-                # and the clamped value will not convert back to what we asked
-                # for. That is exactly how the duplicates were produced.
-                if lab_distance(rgb_to_lab(*rgb), final) > 3.0:
-                    continue
-                if final[0] < SUPPORT_MIN_L:
-                    continue
-                d = min(lab_distance(final, o) for o in chosen)
-                if d >= SUPPORT_MIN_DE:
-                    best = cand_lab
-                    break
-                if best is None or d > min(lab_distance(_displayed(best, is_dark), o) for o in chosen):
-                    best = cand_lab
-            if best is not None and min(
-                lab_distance(_displayed(best, is_dark), o) for o in chosen
-            ) >= SUPPORT_MIN_DE:
-                break
-        if best is None:
-            best = (base[0], -base[1], -base[2])  # last resort: opposite hue
-        picked.append(best)
-        chosen.append(_displayed(best, is_dark))
-
-    return (lab_to_rgb(*_aaa_darkened(picked[0], is_dark)),
-            lab_to_rgb(*_aaa_darkened(picked[1], is_dark)))
-
-
-def _on_dark(lab, surfaces, min_ratio=4.5):
-    """The same hue, light enough to be TEXT on a dark surface.
-
-    `accent`, `secondary` and `tertiary` are darkened until white sits on
-    them at 7:1 — they are background colours by construction, and painting
-    them as text on the dark status bar measured as low as 1.67:1.
-
-    This keeps the hue and chroma and walks lightness up instead, until the
-    ratio holds against every surface the text can land on. Without it there
-    is no way to show a wallpaper colour AS text: the choice would be
-    between wallpaper colour and legibility.
-    """
-    L, a, b = lab
-    for _ in range(120):
-        rgb = lab_to_rgb(L, a, b)
-        if all(contrast_ratio(rgb, s) >= min_ratio for s in surfaces):
-            return rgb
-        if L >= 100.0:
-            break
-        L = min(100.0, L + 1.5)
-    return lab_to_rgb(L, a, b)
-
-
-def _muted_text(panel_rgb, border_rgb, bg_lab, is_dark):
-    """Readable de-emphasised text — 4.5:1 against every surface it lands on.
-
-    Not `term.c8`. c8 is ANSI bright-black and is supposed to be dim; its
-    floor is 2.5:1 against bg, and tmux was painting the clock and the
-    inactive window names with it at 2.12:1 and 2.45:1. Raising c8 would
-    have made every terminal's dim colour less dim in order to fix a status
-    bar, so this is a separate slot.
-
-    Floored against BOTH panel and border, not just panel: the two differ in
-    lightness, tmux draws muted text on each of them, and flooring against
-    only the friendlier one left the other at 4.40:1 — a near miss is still
-    a miss.
-    """
-    start = 62.0 if is_dark else 42.0
-    seed = lab_to_rgb(start, bg_lab[1] * 0.5, bg_lab[2] * 0.5)
-    out = seed
-    for surface in (panel_rgb, border_rgb):
-        out = ensure_contrast(out, surface, 4.5, is_dark)
-    # ensure_contrast against the second surface can walk back toward the
-    # first, so confirm rather than assume, and step until both hold.
-    for _ in range(80):
-        if all(contrast_ratio(out, s) >= 4.5 for s in (panel_rgb, border_rgb)):
-            break
-        l, a, b = rgb_to_lab(*out)
-        l = min(100.0, l + 2.0) if is_dark else max(0.0, l - 2.0)
-        out = lab_to_rgb(l, a, b)
-    return out
-
-
-def _compute_panel_border(bg_lab, bg_rgb, is_dark):
-    """Compute panel and border with enforced contrast ranges against bg."""
-    if is_dark:
-        panel_lab = (min(bg_lab[0] + 3, 100), bg_lab[1], bg_lab[2])
-        border_lab = (bg_lab[0] + 8, bg_lab[1] * 0.5, bg_lab[2] * 0.5)
-    else:
-        panel_lab = (max(bg_lab[0] - 3, 0), bg_lab[1], bg_lab[2])
-        border_lab = (bg_lab[0] - 6, bg_lab[1] * 0.3, bg_lab[2] * 0.3)
-    panel_rgb = lab_to_rgb(*panel_lab)
-    for _ in range(20):
-        pr = contrast_ratio(panel_rgb, bg_rgb)
-        if 1.03 <= pr <= 2.0:
-            break
-        if pr < 1.03:
-            panel_lab = (panel_lab[0] + (2 if is_dark else -2), panel_lab[1], panel_lab[2])
-        else:
-            panel_lab = (panel_lab[0] + (-1 if is_dark else 1), panel_lab[1], panel_lab[2])
-        panel_lab = (max(0, min(100, panel_lab[0])), panel_lab[1], panel_lab[2])
-        panel_rgb = lab_to_rgb(*panel_lab)
-    return panel_rgb, lab_to_rgb(*border_lab)
-
-
-def _build_ansi_color(base_lab, accent_lab, bg_rgb, is_dark):
-    """Build normal + bright ANSI variant from a base Lab color."""
-    normal_L = (
-        max(55.0, min(75.0, base_lab[0])) if is_dark
-        else max(30.0, min(50.0, base_lab[0]))
-    )
-    normal = adjust_lightness(base_lab, normal_L)
-    if is_dark:
-        # Dark bg: the bright variant pops by getting lighter.
-        bright = adjust_lightness(base_lab, normal_L + 12)
-        bright_min = 4.5
-    else:
-        # Light bg: a lighter bright would wash out against near-white, so
-        # brighten by vividness at equal lightness instead — the bright is
-        # never darker than the normal (matches Apple's light ANSI ramp,
-        # where brights read as more saturated, not muddier).
-        bright = (normal[0], normal[1] * 1.25, normal[2] * 1.25)
-        bright_min = 7.0
-    # WCAG AAA (7:1) for the chromatic slots on a light bg so coloured text
-    # (paths, syntax) is unambiguously legible — AA (4.5:1) still read as washed
-    # out on cream. Brights stay AAA too and differ from normals by saturation
-    # (Apple's light ramp), not lightness. Dark mode keeps its lower floor
-    # (light text on dark reads comfortably at a lower ratio).
-    normal_min = 3.0 if is_dark else 7.0
-    normal_rgb = ensure_contrast(lab_to_rgb(*normal), bg_rgb, normal_min, is_dark)
-    bright_rgb = ensure_contrast(lab_to_rgb(*bright), bg_rgb, bright_min, is_dark)
-    return normal_rgb, bright_rgb
-
-
-def _ansi_palette(clusters, accent_lab, bg_rgb, is_dark):
-    """Generate the 6 chromatic ANSI hues (red, green, yellow, blue, magenta, cyan)."""
-    chromatic = [(c, pop) for c, pop in clusters if lab_chroma(*c) > 10]
-    hue_assignments: Dict[str, List[Tuple[float, float, float]]] = {h: [] for h in ANSI_HUES}
-    for c_lab, _ in chromatic:
-        hue_assignments[find_nearest_hue(lab_hue(*c_lab))].append(c_lab)
-
-    accent_chroma = lab_chroma(*accent_lab)
-    ansi = {}
-    for hue_name, target_hue in ANSI_HUES.items():
-        candidates = hue_assignments[hue_name]
-        if candidates:
-            base = max(candidates, key=lambda c: lab_chroma(*c))
-        else:
-            new_a = accent_chroma * math.cos(math.radians(target_hue))
-            new_b = accent_chroma * math.sin(math.radians(target_hue))
-            base = (50.0, new_a, new_b)
-        ansi[hue_name] = _build_ansi_color(base, accent_lab, bg_rgb, is_dark)
-    return ansi
-
-
-def _structural_colors(bg_lab, bg_rgb, is_dark):
-    """Compute c0, c7, c8, c15 structural ANSI colors."""
-    if is_dark:
-        return (
-            ensure_contrast(lab_to_rgb(bg_lab[0] + 10, bg_lab[1], bg_lab[2]), bg_rgb, 1.5, True),
-            ensure_contrast(lab_to_rgb(75.0, bg_lab[1] * 0.1, bg_lab[2] * 0.1), bg_rgb, 5.0, True),
-            ensure_contrast(lab_to_rgb(bg_lab[0] + 25, bg_lab[1], bg_lab[2]), bg_rgb, 2.5, True),
-            ensure_contrast(lab_to_rgb(90.0, bg_lab[1] * 0.05, bg_lab[2] * 0.05), bg_rgb, 7.0, True),
-        )
-    # Light bg: the neutral ramp increases in lightness (c0 < c8 < c7 < c15).
-    # c0/c8/c7 stay readable (>= AA); c15 ("bright white") is the LIGHTEST tone,
-    # strictly lighter than c7 — bright-white text legibility is gated by fg, not
-    # c15, and forcing c15 to the same floor as c7 made them converge (c15 ended
-    # a hair darker, breaking the ramp). Start c15 well above c7 with only a mild
-    # floor so it stays the lightest. (Terminals render the dark palette; this
-    # ramp only feeds non-terminal light-palette consumers.)
-    return (
-        ensure_contrast(lab_to_rgb(18.0, bg_lab[1] * 0.2, bg_lab[2] * 0.2), bg_rgb, 7.0, False),
-        ensure_contrast(lab_to_rgb(50.0, bg_lab[1] * 0.15, bg_lab[2] * 0.15), bg_rgb, 4.5, False),
-        ensure_contrast(lab_to_rgb(35.0, bg_lab[1] * 0.2, bg_lab[2] * 0.2), bg_rgb, 4.5, False),
-        ensure_contrast(lab_to_rgb(64.0, bg_lab[1] * 0.08, bg_lab[2] * 0.08), bg_rgb, 2.5, False),
-    )
-
-
-def generate_theme(
-    clusters: List[Tuple[Tuple[float, float, float], int]],
-    name: str,
-    is_dark: bool,
-) -> Dict:
-    """Generate a full theme definition from clustered dominant colors."""
-    bg_lab, bg_rgb, fg_rgb = _compute_bg_fg(clusters, is_dark)
-    accent_lab, accent_rgb = _compute_accent(clusters, is_dark)
-    accent_text = (255, 255, 255)
-    cursor_rgb = accent_rgb
-
-    # Selection background
-    if is_dark:
-        sel_lab = (bg_lab[0] + 15, accent_lab[1] * 0.4, accent_lab[2] * 0.4)
-    else:
-        sel_lab = (bg_lab[0] - 12, accent_lab[1] * 0.3, accent_lab[2] * 0.3)
-    sel_rgb = lab_to_rgb(*sel_lab)
-
-    panel_rgb, border_rgb = _compute_panel_border(bg_lab, bg_rgb, is_dark)
-    secondary_rgb, tertiary_rgb = _compute_support_colours(clusters, accent_lab, is_dark)
-    muted_rgb = _muted_text(panel_rgb, border_rgb, bg_lab, is_dark)
-    # Text-safe versions of the three chromatic colours, for consumers that
-    # paint them as foreground on panel/border rather than as a block.
-    _surfaces = (panel_rgb, border_rgb, bg_rgb)
-    accent_on_rgb = _on_dark(rgb_to_lab(*accent_rgb), _surfaces)
-    secondary_on_rgb = _on_dark(rgb_to_lab(*secondary_rgb), _surfaces)
-    tertiary_on_rgb = _on_dark(rgb_to_lab(*tertiary_rgb), _surfaces)
-    ansi = _ansi_palette(clusters, accent_lab, bg_rgb, is_dark)
-    c0_rgb, c7_rgb, c8_rgb, c15_rgb = _structural_colors(bg_lab, bg_rgb, is_dark)
-
-    accent_hue = lab_hue(*accent_lab)
-    nvim_theme = _nvim_from_hue(accent_hue, is_dark)
-    macos_accent = _macos_accent_from_hue(accent_hue)
-
-    mode = "dark" if is_dark else "light"
-
-    return {
-        "name": name,
-        "mode": mode,
-        "family": name.rsplit("-", 1)[0] if name.endswith(f"-{mode}") else name,
-        "macos_accent": macos_accent,
-        "wallpaper": "",  # Set by caller
-        "source": "custom",  # Set by caller
-        "term": {
-            "bg": rgb_to_hex(*bg_rgb),
-            "fg": rgb_to_hex(*fg_rgb),
-            "cursor": rgb_to_hex(*cursor_rgb),
-            "cursor_text": rgb_to_hex(*bg_rgb),
-            "sel_bg": rgb_to_hex(*sel_rgb),
-            "sel_fg": rgb_to_hex(*fg_rgb),
-            "c0": rgb_to_hex(*c0_rgb),
-            "c1": rgb_to_hex(*ansi["red"][0]),
-            "c2": rgb_to_hex(*ansi["green"][0]),
-            "c3": rgb_to_hex(*ansi["yellow"][0]),
-            "c4": rgb_to_hex(*ansi["blue"][0]),
-            "c5": rgb_to_hex(*ansi["magenta"][0]),
-            "c6": rgb_to_hex(*ansi["cyan"][0]),
-            "c7": rgb_to_hex(*c7_rgb),
-            "c8": rgb_to_hex(*c8_rgb),
-            "c9": rgb_to_hex(*ansi["red"][1]),
-            "c10": rgb_to_hex(*ansi["green"][1]),
-            "c11": rgb_to_hex(*ansi["yellow"][1]),
-            "c12": rgb_to_hex(*ansi["blue"][1]),
-            "c13": rgb_to_hex(*ansi["magenta"][1]),
-            "c14": rgb_to_hex(*ansi["cyan"][1]),
-            "c15": rgb_to_hex(*c15_rgb),
-        },
-        "ui": {
-            "accent": rgb_to_hex(*accent_rgb),
-            "accent_text": rgb_to_hex(*accent_text),
-            "error": rgb_to_hex(*ansi["red"][0]),
-            "warning": rgb_to_hex(*ansi["yellow"][0]),
-            "success": rgb_to_hex(*ansi["green"][0]),
-            "info": rgb_to_hex(*ansi["blue"][0]),
-            "panel": rgb_to_hex(*panel_rgb),
-            "border": rgb_to_hex(*border_rgb),
-            # The wallpaper's 2nd and 3rd chromatic colours. White sits on
-            # either at 7:1, same as accent.
-            "secondary": rgb_to_hex(*secondary_rgb),
-            "tertiary": rgb_to_hex(*tertiary_rgb),
-            # De-emphasised text that is still text: 4.5:1 against `panel`.
-            "text_muted": rgb_to_hex(*muted_rgb),
-            # Same hues, lightened until they are legible AS TEXT on panel,
-            # border and bg (>= 4.5:1 on all three).
-            "accent_on_surface": rgb_to_hex(*accent_on_rgb),
-            "secondary_on_surface": rgb_to_hex(*secondary_on_rgb),
-            "tertiary_on_surface": rgb_to_hex(*tertiary_on_rgb),
-        },
-        "app": {
-            "nvim": nvim_theme[0],
-            "nvim_style": nvim_theme[1],
-            "lualine": nvim_theme[0],
-            "gtk_theme": "Adwaita-dark" if is_dark else "Adwaita",
-            "gtk_icon": "Papirus-Dark" if is_dark else "Papirus-Light",
-            "gnome_shell": "",
-            "gnome_gtk": "Adwaita-dark" if is_dark else "Adwaita",
-            "vscode": VSCODE_DARK if is_dark else VSCODE_LIGHT,
-            "vscode_dark": VSCODE_DARK,
-            "vscode_light": VSCODE_LIGHT,
-            "vscode_icons": VSCODE_ICONS_DARK if is_dark else VSCODE_ICONS_LIGHT,
-            "cat_wallpaper": "",
-            "starship_palette": f"catppuccin_{'mocha' if is_dark else 'latte'}",
-        },
-    }
-
-
-# ---------------------------------------------------------------------------
-# TOML output
-# ---------------------------------------------------------------------------
-
-def theme_to_toml(theme: Dict) -> str:
-    """Render a theme dict as TOML sections."""
-    name = theme["name"]
-    lines = []
-    lines.append(f'[themes.{name}]')
-    lines.append(f'mode = "{theme["mode"]}"')
-    lines.append(f'family = "{theme["family"]}"')
-    lines.append(f'macos_accent = {theme["macos_accent"]}')
-    lines.append(f'wallpaper = "{theme["wallpaper"]}"')
-    lines.append(f'source = "{theme["source"]}"')
-    lines.append("")
-
-    lines.append(f"[themes.{name}.term]")
-    for key in ["bg", "fg", "cursor", "cursor_text", "sel_bg", "sel_fg"]:
-        lines.append(f'{key} = "{theme["term"][key]}"')
-    for i in range(16):
-        key = f"c{i}"
-        pad = " " * (4 - len(key))
-        lines.append(f'{key}{pad}= "{theme["term"][key]}"')
-    lines.append("")
-
-    lines.append(f"[themes.{name}.ui]")
-    for key in ["accent", "accent_text", "secondary", "tertiary", "text_muted",
-                "accent_on_surface", "secondary_on_surface", "tertiary_on_surface",
-                "error", "warning", "success", "info", "panel", "border"]:
-        lines.append(f'{key} = "{theme["ui"][key]}"')
-    lines.append("")
-
-    lines.append(f"[themes.{name}.app]")
-    for key, val in theme["app"].items():
-        lines.append(f'{key} = "{val}"')
-
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-
-def determine_mode(pixels: List[Tuple[int, int, int]]) -> bool:
-    """Determine if image is dark (True) or light (False) from average luminance."""
-    if not pixels:
-        return True
-    avg_lum = sum(relative_luminance(*p) for p in pixels) / len(pixels)
-    return avg_lum < 0.35
-
-
-def derive_name(image_path: str) -> str:
-    """Derive a theme name from the image filename."""
-    base = os.path.splitext(os.path.basename(image_path))[0]
-    # Normalize: lowercase, replace spaces with hyphens, strip non-alphanum
-    name = base.lower().replace(" ", "-").replace("_", "-")
-    name = "".join(c for c in name if c.isalnum() or c == "-")
-    # Remove consecutive hyphens
-    while "--" in name:
-        name = name.replace("--", "-")
-    return name.strip("-")
-
-
-def main():
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        description="Extract a terminal theme from a wallpaper image."
-    )
-    parser.add_argument("image", help="Path to wallpaper image")
-    parser.add_argument("--name", help="Theme name (default: derived from filename)")
-    parser.add_argument("--format", choices=["toml", "json"], default="toml")
-    parser.add_argument("--clusters", type=int, default=8, help="Number of K-Means clusters")
-    parser.add_argument("--source", choices=["system", "custom"], default="custom", help="Wallpaper source type")
-    args = parser.parse_args()
-
-    # Extract pixels
-    try:
-        pixels = extract_pixels(args.image)
-    except FileNotFoundError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
-    if not pixels:
-        print("Error: no pixels extracted", file=sys.stderr)
-        sys.exit(1)
-
-    # Derive name
-    name = args.name or derive_name(args.image)
-
-    # Determine dark/light: trust name suffix if present, else detect from pixels
-    if name.endswith("-dark"):
-        is_dark = True
-    elif name.endswith("-light"):
-        is_dark = False
-    else:
-        is_dark = determine_mode(pixels)
-        name += "-dark" if is_dark else "-light"
-
-    # Subsample for speed — 2000 pixels is enough for accurate K-Means
-    if len(pixels) > 2000:
-        rng = random.Random(42)  # nosec B311 — deterministic sampling
-        pixels = rng.sample(pixels, 2000)
-
-    # Convert to CIELAB
-    lab_pixels = [rgb_to_lab(*p) for p in pixels]
-
-    # Filter near-black and near-white to avoid muddy palettes
-    filtered = [p for p in lab_pixels if 5 < p[0] < 95]
-    if len(filtered) < len(lab_pixels) * 0.1:
-        filtered = lab_pixels  # Image is mostly black/white, use all
-
-    # K-Means clustering
-    clusters = kmeans_lab(filtered, k=args.clusters, runs=3)
-
-    # Generate theme
-    theme = generate_theme(clusters, name, is_dark)
-    wp_base = args.image.split("[")[0] if "[" in args.image else args.image
-    wp_abs = os.path.abspath(wp_base)
-    # Store home-relative with a `~` so the committed themes.toml is not tied to
-    # one machine's username. Consumers (wallpaper-sync.sh) expand `~/`. System
-    # wallpapers (/System/..., /usr/share/...) stay absolute — identical on
-    # every host anyway.
-    home = os.path.expanduser("~")
-    if wp_abs == home or wp_abs.startswith(home + os.sep):
-        wp_abs = "~" + wp_abs[len(home):]
-    theme["wallpaper"] = wp_abs
-    theme["source"] = args.source
-
-    # Output
-    if args.format == "json":
-        print(json.dumps(theme, indent=2))
-    else:
-        print(theme_to_toml(theme))
-
-
-if __name__ == "__main__":
-    main()