opencode-skills-collection 4.1.1 → 4.1.3

package/bundled-skills/liuguang-banlan-ui/scripts/measure_preview.py

@@ -30,17 +30,26 @@ except ModuleNotFoundError as exc:
     raise SystemExit(2)
 
 
-def srgb_to_oklab(rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
-    linear = np.where(
-        rgb <= 0.04045,
-        rgb / 12.92,
-        ((rgb + 0.055) / 1.055) ** 2.4,
-    )
+# A color counts as visible when it deviates this far from the base (OKLab).
+TINT_THRESHOLD = {"opal": 0.003, "obsidian": 0.004}
+# A block is gray when its lightness moves this far with little hue change.
+GRAY_SHIFT = 0.003
+
+
+def load_config(path: pathlib.Path) -> dict:
+    return load_manifest(path)
+
+
+def srgb_to_linear(rgb: np.ndarray) -> np.ndarray:
+    return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def linear_to_oklab(linear: np.ndarray) -> np.ndarray:
     r, g, b = np.moveaxis(linear, -1, 0)
     l = np.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
     m = np.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
     s = np.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
-    lab = np.stack(
+    return np.stack(
         (
             0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
             1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
@@ -48,38 +57,50 @@ def srgb_to_oklab(rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
         ),
         axis=-1,
     )
-    luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
-    return lab, luminance
 
 
-def circular_distance(a: np.ndarray, b: float) -> np.ndarray:
-    delta = np.abs(a - b)
-    return np.minimum(delta, 360.0 - delta)
+def oklch_to_ab(color: dict) -> np.ndarray:
+    hue = np.radians(float(color["h"]))
+    return float(color["c"]) * np.array([np.cos(hue), np.sin(hue)])
 
 
-def measure(image_path: pathlib.Path, config: dict) -> dict:
-    image = Image.open(image_path).convert("RGB")
-    pixels = np.asarray(image, dtype=np.float32) / 255.0
-    lab, luminance = srgb_to_oklab(pixels)
-    chroma = np.hypot(lab[..., 1], lab[..., 2])
-    hue = (np.degrees(np.arctan2(lab[..., 2], lab[..., 1])) + 360.0) % 360.0
+def block_average(linear: np.ndarray, block: int) -> np.ndarray:
+    block = max(1, min(block, linear.shape[0], linear.shape[1]))
+    h = linear.shape[0] // block * block
+    w = linear.shape[1] // block * block
+    trimmed = linear[:h, :w].reshape(h // block, block, w // block, block, 3)
+    return trimmed.mean(axis=(1, 3))
 
-    base_chroma = float(config["base"]["oklch"]["c"])
-    threshold = base_chroma + (0.003 if config["mode"] == "opal" else 0.004)
-    chroma_energy = np.maximum(chroma - threshold, 0.0)
-    visible = chroma_energy > 0
 
-    distances = np.stack(
-        [circular_distance(hue, float(color["oklch"]["h"])) for color in config["colors"]],
-        axis=-1,
-    )
-    assignments = np.argmin(distances, axis=-1)
-    total_pixels = pixels.shape[0] * pixels.shape[1]
-    total_energy = float(chroma_energy.sum())
+def measure(image_path: pathlib.Path, config: dict, block: int = 8) -> dict:
+    with Image.open(image_path) as source:
+        image = source.convert("RGB")
+    linear = srgb_to_linear(np.asarray(image, dtype=np.float64) / 255.0)
+    luminance = 0.2126 * linear[..., 0] + 0.7152 * linear[..., 1] + 0.0722 * linear[..., 2]
+    lab = linear_to_oklab(block_average(linear, block))
+
+    base = config["base"]["oklch"]
+    base_ab = oklch_to_ab(base)
+    shift = lab[..., 0] - float(base["l"])
+    delta = lab[..., 1:] - base_ab
+    tint = np.hypot(delta[..., 0], delta[..., 1])
+
+    threshold = TINT_THRESHOLD.get(config["mode"], 0.003)
+    energy = np.maximum(tint - threshold, 0.0)
+    visible = energy > 0
+    gray = (np.abs(shift) > GRAY_SHIFT) & (tint < np.abs(shift) / 3)
+
+    directions = np.stack([oklch_to_ab(color["oklch"]) - base_ab for color in config["colors"]])
+    angles = np.arctan2(directions[:, 1], directions[:, 0])
+    deviation_angle = np.arctan2(delta[..., 1], delta[..., 0])
+    distance = np.abs((deviation_angle[..., None] - angles + np.pi) % (2 * np.pi) - np.pi)
+    assignments = np.argmin(distance, axis=-1)
+
+    total_blocks = tint.size
+    total_energy = float(energy.sum())
     colors = []
     for index, color in enumerate(config["colors"]):
         assigned = visible & (assignments == index)
-        energy = float(chroma_energy[assigned].sum())
         colors.append(
             {
                 "id": color["id"],
@@ -87,24 +108,40 @@ def measure(image_path: pathlib.Path, config: dict) -> dict:
                 "configuredIntensity": color["intensity"],
                 "oklch": color["oklch"],
                 "peakOpacity": color["peakOpacity"],
-                "measuredCoverage": round(float(assigned.sum()) / total_pixels, 4),
-                "effectiveShare": round(energy / total_energy, 4) if total_energy else 0.0,
+                "measuredCoverage": round(float(assigned.sum()) / total_blocks, 4),
+                "effectiveShare": round(float(energy[assigned].sum()) / total_energy, 4) if total_energy else 0.0,
             }
         )
 
+    mean_tint = float(tint.mean())
     return {
         "image": image_path.name,
         "dimensions": {"width": image.width, "height": image.height},
-        "method": "nearest configured OKLCH hue over pixels above the base-chroma visibility threshold",
-        "visibilityThresholdChroma": round(threshold, 4),
+        "method": (
+            f"OKLab deviation from the configured base over {block}x{block} pixel blocks; "
+            "hue is attributed by the direction of the deviation"
+        ),
+        "blockSize": block,
+        "visibilityThresholdTint": threshold,
         "chromaticPixelRatio": round(float(visible.mean()), 4),
-        "meanOklabChroma": round(float(chroma.mean()), 5),
+        "tint": {
+            "mean": round(mean_tint, 5),
+            "p50": round(float(np.percentile(tint, 50)), 5),
+            "p95": round(float(np.percentile(tint, 95)), 5),
+        },
+        "lightnessShift": {
+            "mean": round(float(shift.mean()), 5),
+            "p05": round(float(np.percentile(shift, 5)), 5),
+            "p95": round(float(np.percentile(shift, 95)), 5),
+        },
+        "shiftToTint": round(abs(float(shift.mean())) / mean_tint, 3) if mean_tint else None,
+        "grayRatio": round(float(gray.mean()), 4) if config["mode"] == "opal" else None,
         "luminance": {
             "mean": round(float(luminance.mean()), 5),
             "p05": round(float(np.percentile(luminance, 5)), 5),
             "p95": round(float(np.percentile(luminance, 95)), 5),
             "max": round(float(luminance.max()), 5),
-            "configuredCap": config["field"]["luminanceCap"],
+            "configuredCap": config["field"].get("luminanceCap"),
         },
         "colors": colors,
     }
@@ -114,25 +151,19 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("--image", required=True, type=pathlib.Path)
     parser.add_argument("--config", required=True, type=pathlib.Path)
+    parser.add_argument("--block", type=int, default=8, help="pixel block size used to average out dither")
     args = parser.parse_args()
     try:
-        config = load_manifest(args.config.resolve())
+        config = load_config(args.config.resolve())
     except (ManifestSyntaxError, OSError) as error:
-        print(
-            json.dumps(
-                {"status": "invalid", "errors": [str(error)]},
-                ensure_ascii=False,
-                indent=2,
-            ),
-            file=sys.stderr,
-        )
+        print(json.dumps({"status": "invalid", "errors": [str(error)]}, ensure_ascii=False, indent=2), file=sys.stderr)
         raise SystemExit(1) from error
     payload = {
-        "schemaVersion": "1.0",
+        "schemaVersion": "1.1",
         "theme": config["label"],
         "preset": config["preset"],
         "overallColorIntensity": config["overallColorIntensity"],
-        "measurement": measure(args.image.resolve(), config),
+        "measurement": measure(args.image.resolve(), config, args.block),
     }
     print(json.dumps(payload, ensure_ascii=False, indent=2))
 

package/bundled-skills/liuguang-banlan-ui/scripts/serve_preview.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Serve a directory over local HTTP with caching disabled, for previews and screenshots."""
+
+import argparse
+import functools
+import http.server
+import pathlib
+
+
+# python -m http.server sends Last-Modified without Cache-Control, so browsers keep
+# serving a stale theme-config.js after an edit and screenshots measure the old field.
+class NoStoreHandler(http.server.SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_header("Cache-Control", "no-store")
+        super().end_headers()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", nargs="?", type=pathlib.Path, default=pathlib.Path("."))
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--bind", default="127.0.0.1")
+    args = parser.parse_args()
+    root = args.directory.resolve()
+    handler = functools.partial(NoStoreHandler, directory=str(root))
+    with http.server.ThreadingHTTPServer((args.bind, args.port), handler) as server:
+        print(f"serving {root} at http://{args.bind}:{args.port}/ with Cache-Control: no-store")
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/bundled-skills/liuguang-banlan-ui/scripts/validate_manifest.py

@@ -126,7 +126,7 @@ def validate(config: dict) -> list[str]:
     if not isinstance(field, dict):
         errors.append("field must be an object")
         field = {}
-    for key in ("scale", "octaves", "warpStrength", "motionSpeed", "staticTime", "ditherStrength", "luminanceCap"):
+    for key in ("scale", "octaves", "warpStrength", "motionSpeed", "staticTime", "ditherStrength"):
         require(key in field, f"field missing {key}", errors)
     check_range(field.get("scale"), 0, float("inf"), "field.scale must be positive", errors, lower_inclusive=False)
     octaves = field.get("octaves")
@@ -139,10 +139,37 @@ def validate(config: dict) -> list[str]:
     check_range(field.get("motionSpeed"), 0, float("inf"), "field.motionSpeed must be finite and nonnegative", errors)
     check_finite(field.get("staticTime"), "field.staticTime must be a finite number", errors)
     check_range(field.get("ditherStrength"), 0, 1, "field.ditherStrength must be in [0, 1]", errors)
-    check_range(field.get("luminanceCap"), 0, 1, "field.luminanceCap must be in (0, 1]", errors, lower_inclusive=False)
+    if config["mode"] == "obsidian" or "luminanceCap" in field:
+        check_range(field.get("luminanceCap"), 0, 1, "field.luminanceCap must be in (0, 1]", errors, lower_inclusive=False)
     return errors
 
 
+def hue_travel(hues: list[float]) -> float:
+    steps = (abs(a - b) % 360 for a, b in zip(hues, hues[1:] + hues[:1]))
+    return sum(min(step, 360 - step) for step in steps)
+
+
+def best_hue_travel(hues: list[float]) -> float:
+    ordered = sorted(h % 360 for h in hues)
+    widest = max([b - a for a, b in zip(ordered, ordered[1:])] + [ordered[0] + 360 - ordered[-1]])
+    return 360.0 if widest <= 180 else 2 * (360 - widest)
+
+
+def collect_warnings(config: dict) -> list[str]:
+    notes: list[str] = []
+    colors = config.get("colors", [])
+    hues = [float(color.get("oklch", {}).get("h", 0)) for color in colors]
+    if len(hues) >= 3:
+        travel, best = hue_travel(hues), best_hue_travel(hues)
+        if travel > best * 1.1:
+            notes.append(
+                f"colors are not in hue order: neighbor hue steps add up to {travel:.0f} degrees, "
+                f"the best order gives {best:.0f}. The renderer mixes each color with its array "
+                "neighbors, and near-complementary neighbors mix toward gray."
+            )
+    return notes
+
+
 def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("config", type=pathlib.Path)
@@ -162,7 +189,11 @@ def main() -> None:
     if errors:
         print(json.dumps({"status": "invalid", "errors": errors}, ensure_ascii=False, indent=2))
         sys.exit(1)
-    print(json.dumps({"status": "valid", "mode": config["mode"], "preset": config["preset"], "colors": len(config["colors"])}, ensure_ascii=False, indent=2))
+    report = {"status": "valid", "mode": config["mode"], "preset": config["preset"], "colors": len(config["colors"])}
+    notes = collect_warnings(config)
+    if notes:
+        report["warnings"] = notes
+    print(json.dumps(report, ensure_ascii=False, indent=2))
 
 
 if __name__ == "__main__":

package/bundled-skills/liuguang-banlan-ui/tests/test_measure_preview.py

@@ -0,0 +1,119 @@
+import pathlib
+import sys
+import tempfile
+import unittest
+
+import numpy as np
+from PIL import Image
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "scripts"))
+import measure_preview as mp  # noqa: E402
+
+LAB_TO_LMS = np.array([
+    [1.0, 0.3963377774, 0.2158037573],
+    [1.0, -0.1055613458, -0.0638541728],
+    [1.0, -0.0894841775, -1.2914855480],
+])
+LMS_TO_RGB = np.array([
+    [4.0767416621, -3.3077115913, 0.2309699292],
+    [-1.2684380046, 2.6097574011, -0.3413193965],
+    [-0.0041960863, -0.7034186147, 1.7076147010],
+])
+HUES = (("rose", 18), ("peach", 62), ("mint", 159), ("cyan", 201), ("blue", 248), ("lilac", 304))
+
+
+def lab_to_srgb(lab):
+    linear = np.clip(LMS_TO_RGB @ ((LAB_TO_LMS @ np.asarray(lab, dtype=np.float64)) ** 3), 0.0, 1.0)
+    return np.where(linear <= 0.0031308, linear * 12.92, 1.055 * linear ** (1 / 2.4) - 0.055)
+
+
+def config(base=(0.982, 0.004, 94)):
+    return {
+        "mode": "opal",
+        "base": {"oklch": {"l": base[0], "c": base[1], "h": base[2]}},
+        "colors": [
+            {"id": cid, "label": cid, "oklch": {"l": 0.93, "c": 0.045, "h": h}, "intensity": 0.5, "peakOpacity": 0.08}
+            for cid, h in HUES
+        ],
+        "field": {},
+    }
+
+
+def base_lab(cfg):
+    o = cfg["base"]["oklch"]
+    h = np.radians(o["h"])
+    return np.array([o["l"], o["c"] * np.cos(h), o["c"] * np.sin(h)])
+
+
+def flat(lab, size=(64, 64)):
+    return np.broadcast_to(lab_to_srgb(lab), (*size, 3)).copy()
+
+
+class MeasurePreviewTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+
+    def measure_codes(self, cfg, codes):
+        path = pathlib.Path(self.tmp.name) / "field.png"
+        Image.fromarray(np.clip(codes, 0, 255).astype(np.uint8)).save(path)
+        return mp.measure(path, cfg)
+
+    def measure(self, cfg, pixels):
+        return self.measure_codes(cfg, np.round(pixels * 255))
+
+    def test_flat_base_reads_as_base(self):
+        for chroma in (0.0, 0.004):
+            with self.subTest(chroma=chroma):
+                cfg = config(base=(0.982, chroma, 94))
+                m = self.measure(cfg, flat(base_lab(cfg)))
+                self.assertEqual(m["chromaticPixelRatio"], 0)
+                self.assertEqual(m["grayRatio"], 0)
+                self.assertLess(abs(m["lightnessShift"]["mean"]), 0.0025)
+                self.assertIsNone(m["luminance"]["configuredCap"])
+
+    def test_visibility_does_not_depend_on_base_chroma(self):
+        tint = np.array([0.0, -0.0045, -0.0025])
+        ratios = []
+        for chroma in (0.0, 0.004, 0.008):
+            cfg = config(base=(0.982, chroma, 94))
+            ratios.append(self.measure(cfg, flat(base_lab(cfg) + tint))["chromaticPixelRatio"])
+        self.assertEqual(ratios, [1.0, 1.0, 1.0])
+
+    def test_hue_follows_deviation_direction(self):
+        cfg = config()
+        blue = np.radians(248)
+        m = self.measure(cfg, flat(base_lab(cfg) + 0.006 * np.array([0.0, np.cos(blue), np.sin(blue)])))
+        coverage = {c["id"]: c["measuredCoverage"] for c in m["colors"]}
+        self.assertEqual(max(coverage, key=coverage.get), "blue")
+
+    def test_lightness_only_shift_is_gray(self):
+        cfg = config(base=(0.982, 0.0, 94))
+        m = self.measure(cfg, flat(base_lab(cfg) + np.array([-0.01, 0.0, 0.0])))
+        self.assertEqual(m["grayRatio"], 1.0)
+        self.assertAlmostEqual(m["lightnessShift"]["mean"], -0.01, delta=0.002)
+
+    def test_tinted_shift_is_not_gray(self):
+        cfg = config()
+        rose = np.radians(18)
+        m = self.measure(cfg, flat(base_lab(cfg) + np.array([-0.006, 0.008 * np.cos(rose), 0.008 * np.sin(rose)])))
+        self.assertEqual(m["grayRatio"], 0)
+        self.assertEqual(m["chromaticPixelRatio"], 1.0)
+
+    def test_gray_ratio_is_only_defined_for_opal(self):
+        cfg = config(base=(0.098, 0.012, 236))
+        cfg["mode"] = "obsidian"
+        m = self.measure(cfg, flat(base_lab(cfg) + np.array([0.15, 0.0, 0.0])))
+        self.assertIsNone(m["grayRatio"])
+
+    def test_block_average_absorbs_dither(self):
+        cfg = config()
+        rng = np.random.default_rng(7)
+        codes = np.round(flat(base_lab(cfg)) * 255) + rng.integers(-1, 2, size=(64, 64, 3))
+        m = self.measure_codes(cfg, codes)
+        self.assertEqual(m["chromaticPixelRatio"], 0)
+        self.assertEqual(m["grayRatio"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/bundled-skills/liuguang-banlan-ui/tests/test_serve_preview.py

@@ -0,0 +1,38 @@
+import functools
+import http.server
+import pathlib
+import sys
+import tempfile
+import threading
+import unittest
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "scripts"))
+import serve_preview  # noqa: E402
+
+
+class QuietHandler(serve_preview.NoStoreHandler):
+    def log_message(self, *args):
+        pass
+
+
+class ServePreviewTest(unittest.TestCase):
+    def test_responses_are_not_cached(self):
+        body = b"window.SPECTRAL_THEME = {};"
+        with tempfile.TemporaryDirectory() as root:
+            pathlib.Path(root, "theme-config.js").write_bytes(body)
+            handler = functools.partial(QuietHandler, directory=root)
+            with http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler) as server:
+                threading.Thread(target=server.serve_forever, daemon=True).start()
+                try:
+                    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+                    url = f"http://127.0.0.1:{server.server_address[1]}/theme-config.js"
+                    with opener.open(url) as response:
+                        self.assertEqual(response.headers["Cache-Control"], "no-store")
+                        self.assertEqual(response.read(), body)
+                finally:
+                    server.shutdown()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/bundled-skills/liuguang-banlan-ui/tests/test_validate_manifest.py

@@ -0,0 +1,73 @@
+import pathlib
+import shutil
+import sys
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+import validate_manifest as vm  # noqa: E402
+
+HUES = {"rose": 18, "peach": 62, "mint": 159, "cyan": 201, "blue": 248, "lilac": 304}
+INTERLEAVED = ["rose", "cyan", "lilac", "peach", "mint", "blue"]
+
+
+def manifest(mode="opal", order=None, cap=None):
+    field = {"scale": 1, "octaves": 4, "warpStrength": 0.3, "motionSpeed": 0.01, "staticTime": 1, "ditherStrength": 1}
+    if cap is not None:
+        field["luminanceCap"] = cap
+    return {
+        "schemaVersion": "1.1",
+        "mode": mode,
+        "label": "test",
+        "preset": "test",
+        "seed": 1,
+        "overallColorIntensity": 0.5,
+        "base": {"oklch": {"l": 0.98, "c": 0.004, "h": 94}},
+        "colors": [
+            {
+                "id": cid,
+                "label": cid,
+                "oklch": {"l": 0.93, "c": 0.04, "h": HUES[cid]},
+                "srgbFallback": "#ffffff",
+                "intensity": 0.5,
+                "peakOpacity": 0.08,
+                "fieldScale": 1,
+                "phase": [0, 0],
+            }
+            for cid in (order or list(HUES))
+        ],
+        "field": field,
+        "output": {"colorSpace": "srgb", "reducedMotion": "frozen-calibrated-frame"},
+    }
+
+
+class ValidateManifestTest(unittest.TestCase):
+    def test_hue_ordered_palette_passes_without_warnings(self):
+        self.assertEqual(vm.validate(manifest()), [])
+        self.assertEqual(vm.collect_warnings(manifest()), [])
+
+    def test_interleaved_palette_warns(self):
+        notes = vm.collect_warnings(manifest(order=INTERLEAVED))
+        self.assertEqual(len(notes), 1)
+        self.assertIn("hue order", notes[0])
+
+    def test_luminance_cap_is_required_only_for_obsidian(self):
+        self.assertEqual(vm.validate(manifest(mode="opal")), [])
+        errors = vm.validate(manifest(mode="obsidian"))
+        self.assertTrue(
+            any(msg.startswith("field.luminanceCap must be in (0, 1]") for msg in errors),
+            errors,
+        )
+        self.assertEqual(vm.validate(manifest(mode="obsidian", cap=0.165)), [])
+
+    @unittest.skipUnless(shutil.which("node"), "node is needed to load the starter manifests")
+    def test_starter_manifests(self):
+        for mode in ("opal", "obsidian"):
+            with self.subTest(mode=mode):
+                config = vm.load_manifest(ROOT / "assets" / "starter" / mode / "theme-config.js")
+                self.assertEqual(vm.validate(config), [])
+                self.assertEqual(vm.collect_warnings(config), [])
+
+
+if __name__ == "__main__":
+    unittest.main()