Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

61.1 KB
Raw Blame
"""Phosphene Bench — a fixed, versioned benchmark of local AI video on a Mac.

One button (Settings -> Phosphene Bench) renders the suite below through the
panel's OWN queue — the same make_job() path, the same worker, the same timer
that every real render and the public /benchmarks numbers use — and turns the
times into a result card (PNG), a JSON record and a plain-text summary.

What makes a benchmark worth quoting is that nobody can tune it, so the rules
live here, in code, not in a doc:

* THE SUITE IS FROZEN. Prompts, seeds, sizes, lengths and step order are data
  in SUITE. `suite_fingerprint()` hashes that data and test_bench.py pins the
  hash to SUITE_FINGERPRINT, so a change that does not also bump SUITE_ID
  ("PB1" -> "PB2") fails the build. Results from two suites are never mixed.
* THE SAME SETTINGS FOR EVERY MAC. The only per-Mac difference is the one the
  app already makes on every render: below 48 GB the Balanced canvas is the
  Compact tier's 768x448 (LTX_QUALITIES applies the clamp). The record says
  which canvas ran, so comparisons stay like for like.
* NOTHING ELSE ON THE GPU. A run refuses to start while anything is queued,
  running, or holding the GPU gate, and it never queues behind other work.
* NEVER A SILENT DOWNLOAD. A step whose model is not on disk is reported
  `missing` with an install offer; the run skips it. Nothing is fetched unless
  the person clicks Install.
* NO BEST-OF. A run that misses a core step is `complete: false` and cannot be
  submitted. Submitting sends EVERY complete run of this suite stored on the
  Mac, and the leaderboard takes each Mac's median.

This module never imports mlx_ltx_panel: the panel hands it a `host` object
(panel/routes_bench.py) with the handful of operations it needs, so the unit
tests drive the runner with a fake host and no GPU.
"""
from __future__ import annotations

import copy
import ctypes
import ctypes.util
import hashlib
import json
import os
import platform
import re
import statistics
import subprocess
import threading
import time
import uuid
from pathlib import Path

import hostinfo

SCHEMA = "phosphene-bench/1"
SUITE_ID = "PB1"
SUITE_NAME = "Phosphene Bench 1"
# sha256 of the canonical suite data, first 12 hex. test_bench.py recomputes
# it: editing SUITE without bumping SUITE_ID (and this pin) fails the build.
SUITE_FINGERPRINT = "170df0bdfe5a"

# Fixed for every Mac. 20261028: the date this suite was frozen for.
SEED = 20261028
# A real prompt with real sound, not a smoke-test string — the Bench renders
# a clip people will look at, and audio is half of what LTX-2.5 generates.
VIDEO_PROMPT = (
    "A lighthouse keeper climbs a spiral iron staircase at dusk, a lantern "
    "swinging in his hand, warm light sweeping across rough stone walls and "
    "a small round window full of stormy sea. Audio: boots ringing on iron "
    "steps, wind whistling through a cracked pane, distant waves breaking, "
    "no music, no speech."
)
IMAGE_PROMPT = (
    "A ceramic teapot on a sunlit wooden table beside an open window, a thin "
    "curl of steam rising from the spout, soft morning light, linen curtain "
    "moving in the breeze, shallow depth of field, natural colour photograph."
)

LABEL_PREFIX = "Phosphene Bench"

# The steps, in run order. `form` is exactly what make_job() receives — the
# same fields the panel's own Generate button posts. Every field that could
# change the work is pinned explicitly, never left to a default that a later
# release, a saved setting or a Load Params could move:
#   enhance off (no prompt rewrite), upscale off (no export pass), accel off,
#   schedule_preset "" (the tuned default), temporal_mode native, one seed.
_LTX_COMMON = {
    "engine": "ltx", "mode": "t2v", "prompt": VIDEO_PROMPT, "seed": str(SEED),
    "frame_rate": "24", "enhance": "off", "upscale": "off", "accel": "off",
    "schedule_preset": "", "temporal_mode": "native", "no_music": "off",
    "steps": "8", "negative_prompt": "",
}
SUITE: dict = {
    "id": SUITE_ID,
    "name": SUITE_NAME,
    "seed": SEED,
    "steps": [
        {
            # UNTIMED warm-up. Loads the video engine so the timed LTX steps
            # measure the Mac, not the disk or the first-use compile. The
            # public /benchmarks drop each install's first render on an
            # engine for the same reason. Its wall time is still recorded.
            "id": "warmup", "kind": "ltx", "core": False, "timed": False,
            "label": "Engine warm-up", "what": "1-second LTX-2.5 Quick clip, excluded from timed results",
            "quality": "quick", "seconds": 1,
            "form": {**_LTX_COMMON, "quality": "quick", "frames": "25"},
        },
        {
            "id": "ltx_quick_5s", "kind": "ltx", "core": True, "timed": True,
            "label": "LTX-2.5 Quick · 5 s", "what": "5-second video with sound, 640×448, 121 frames at 24 fps",
            "quality": "quick", "seconds": 5,
            "form": {**_LTX_COMMON, "quality": "quick", "frames": "121"},
        },
        {
            "id": "ltx_balanced_5s", "kind": "ltx", "core": True, "timed": True,
            "headline": True,
            "label": "LTX-2.5 Balanced · 5 s", "what": "5-second video with sound, 1024×576, 121 frames at 24 fps",
            "quality": "balanced", "seconds": 5,
            "form": {**_LTX_COMMON, "quality": "balanced", "frames": "121"},
        },
        {
            "id": "image_klein", "kind": "image", "core": True, "timed": True,
            "label": "FLUX.2 [klein] 4B · 4 images", "what": "Four 1024×1024 images in one job, 4 steps, 4-bit",
            "images": 4,
            "form": {"mode": "image", "prompt": IMAGE_PROMPT, "seed": str(SEED),
                     "engine_override": "flux2_klein_inline", "aspect": "1:1",
                     "n": "4", "refs": "[]", "loras": "[]"},
        },
        {
            # OPTIONAL. Hailuo H3 is a 75 GB install whose licence excludes
            # the EU, UK, South Korea and the US — the Bench never offers to
            # download it and never puts it in the headline. It runs only
            # where it is already installed, capable and accepted. Best
            # sampler pinned (h3_tristep=0, no Turbo, Auto steps) so the
            # Fast adapter being installed or not cannot change the work.
            "id": "h3_draft_5s", "kind": "h3", "core": False, "timed": True,
            "label": "Hailuo H3 Draft · 5 s", "what": "Optional 5-second video, only with H3 already installed",
            "seconds": 5,
            "form": {"engine": "h3", "mode": "t2v", "prompt": VIDEO_PROMPT,
                     "seed": str(SEED), "h3_quality": "draft", "h3_length": "5s",
                     "h3_tristep": "0", "h3_turbo": "", "h3_steps": "",
                     "h3_upscale": "off", "h3_orientation": "landscape",
                     "enhance": "off", "negative_prompt": ""},
        },
    ],
}

STEP_IDS = tuple(s["id"] for s in SUITE["steps"])
CORE_STEP_IDS = tuple(s["id"] for s in SUITE["steps"] if s["core"])
HEADLINE_STEP = next(s["id"] for s in SUITE["steps"] if s.get("headline"))
# What the image step needs on disk (the HF cache) and how big it is.
KLEIN_REPO = "Runpod/FLUX.2-klein-4B-mflux-4bit"
KLEIN_GB = 4.3
# The snapshot folders mflux's FLUX.2 loader reads (checked before a run).
KLEIN_COMPONENTS = ("transformer", "vae", "text_encoder", "tokenizer")

STEP_STATUSES = ("ready", "missing", "optional_skip", "queued", "running",
                 "done", "failed", "skipped", "cancelled")
THERMAL_STATES = ("nominal", "fair", "serious", "critical", "unknown")


# ---- the suite fingerprint -------------------------------------------------

def suite_fingerprint(suite: dict | None = None) -> str:
    """sha256 over the canonical JSON of everything that defines the work.

    Labels and blurbs are copy, not work, so they are left out: rewording a
    step must not invalidate every result ever recorded."""
    s = suite or SUITE
    core = {
        "id": s["id"], "seed": s["seed"],
        "steps": [{k: v for k, v in st.items() if k not in ("label", "what")}
                  for st in s["steps"]],
    }
    blob = json.dumps(core, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:12]


def step_def(step_id: str) -> dict:
    for s in SUITE["steps"]:
        if s["id"] == step_id:
            return s
    raise KeyError(step_id)


def job_form(step_id: str) -> dict:
    """The make_job form for a step: a fresh copy (callers may not mutate the
    suite), with the queue label added. Values are strings, as a browser
    form would send them."""
    st = step_def(step_id)
    form = dict(st["form"])
    form["preset_label"] = f"{LABEL_PREFIX} · {st['label']}"
    return form


# ---- the plan: what WILL run on this Mac ------------------------------------

def plan(readiness: dict, canvases: dict | None = None) -> list[dict]:
    """Ordered steps with a status each, from a readiness snapshot.

    `readiness` (built by the host from the panel's own probes):
      {"ltx": {"ok": bool, "generation": "ltx25", "missing_keys": [...]},
       "image": {"ok": bool, "gb": 4.3},
       "h3": {"installed": bool, "capable": bool, "licence_ok": bool}}
    `canvases`: {"quick": "640×448", "balanced": "768×448", ...} — the canvas
      THIS Mac renders each quality at (already tier-clamped by the panel).

    Pure: the same readiness gives the same plan, byte for byte.
    """
    canvases = canvases or {}
    ltx = readiness.get("ltx") or {}
    img = readiness.get("image") or {}
    h3 = readiness.get("h3") or {}
    out: list[dict] = []
    for st in SUITE["steps"]:
        row = {"id": st["id"], "label": st["label"], "what": st["what"],
               "kind": st["kind"], "core": st["core"], "timed": st["timed"],
               "headline": bool(st.get("headline")), "status": "ready",
               "reason": "", "install": None}
        if st["kind"] == "ltx":
            canvas = canvases.get(st["quality"])
            if canvas:
                row["canvas"] = canvas
                row["what"] = re.sub(r"\d+×\d+", canvas, st["what"])
            if ltx.get("generation") and ltx["generation"] != "ltx25":
                row["status"], row["reason"] = "missing", "wrong_generation"
            elif not ltx.get("ok"):
                row["status"], row["reason"] = "missing", "ltx_missing"
                row["install"] = {"kind": "models",
                                  "keys": list(ltx.get("missing_keys") or [])}
        elif st["kind"] == "image":
            row["canvas"] = "1024×1024"
            if not img.get("ok"):
                row["status"], row["reason"] = "missing", "image_missing"
                row["install"] = {"kind": "image", "repo": KLEIN_REPO,
                                  "gb": float(img.get("gb") or KLEIN_GB)}
        elif st["kind"] == "h3":
            row["canvas"] = "640×384"
            if not h3.get("capable"):
                row["status"], row["reason"] = "optional_skip", "h3_not_capable"
            elif not h3.get("installed"):
                row["status"], row["reason"] = "optional_skip", "h3_not_installed"
            elif not h3.get("licence_ok"):
                row["status"], row["reason"] = "optional_skip", "h3_licence"
        out.append(row)
    return out


def plan_can_run(rows: list[dict]) -> tuple[bool, str]:
    """Every core step must be ready (a run that cannot be complete is not
    started — it would only produce a result nobody may compare)."""
    for r in rows:
        if r["core"] and r["status"] != "ready":
            return False, r["reason"] or "missing"
    warm = next((r for r in rows if r["id"] == "warmup"), None)
    if warm and warm["status"] != "ready":
        return False, warm["reason"] or "missing"
    return True, ""


# ---- the Mac -----------------------------------------------------------------

_THERMAL_NAMES = {0: "nominal", 1: "fair", 2: "serious", 3: "critical"}


def _objc_process_info():
    """NSProcessInfo.processInfo through the ObjC runtime, or None.

    ctypes, not pyobjc: the engine venv does not carry pyobjc, and this is
    two message sends. Off macOS (or on any failure) every caller degrades to
    "unknown" — a benchmark must never fail because a sensor is missing."""
    try:
        objc = ctypes.cdll.LoadLibrary(ctypes.util.find_library("objc"))
        ctypes.cdll.LoadLibrary("/System/Library/Frameworks/Foundation.framework/Foundation")
        objc.objc_getClass.restype = ctypes.c_void_p
        objc.objc_getClass.argtypes = [ctypes.c_char_p]
        objc.sel_registerName.restype = ctypes.c_void_p
        objc.sel_registerName.argtypes = [ctypes.c_char_p]
        send = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p)(("objc_msgSend", objc))
        cls = objc.objc_getClass(b"NSProcessInfo")
        if not cls:
            return None
        return objc, send(cls, objc.sel_registerName(b"processInfo"))
    except Exception:                                       # noqa: BLE001
        return None


_PI_CACHE: list = []


def thermal_state() -> str:
    """macOS's own thermal pressure verdict: nominal/fair/serious/critical."""
    if not hostinfo.IS_MAC:
        return "unknown"
    try:
        if not _PI_CACHE:
            got = _objc_process_info()
            if got is None:
                return "unknown"
            _PI_CACHE.append(got)
        objc, pi = _PI_CACHE[0]
        sendl = ctypes.CFUNCTYPE(ctypes.c_long, ctypes.c_void_p, ctypes.c_void_p)(("objc_msgSend", objc))
        return _THERMAL_NAMES.get(int(sendl(pi, objc.sel_registerName(b"thermalState"))), "unknown")
    except Exception:                                       # noqa: BLE001
        return "unknown"


def low_power_mode() -> bool | None:
    if not hostinfo.IS_MAC:
        return None
    try:
        out = subprocess.run(["pmset", "-g"], capture_output=True, text=True,
                             errors="replace", timeout=3).stdout
        m = re.search(r"^\s*lowpowermode\s+(\d)", out, re.M)
        return bool(int(m.group(1))) if m else False
    except Exception:                                       # noqa: BLE001
        return None


def power_source() -> str:
    """"ac", "battery" or "unknown". A desktop Mac reports AC."""
    if not hostinfo.IS_MAC:
        return "unknown"
    try:
        out = subprocess.run(["pmset", "-g", "batt"], capture_output=True, text=True,
                             errors="replace", timeout=3).stdout
    except Exception:                                       # noqa: BLE001
        return "unknown"
    if "AC Power" in out:
        return "ac"
    if "Battery Power" in out:
        return "battery"
    return "unknown"


def _sysctl_int(name: str) -> int:
    try:
        v = subprocess.run(["sysctl", "-n", name], capture_output=True, text=True,
                           errors="replace", timeout=3).stdout.strip()
        return int(v) if v.isdigit() else 0
    except Exception:                                       # noqa: BLE001
        return 0


def gpu_cores() -> int:
    if not hostinfo.IS_MAC:
        return 0
    try:
        out = subprocess.run(["system_profiler", "SPDisplaysDataType", "-json"],
                             capture_output=True, text=True, errors="replace",
                             timeout=20).stdout
        for gpu in json.loads(out or "{}").get("SPDisplaysDataType") or []:
            n = str(gpu.get("sppci_cores") or "")
            if n.isdigit():
                return int(n)
    except Exception:                                       # noqa: BLE001
        pass
    return 0


_CHIP_RE = re.compile(r"\bM(\d+)\s*(Pro|Max|Ultra)?\b", re.I)


def chip_family(brand: str) -> str:
    m = _CHIP_RE.search(brand or "")
    if not m:
        return "unknown"
    return f"M{m.group(1)}" + (f" {m.group(2).title()}" if m.group(2) else "")


def mac_info(tier: str = "") -> dict:
    """Hardware CLASS facts — every M4 Max 64 GB Mac16,9 reports the same.
    No serial, no hostname, no user name."""
    brand = hostinfo.chip_brand() or ""
    ram = hostinfo.total_ram_bytes()
    macos = platform.mac_ver()[0] if hostinfo.IS_MAC else ""
    build = ""
    if hostinfo.IS_MAC:
        try:
            build = subprocess.run(["sw_vers", "-buildVersion"], capture_output=True,
                                   text=True, errors="replace", timeout=3).stdout.strip()
        except Exception:                                   # noqa: BLE001
            build = ""
    return {
        "chip": brand or "unknown",
        "chip_family": chip_family(brand),
        "cpu_cores": {"performance": _sysctl_int("hw.perflevel0.physicalcpu"),
                      "efficiency": _sysctl_int("hw.perflevel1.physicalcpu")},
        "gpu_cores": gpu_cores(),
        "ram_gb": int(round(ram / 2**30)) if ram else 0,
        "model_id": hostinfo.hw_model() or "unknown",
        "macos": macos or "unknown",
        "macos_build": build or "unknown",
        "tier": tier or "unknown",
    }


# ---- memory + thermal sampling ------------------------------------------------

class Sampler:
    """Samples the Mac's memory in use (active + wired + compressed, the same
    reading hostinfo gives the rest of the panel) and swap, twice a second, and
    the thermal state every few seconds, while a step runs.

    Whole-Mac numbers on purpose: an MLX render lives in unified memory shared
    with the GPU, and the honest question a reviewer asks is "how much of this
    Mac did it take", which the pre-step baseline answers as `added_gb`."""

    def __init__(self, interval: float = 0.5, reader=None, thermal=None):
        self.interval = interval
        self._read = reader or hostinfo.memory_usage
        self._thermal = thermal or thermal_state
        self._stop = threading.Event()
        self._thread: threading.Thread | None = None
        self.baseline_used = 0
        self.peak_used = 0
        self.peak_swap = 0
        self.thermal_worst = "unknown"
        self.samples = 0

    def _sample(self) -> None:
        try:
            mem = self._read() or {}
        except Exception:                                   # noqa: BLE001
            return
        used, swap = int(mem.get("used") or 0), int(mem.get("swap_used") or 0)
        self.peak_used = max(self.peak_used, used)
        self.peak_swap = max(self.peak_swap, swap)
        self.samples += 1

    def _thermal_sample(self) -> None:
        self.thermal_worst = worse_thermal(self.thermal_worst, self._thermal())

    def start(self) -> None:
        try:
            mem = self._read() or {}
            self.baseline_used = int(mem.get("used") or 0)
        except Exception:                                   # noqa: BLE001
            self.baseline_used = 0
        self._sample()
        self._thermal_sample()

        def loop():
            n = 0
            while not self._stop.wait(self.interval):
                self._sample()
                n += 1
                if n % 6 == 0:
                    self._thermal_sample()
        self._thread = threading.Thread(target=loop, name="bench-sampler", daemon=True)
        self._thread.start()

    def stop(self) -> dict:
        self._stop.set()
        if self._thread:
            self._thread.join(timeout=2)
        self._sample()
        self._thermal_sample()
        gib = 2**30
        return {
            "peak_mem_gb": round(self.peak_used / gib, 1) if self.peak_used else None,
            "added_mem_gb": (round(max(0, self.peak_used - self.baseline_used) / gib, 1)
                             if self.peak_used else None),
            "swap_peak_gb": round(self.peak_swap / gib, 1),
            "thermal_worst": self.thermal_worst,
        }


def worse_thermal(a: str, b: str) -> str:
    order = {"unknown": -1, "nominal": 0, "fair": 1, "serious": 2, "critical": 3}
    return a if order.get(a, -1) >= order.get(b, -1) else b


_MLX_PEAK_RE = re.compile(r"\[mlx\] run peak ([\d.]+) GiB")


def new_log_lines(before: list, after: list) -> list:
    """The log lines added since `before` was taken. The panel log is capped
    (LOG_LIMIT), so an index would drift once it rotates; anchor on the last
    line we had instead."""
    if not before:
        return list(after)
    last = before[-1]
    for i in range(len(after) - 1, -1, -1):
        if after[i] == last:
            return list(after[i + 1:])
    return list(after)


def engine_peak_from_log(lines: list[str]) -> float | None:
    """The helper prints "[mlx] run peak N GiB" at the end of an LTX render;
    the last one in this step's slice of the log is the step's own figure."""
    peak = None
    for ln in lines or ():
        m = _MLX_PEAK_RE.search(str(ln))
        if m:
            peak = round(float(m.group(1)), 1)
    return peak


# ---- the result document ------------------------------------------------------

def _iso(ts: float) -> str:
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts))


def summarize(steps: list[dict]) -> dict:
    by_id = {s["id"]: s for s in steps}
    complete = all((by_id.get(i) or {}).get("status") == "done" for i in CORE_STEP_IDS)
    core_total = (round(sum(by_id[i]["wall_sec"] for i in CORE_STEP_IDS), 1)
                  if complete else None)
    head = by_id.get(HEADLINE_STEP) or {}
    return {
        "complete": complete,
        "core_total_sec": core_total,
        "headline_step": HEADLINE_STEP,
        "headline_sec": head.get("wall_sec") if head.get("status") == "done" else None,
    }


def warnings_for(conditions: dict, steps: list[dict]) -> list[str]:
    w = []
    if conditions.get("power") == "battery":
        w.append("battery")
    if conditions.get("low_power_mode"):
        w.append("low_power_mode")
    if conditions.get("output_preset_default") is False:
        w.append("output_codec")
    if conditions.get("thermal_worst") in ("serious", "critical"):
        w.append("thermal_" + conditions["thermal_worst"])
    # Swap GROWTH, not swap: a Mac that already had swap in use before the
    # run (macOS keeps it for hours) did not page because of the Bench.
    base = float(conditions.get("swap_start_gb") or 0.0)
    if any((s.get("swap_peak_gb") or 0) - base >= 1.0 for s in steps if s.get("status") == "done"):
        w.append("swap")
    return w


def eligible(doc: dict) -> bool:
    """May this run go on the leaderboard? Complete, this suite, and not in
    Low Power Mode (which caps the GPU by design — a different machine)."""
    return bool(doc.get("suite", {}).get("id") == SUITE_ID
                and doc.get("suite", {}).get("fingerprint") == SUITE_FINGERPRINT
                and doc.get("summary", {}).get("complete")
                and not doc.get("conditions", {}).get("low_power_mode")
                # The encode settings live in Settings, not in the suite: a
                # non-default output codec changes the encode time, so it is
                # recorded and keeps the run off the board.
                and doc.get("conditions", {}).get("output_preset_default") is not False)


def new_run_id() -> str:
    return uuid.uuid4().hex[:16]


def build_result(*, run_id: str, started: float, finished: float, app: dict, mac: dict,
                 conditions: dict, steps: list[dict]) -> dict:
    doc = {
        "schema": SCHEMA,
        "suite": {"id": SUITE_ID, "name": SUITE_NAME, "fingerprint": SUITE_FINGERPRINT},
        "run_id": run_id,
        "started_at": _iso(started),
        "finished_at": _iso(finished),
        "app": app,
        "mac": mac,
        "conditions": conditions,
        "steps": steps,
        "summary": summarize(steps),
    }
    doc["warnings"] = warnings_for(conditions, steps)
    doc["summary"]["eligible"] = eligible(doc)
    return doc


# ---- JSON Schema ----------------------------------------------------------------
# Published as docs/bench.schema.json (test_bench.py keeps the two identical)
# and enforced on every document this module writes by validate().

_NUM_OR_NULL = {"type": ["number", "null"], "minimum": 0}
_STEP_SCHEMA = {
    "type": "object",
    "required": ["id", "label", "status", "core", "timed", "wall_sec"],
    "additionalProperties": False,
    "properties": {
        "id": {"type": "string", "enum": list(STEP_IDS)},
        "label": {"type": "string"},
        "kind": {"type": "string", "enum": ["ltx", "image", "h3"]},
        "core": {"type": "boolean"},
        "timed": {"type": "boolean"},
        "status": {"type": "string", "enum": ["done", "failed", "skipped", "cancelled"]},
        "reason": {"type": "string"},
        "canvas": {"type": ["string", "null"], "pattern": r"^\d+×\d+$"},
        "frames": {"type": ["integer", "null"], "minimum": 0},
        "images": {"type": ["integer", "null"], "minimum": 0},
        "wall_sec": _NUM_OR_NULL,
        "peak_mem_gb": _NUM_OR_NULL,
        "added_mem_gb": _NUM_OR_NULL,
        "swap_peak_gb": _NUM_OR_NULL,
        "engine_peak_gb": _NUM_OR_NULL,
        "thermal_worst": {"type": "string", "enum": list(THERMAL_STATES)},
    },
}
RESULT_SCHEMA = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://phosphene.video/bench/schema/phosphene-bench-1.json",
    "title": "Phosphene Bench result",
    "type": "object",
    "required": ["schema", "suite", "run_id", "started_at", "finished_at", "app",
                 "mac", "conditions", "steps", "summary", "warnings"],
    "additionalProperties": False,
    "properties": {
        "schema": {"type": "string", "enum": [SCHEMA]},
        "suite": {
            "type": "object", "required": ["id", "name", "fingerprint"],
            "additionalProperties": False,
            "properties": {"id": {"type": "string", "pattern": r"^PB\d+$"},
                           "name": {"type": "string"},
                           "fingerprint": {"type": "string", "pattern": r"^[0-9a-f]{12}$"}},
        },
        "run_id": {"type": "string", "pattern": r"^[0-9a-f]{16}$"},
        "started_at": {"type": "string", "pattern": r"^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$"},
        "finished_at": {"type": "string", "pattern": r"^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$"},
        "app": {
            "type": "object", "required": ["version", "edition", "distribution"],
            "additionalProperties": False,
            "properties": {"version": {"type": "string"},
                           "edition": {"type": "string", "enum": ["free", "pro"]},
                           "distribution": {"type": "string", "enum": ["pinokio", "mac-app"]},
                           "generation": {"type": "string"}},
        },
        "mac": {
            "type": "object",
            "required": ["chip", "chip_family", "cpu_cores", "gpu_cores", "ram_gb",
                         "model_id", "macos", "macos_build", "tier"],
            "additionalProperties": False,
            "properties": {
                "chip": {"type": "string"}, "chip_family": {"type": "string"},
                "cpu_cores": {"type": "object", "required": ["performance", "efficiency"],
                              "additionalProperties": False,
                              "properties": {"performance": {"type": "integer", "minimum": 0},
                                             "efficiency": {"type": "integer", "minimum": 0}}},
                "gpu_cores": {"type": "integer", "minimum": 0},
                "ram_gb": {"type": "integer", "minimum": 0},
                "model_id": {"type": "string"}, "macos": {"type": "string"},
                "macos_build": {"type": "string"}, "tier": {"type": "string"},
            },
        },
        "conditions": {
            "type": "object",
            "required": ["power", "low_power_mode", "thermal_start", "thermal_worst"],
            "additionalProperties": False,
            "properties": {
                "power": {"type": "string", "enum": ["ac", "battery", "unknown"]},
                "low_power_mode": {"type": ["boolean", "null"]},
                "thermal_start": {"type": "string", "enum": list(THERMAL_STATES)},
                "thermal_worst": {"type": "string", "enum": list(THERMAL_STATES)},
                "mem_used_start_gb": _NUM_OR_NULL,
                "swap_start_gb": _NUM_OR_NULL,
                "warmup_sec": _NUM_OR_NULL,
                "output_preset": {"type": ["string", "null"]},
                "output_preset_default": {"type": ["boolean", "null"]},
            },
        },
        "steps": {"type": "array", "items": _STEP_SCHEMA},
        "summary": {
            "type": "object",
            "required": ["complete", "eligible", "core_total_sec", "headline_step", "headline_sec"],
            "additionalProperties": False,
            "properties": {"complete": {"type": "boolean"}, "eligible": {"type": "boolean"},
                           "core_total_sec": _NUM_OR_NULL,
                           "headline_step": {"type": "string", "enum": list(STEP_IDS)},
                           "headline_sec": _NUM_OR_NULL},
        },
        "warnings": {"type": "array", "items": {"type": "string"}},
    },
}


def _type_ok(val, t) -> bool:
    types = t if isinstance(t, list) else [t]
    for name in types:
        if name == "null" and val is None:
            return True
        if name == "boolean" and isinstance(val, bool):
            return True
        if name == "integer" and isinstance(val, int) and not isinstance(val, bool):
            return True
        if name == "number" and isinstance(val, (int, float)) and not isinstance(val, bool):
            return True
        if name == "string" and isinstance(val, str):
            return True
        if name == "object" and isinstance(val, dict):
            return True
        if name == "array" and isinstance(val, list):
            return True
    return False


def validate(doc, schema: dict | None = None, path: str = "$") -> list[str]:
    """A small JSON Schema validator for exactly the keywords RESULT_SCHEMA
    uses (type, required, properties, additionalProperties, items, enum,
    pattern, minimum). The engine venv has no jsonschema; the schema file is
    still standard draft 2020-12, so anyone can check a result with any
    validator. Returns a list of errors; empty means valid."""
    s = RESULT_SCHEMA if schema is None else schema
    errs: list[str] = []
    if "type" in s and not _type_ok(doc, s["type"]):
        return [f"{path}: expected {s['type']}, got {type(doc).__name__}"]
    if "enum" in s and doc not in s["enum"]:
        errs.append(f"{path}: {doc!r} not one of {s['enum']}")
    if isinstance(doc, str) and "pattern" in s and not re.search(s["pattern"], doc):
        errs.append(f"{path}: {doc!r} does not match {s['pattern']}")
    if (isinstance(doc, (int, float)) and not isinstance(doc, bool)
            and "minimum" in s and doc < s["minimum"]):
        errs.append(f"{path}: {doc} < {s['minimum']}")
    if isinstance(doc, dict):
        for k in s.get("required", ()):
            if k not in doc:
                errs.append(f"{path}: missing {k!r}")
        props = s.get("properties", {})
        for k, v in doc.items():
            if k in props:
                errs.extend(validate(v, props[k], f"{path}.{k}"))
            elif s.get("additionalProperties") is False:
                errs.append(f"{path}: unexpected {k!r}")
    if isinstance(doc, list) and "items" in s:
        for i, v in enumerate(doc):
            errs.extend(validate(v, s["items"], f"{path}[{i}]"))
    return errs


# ---- formatting --------------------------------------------------------------

def fmt_sec(sec) -> str:
    """48 s · 2m 19s · 1h 02m."""
    if sec is None:
        return "—"
    s = int(round(float(sec)))
    if s < 60:
        return f"{s} s"
    if s < 3600:
        return f"{s // 60}m {s % 60:02d}s"
    return f"{s // 3600}h {(s % 3600) // 60:02d}m"


_THERMAL_WORDS = {"nominal": "nominal", "fair": "fair", "serious": "serious",
                  "critical": "critical", "unknown": "not reported"}


def summary_text(doc: dict) -> str:
    """The "Copy results" block: plain text a reviewer can paste anywhere."""
    mac, app, cond = doc["mac"], doc["app"], doc["conditions"]
    cores = mac.get("cpu_cores") or {}
    cpu = (cores.get("performance") or 0) + (cores.get("efficiency") or 0)
    lines = [
        f"{COPY['copy_results_header']} · suite {doc['suite']['fingerprint']}",
        f"{mac['chip']} · {mac['gpu_cores']}-core GPU · {cpu}-core CPU · {mac['ram_gb']} GB · "
        f"{mac['model_id']} · macOS {mac['macos']} ({mac['macos_build']})",
        f"Phosphene {app['version']} ({app['edition']}, {app['distribution']})",
        "",
    ]
    for st in doc["steps"]:
        if not st.get("timed"):
            continue
        t = fmt_sec(st.get("wall_sec")) if st["status"] == "done" else st["status"]
        mem = (f" · peak {st['peak_mem_gb']} GB in use (+{st['added_mem_gb']} GB)"
               if st.get("peak_mem_gb") is not None and st["status"] == "done" else "")
        canvas = f" · {st['canvas']}" if st.get("canvas") else ""
        lines.append(f"{st['label']}{canvas}: {t}{mem}")
    lines.append("")
    warm = cond.get("warmup_sec")
    lines.append(
        f"Engine warm-up {fmt_sec(warm)} (untimed) · power {cond['power']} · Low Power Mode "
        f"{'on' if cond.get('low_power_mode') else 'off'} · thermal {_THERMAL_WORDS.get(cond['thermal_start'])}"
        f" -> {_THERMAL_WORDS.get(cond['thermal_worst'])}")
    if not doc["summary"]["complete"]:
        lines.append(COPY["result_incomplete"])
    lines.append(f"Run {doc['run_id']} · {doc['finished_at']} · phosphene.video/bench")
    return "\n".join(lines)


# ---- analytics (the opt-in leaderboard submission) -----------------------------

def analytics_props(doc: dict, run_index: int = 1, runs_total: int = 1) -> dict:
    """The flat property dict for ONE `bench_result` event (docs/ANALYTICS.md).

    Hardware CLASS and timings only: no prompt (the suite's are fixed anyway),
    no path, no filename, no seed. Exact seconds are sent — unlike the
    bucketed render_completed — because publishing them is the point of an
    explicit, per-click opt-in."""
    mac, app, cond = doc["mac"], doc["app"], doc["conditions"]
    p = {
        "schema": doc["schema"],
        "suite_id": doc["suite"]["id"],
        "suite_fp": doc["suite"]["fingerprint"],
        "run_id": doc["run_id"],
        "run_index": int(run_index),
        "runs_total": int(runs_total),
        "version": app["version"],
        "edition": app["edition"],
        "distribution": app["distribution"],
        "chip_family": mac["chip_family"],
        "gpu_cores": mac["gpu_cores"],
        "cpu_p": (mac.get("cpu_cores") or {}).get("performance", 0),
        "cpu_e": (mac.get("cpu_cores") or {}).get("efficiency", 0),
        "ram_gb": mac["ram_gb"],
        "model_id": mac["model_id"],
        "os_version": ".".join(str(mac["macos"]).split(".")[:2]),
        "power": cond["power"],
        "low_power": bool(cond.get("low_power_mode")),
        "thermal_worst": cond["thermal_worst"],
        "warmup_sec": cond.get("warmup_sec"),
        "complete": bool(doc["summary"]["complete"]),
        "eligible": bool(doc["summary"]["eligible"]),
    }
    for st in doc["steps"]:
        if st["id"] == "warmup":
            continue
        k = st["id"]
        p[f"st_{k}"] = st["status"]
        p[f"s_{k}"] = st.get("wall_sec") if st["status"] == "done" else None
        p[f"mem_{k}"] = st.get("peak_mem_gb") if st["status"] == "done" else None
        p[f"add_{k}"] = st.get("added_mem_gb") if st["status"] == "done" else None
        p[f"cv_{k}"] = st.get("canvas")
    return p


def runs_to_submit(docs: list[dict]) -> list[dict]:
    """Every complete, eligible run of THIS suite, oldest first — not the one
    on screen. That is the no-best-of rule: the board takes each Mac's
    median, so sending all of them is what makes the median honest."""
    ok = [d for d in docs if eligible(d)]
    return sorted(ok, key=lambda d: d["started_at"])


def install_median(docs: list[dict], step_id: str) -> float | None:
    """What the leaderboard does per Mac (mirrored in the site's builder)."""
    vals = [s["wall_sec"] for d in docs for s in d["steps"]
            if s["id"] == step_id and s["status"] == "done" and s.get("wall_sec") is not None]
    return round(statistics.median(vals), 1) if vals else None


# ---- storage -------------------------------------------------------------------

class Store:
    """state/bench/<run_id>.json + <run_id>.png, and submitted.json (run ids
    already sent, so a second Submit sends only what is new)."""

    def __init__(self, root: Path):
        self.root = Path(root)

    def _ensure(self) -> None:
        self.root.mkdir(parents=True, exist_ok=True)

    def path(self, run_id: str, ext: str) -> Path:
        if not re.fullmatch(r"[0-9a-f]{16}", run_id or ""):
            raise ValueError("bad run id")
        return self.root / f"{run_id}.{ext}"

    def save(self, doc: dict) -> Path:
        errs = validate(doc)
        if errs:
            raise ValueError("bench result does not match its schema: " + "; ".join(errs[:5]))
        self._ensure()
        p = self.path(doc["run_id"], "json")
        tmp = p.with_suffix(".json.tmp")
        tmp.write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
        os.replace(tmp, p)
        return p

    def load(self, run_id: str) -> dict | None:
        try:
            return json.loads(self.path(run_id, "json").read_text(encoding="utf-8"))
        except (OSError, ValueError):
            return None

    def runs(self) -> list[dict]:
        out = []
        if not self.root.is_dir():
            return out
        for p in sorted(self.root.glob("*.json")):
            if not re.fullmatch(r"[0-9a-f]{16}\.json", p.name):
                continue
            try:
                d = json.loads(p.read_text(encoding="utf-8"))
            except (OSError, ValueError):
                continue
            if isinstance(d, dict) and d.get("schema") == SCHEMA:
                out.append(d)
        return sorted(out, key=lambda d: d.get("started_at", ""), reverse=True)

    def submitted(self) -> set[str]:
        try:
            return set(json.loads((self.root / "submitted.json").read_text(encoding="utf-8")))
        except (OSError, ValueError, TypeError):
            return set()

    def mark_submitted(self, ids) -> None:
        self._ensure()
        cur = self.submitted() | set(ids)
        (self.root / "submitted.json").write_text(json.dumps(sorted(cur)) + "\n", encoding="utf-8")


# ---- the runner ----------------------------------------------------------------

class BenchBusy(RuntimeError):
    """The Mac is doing something else (queue, render, GPU gate, a run)."""


class Runner:
    """Runs the suite through the host's queue, one step at a time.

    host must provide:
      readiness() -> dict            (see plan())
      canvases() -> dict             quality -> "W×H" on this Mac
      busy_reason() -> str           "" when nothing is queued/running/holding the GPU
      make_job(form) -> job dict     the panel's make_job
      refusal(job) -> str            "" or why the panel would refuse this job
      enqueue(job)
      job(job_id) -> dict | None     the live job (queue, current or history)
      cancel(job_id)
      cold_start()                   drop the warm engine so every run starts the same
      log_lines() -> list[str]       the panel log, oldest first
      app_info() -> dict             {version, edition, distribution, generation}
      render_settings() -> dict      Settings that change the time but are not suite data
                                     ({output_preset, output_preset_default})
      tier() -> str
      store -> Store
      render_card(doc, path)         write the PNG
    """

    TERMINAL = ("done", "failed", "cancelled", "stopped", "error")
    # A step's job that is in neither the queue, `current` nor history for
    # this long was removed by hand (or trimmed); the run stops waiting.
    vanish_after = 60.0

    def __init__(self, host, poll: float = 1.0, sampler_factory=None, clock=time.time):
        self.host = host
        self.poll = poll
        self._sampler_factory = sampler_factory or (lambda: Sampler())
        self._clock = clock
        self._lock = threading.Lock()
        self._thread: threading.Thread | None = None
        self._cancel = threading.Event()
        self.state: dict = {"running": False, "run_id": None, "steps": [], "step_index": None,
                            "step_started": None, "job_id": None, "error": "", "last_run": None,
                            "stopped": False}

    # -- public -------------------------------------------------------------
    def snapshot(self) -> dict:
        with self._lock:
            st = copy.deepcopy(self.state)
        if st.get("running") and st.get("step_started"):
            st["step_elapsed"] = round(self._clock() - st["step_started"], 1)
        return st

    def start(self, wait: bool = False) -> str:
        with self._lock:
            if self.state["running"]:
                raise BenchBusy("bench_running")
            busy = self.host.busy_reason()
            if busy:
                raise BenchBusy(busy)
            rows = plan(self.host.readiness(), self.host.canvases())
            ok, why = plan_can_run(rows)
            if not ok:
                raise BenchBusy(why)
            run_id = new_run_id()
            self._cancel.clear()
            self.state.update(running=True, run_id=run_id, step_index=None, job_id=None,
                              error="", stopped=False, step_started=None,
                              steps=[{"id": r["id"], "label": r["label"], "status":
                                      ("queued" if r["status"] == "ready" else r["status"]),
                                      "reason": r["reason"], "wall_sec": None} for r in rows])
        self._thread = threading.Thread(target=self._run, args=(run_id, rows),
                                        name="phosphene-bench", daemon=True)
        self._thread.start()
        if wait:
            self._thread.join()
        return run_id

    def cancel(self) -> bool:
        with self._lock:
            if not self.state["running"]:
                return False
            job_id = self.state.get("job_id")
        self._cancel.set()
        if job_id:
            try:
                self.host.cancel(job_id)
            except Exception:                               # noqa: BLE001
                pass
        return True

    # -- the thread -----------------------------------------------------------
    def _set_step(self, idx: int, **kw) -> None:
        with self._lock:
            self.state["steps"][idx].update(kw)

    def _run(self, run_id: str, rows: list[dict]) -> None:
        started = self._clock()
        results: list[dict] = []
        warmup_sec = None
        try:
            app = self.host.app_info()
            mac = mac_info(self.host.tier())
            mem0 = hostinfo.memory_usage()
            conditions = {
                "power": power_source(),
                "low_power_mode": low_power_mode(),
                "thermal_start": thermal_state(),
                "thermal_worst": "unknown",
                "mem_used_start_gb": round((mem0.get("used") or 0) / 2**30, 1),
                "swap_start_gb": round((mem0.get("swap_used") or 0) / 2**30, 1),
            }
            conditions["thermal_worst"] = conditions["thermal_start"]
            try:
                conditions.update(self.host.render_settings() or {})
            except Exception:                               # noqa: BLE001
                pass
            try:
                self.host.cold_start()
            except Exception:                               # noqa: BLE001
                pass
            for idx, row in enumerate(rows):
                st = step_def(row["id"])
                rec = {"id": row["id"], "label": row["label"], "kind": st["kind"],
                       "core": st["core"], "timed": st["timed"], "status": "skipped",
                       "reason": row["reason"], "canvas": row.get("canvas"),
                       "frames": None, "images": st.get("images"), "wall_sec": None,
                       "peak_mem_gb": None, "added_mem_gb": None, "swap_peak_gb": None,
                       "engine_peak_gb": None, "thermal_worst": "unknown"}
                if self._cancel.is_set():
                    rec["status"], rec["reason"] = "cancelled", "stopped"
                    self._set_step(idx, status="cancelled")
                    results.append(rec)
                    continue
                if row["status"] != "ready":
                    self._set_step(idx, status="skipped")
                    results.append(rec)
                    continue
                self._run_step(idx, row, rec)
                if rec["thermal_worst"] != "unknown":
                    conditions["thermal_worst"] = worse_thermal(conditions["thermal_worst"],
                                                                rec["thermal_worst"])
                if row["id"] == "warmup":
                    warmup_sec = rec["wall_sec"]
                    if rec["status"] != "done":
                        # Without a working engine the timed steps would fail
                        # the same way; stop here and say why.
                        if rec["status"] == "failed":
                            with self._lock:
                                self.state["error"] = f"Engine warm-up failed: {rec['reason']}"
                        self._cancel.set()
                results.append(rec)
            conditions["warmup_sec"] = warmup_sec
            # The warm-up is recorded in conditions, never as a result row a
            # reader could mistake for a measurement.
            steps_out = [r for r in results if r["id"] != "warmup"]
            doc = build_result(run_id=run_id, started=started, finished=self._clock(),
                               app=app, mac=mac, conditions=conditions, steps=steps_out)
            self.host.store.save(doc)
            try:
                self.host.render_card(doc, self.host.store.path(run_id, "png"))
            except Exception as exc:                        # noqa: BLE001
                with self._lock:
                    self.state["error"] = f"card: {exc}"
            with self._lock:
                self.state["last_run"] = run_id
                self.state["stopped"] = self._cancel.is_set()
        except Exception as exc:                            # noqa: BLE001
            with self._lock:
                self.state["error"] = str(exc)
        finally:
            with self._lock:
                self.state.update(running=False, step_index=None, job_id=None, step_started=None)

    def _wait_idle(self, timeout: float = 600.0) -> bool:
        """Between steps the worker is finishing its bookkeeping (history,
        persist); wait for the panel to be idle again before queueing, so a
        step never starts behind anything."""
        end = self._clock() + timeout
        while self._clock() < end:
            if self._cancel.is_set():
                return False
            if not self.host.busy_reason():
                return True
            time.sleep(self.poll)
        return False

    def _run_step(self, idx: int, row: dict, rec: dict) -> None:
        if not self._wait_idle():
            rec["status"] = "cancelled" if self._cancel.is_set() else "failed"
            rec["reason"] = "stopped" if self._cancel.is_set() else "busy"
            self._set_step(idx, status=rec["status"], reason=rec["reason"])
            return
        try:
            job = self.host.make_job(job_form(row["id"]))
        except Exception as exc:                            # noqa: BLE001
            rec["status"], rec["reason"] = "failed", f"could not build the job: {exc}"
            self._set_step(idx, status="failed", reason=rec["reason"])
            return
        refusal = self.host.refusal(job)
        if refusal:
            rec["status"], rec["reason"] = "failed", refusal
            self._set_step(idx, status="failed", reason=refusal)
            return
        params = job.get("params") or {}
        if row.get("kind") == "ltx" or rec["kind"] in ("ltx", "h3"):
            w, h = params.get("width"), params.get("height")
            if w and h:
                rec["canvas"] = f"{int(w)}×{int(h)}"
            if params.get("frames"):
                rec["frames"] = int(params["frames"])
        log_before = self.host.log_lines()
        sampler = self._sampler_factory()
        sampler.start()
        final = None
        try:
            with self._lock:
                self.state.update(step_index=idx, job_id=job["id"], step_started=self._clock())
            self._set_step(idx, status="running")
            if self._cancel.is_set():
                # Stop pressed while the job was being built: never queue it.
                job["status"] = "cancelled"
            else:
                self.host.enqueue(job)
                if self._cancel.is_set():
                    # Stop pressed between publishing the id and queueing:
                    # cancel() may have looked before the job existed.
                    try:
                        self.host.cancel(job["id"])
                    except Exception:                       # noqa: BLE001
                        pass
            missing = 0
            while job.get("status") != "cancelled":
                j = self.host.job(job["id"])
                # TERMINAL means the worker has also stamped the timer: it sets
                # `done` before its finally block writes finished_at and
                # elapsed_sec, and reading in between would record 0 s.
                if (j is not None and j.get("status") in self.TERMINAL
                        and (j.get("finished_at") or self._cancel.is_set())):
                    final = j
                    break
                if j is None:
                    missing += 1
                    # Removed from the queue by hand, or trimmed out of a
                    # history we never saw it land in: stop waiting.
                    if self._cancel.is_set() or missing * self.poll >= self.vanish_after:
                        break
                else:
                    missing = 0
                time.sleep(self.poll)
        finally:
            mem = sampler.stop()
        rec.update({k: mem[k] for k in ("peak_mem_gb", "added_mem_gb", "swap_peak_gb", "thermal_worst")})
        rec["engine_peak_gb"] = engine_peak_from_log(new_log_lines(log_before, self.host.log_lines()))
        if final is not None:
            fp = final.get("params") or {}
            if rec["kind"] in ("ltx", "h3") and fp.get("width") and fp.get("height"):
                rec["canvas"] = f"{int(fp['width'])}×{int(fp['height'])}"
            if fp.get("frames"):
                rec["frames"] = int(fp["frames"])
        status = (final or {}).get("status")
        if status == "done" and (final.get("elapsed_sec") or 0) > 0:
            rec["status"] = "done"
            rec["wall_sec"] = round(float(final["elapsed_sec"]), 1)
            rec["reason"] = ""
        elif status == "done":
            rec["status"], rec["reason"] = "failed", "the render finished without a time"
        elif status in ("cancelled", "stopped") or self._cancel.is_set():
            rec["status"], rec["reason"] = "cancelled", "stopped"
        else:
            rec["status"] = "failed"
            rec["reason"] = str((final or {}).get("error") or (
                "the step left the queue before it finished" if final is None
                else "the render did not finish"))[:300]
        self._set_step(idx, status=rec["status"], wall_sec=rec["wall_sec"], reason=rec["reason"])


# ---- copy ----------------------------------------------------------------------
# Strings the SERVER renders (the card and the copied text). The browser's
# strings live in webapp/index.html and webapp/js/bench.js. Written by Codex
# (today-2026-10-22/bench/codex/), fact-checked against this module.
COPY = {
    "copy_results_header": "Phosphene Bench PB1 results",
    "result_incomplete": "Incomplete: a core step did not finish. This run cannot go on the leaderboard.",
    "card_headline_label": "LTX-2.5 Balanced · 5-second video with sound",
    "card_footer": "Phosphene Bench PB1 · free, local AI on your Mac · phosphene.video/bench",
}


# ---- the result card -------------------------------------------------------------

_FONT_DIRS = ("/System/Library/Fonts",)
_BG = (0, 6, 26)
_PANEL = (12, 19, 48)
_TEXT = (240, 244, 251)
_MUTED = (182, 191, 209)
_FAINT = (110, 120, 150)
_PINK, _PURPLE, _CYAN = (255, 46, 159), (177, 74, 255), (94, 234, 255)
_AMBER = (210, 153, 34)


def _font(size: int, weight: str = "Regular", mono: bool = False):
    from PIL import ImageFont                                  # noqa: PLC0415
    name = "SFNSMono.ttf" if mono else "SFNS.ttf"
    for d in _FONT_DIRS:
        p = Path(d) / name
        if p.is_file():
            try:
                f = ImageFont.truetype(str(p), size)
                try:
                    f.set_variation_by_name(weight)
                except Exception:                           # noqa: BLE001
                    pass
                return f
            except OSError:
                continue
    try:
        return ImageFont.load_default(size=size)
    except TypeError:                                        # Pillow < 10.1
        return ImageFont.load_default()


def _gradient(w: int, h: int):
    """Pink -> purple -> cyan, left to right: the mark's three rings."""
    from PIL import Image                                      # noqa: PLC0415
    g = Image.new("RGB", (w, 1))
    px = g.load()
    for x in range(w):
        t = x / max(1, w - 1)
        a, b, u = ((_PINK, _PURPLE, t / 0.5) if t < 0.5 else (_PURPLE, _CYAN, (t - 0.5) / 0.5))
        px[x, 0] = tuple(int(a[i] + (b[i] - a[i]) * u) for i in range(3))
    return g.resize((w, h))


def render_card(doc: dict, out_path, mark_path=None, scale: int = 2) -> Path:
    """The shareable PNG. 1600×900 points, drawn at 2× (3200×1800 px).

    Every number on it comes from the result document — the card cannot say
    anything the JSON does not."""
    from PIL import Image, ImageDraw, ImageFilter              # noqa: PLC0415

    W, H = 1600 * scale, 900 * scale
    S = scale

    def s(v):
        return int(round(v * S))

    img = Image.new("RGB", (W, H), _BG)
    # A soft blue wash from the top, like the panel's own body background.
    wash = Image.new("L", (W, H), 0)
    ImageDraw.Draw(wash).ellipse((s(-200), s(-700), s(1800), s(420)), fill=40)
    wash = wash.filter(ImageFilter.GaussianBlur(s(140)))
    img.paste(Image.new("RGB", (W, H), (47, 129, 247)), (0, 0), wash)

    mark = None
    mp = Path(mark_path) if mark_path else Path(__file__).resolve().parent / "assets" / "phosphene_mark_square.png"
    if mp.is_file():
        try:
            mark = Image.open(mp).convert("RGBA")
        except OSError:
            mark = None
    if mark is not None:
        # The mark, huge and faint, bleeding off the right edge.
        # Centred behind the step panel, which is opaque, so only the outer
        # rings show around it (the yellow core stays hidden).
        big = mark.resize((s(1180), s(1180)), Image.LANCZOS)
        lum = big.convert("L").point(lambda v: 255 if v > 24 else 0)
        alpha = lum.point(lambda a: int(a * 0.13))
        img.paste(big.convert("RGB"), (s(1188 - 590), s(505 - 590)), alpha)

    d = ImageDraw.Draw(img)
    mac, app, cond, summ = doc["mac"], doc["app"], doc["conditions"], doc["summary"]
    steps = {st["id"]: st for st in doc["steps"]}
    X0 = s(84)

    # Header: mark + wordmark + suite pill, version on the right.
    if mark is not None:
        small = mark.resize((s(56), s(56)), Image.LANCZOS)
        circle = Image.new("L", small.size, 0)
        ImageDraw.Draw(circle).ellipse((0, 0, small.size[0] - 1, small.size[1] - 1), fill=255)
        img.paste(small.convert("RGB"), (X0, s(64)), circle)
    f_brand = _font(s(30), "Semibold")
    d.text((X0 + s(72), s(76)), "Phosphene Bench", font=f_brand, fill=_TEXT)
    bw = d.textlength("Phosphene Bench", font=f_brand)
    pill_x = X0 + s(72) + bw + s(16)
    f_pill = _font(s(17), "Semibold", mono=True)
    pill_txt = f"{doc['suite']['id']} · {doc['suite']['fingerprint'][:6]}"
    pw = d.textlength(pill_txt, font=f_pill)
    d.rounded_rectangle((pill_x, s(78), pill_x + pw + s(24), s(110)), radius=s(16),
                        outline=(61, 71, 122), width=max(1, S), fill=(19, 27, 63))
    d.text((pill_x + s(12), s(84)), pill_txt, font=f_pill, fill=_CYAN)
    f_meta = _font(s(18), "Regular", mono=True)
    ver = f"Phosphene {app['version']} · {app['edition']}"
    d.text((W - X0 - d.textlength(ver, font=f_meta), s(84)), ver, font=f_meta, fill=_MUTED)

    # The Mac.
    f_chip = _font(s(64), "Bold")
    d.text((X0, s(164)), mac["chip"], font=f_chip, fill=_TEXT)
    cores = mac.get("cpu_cores") or {}
    cpu = (cores.get("performance") or 0) + (cores.get("efficiency") or 0)
    spec = " · ".join(x for x in (
        f"{mac['gpu_cores']}-core GPU" if mac.get("gpu_cores") else "",
        f"{cpu}-core CPU" if cpu else "",
        f"{mac['ram_gb']} GB" if mac.get("ram_gb") else "",
        f"macOS {mac['macos']}",
        mac.get("model_id") or "") if x)
    d.text((X0, s(248)), spec, font=_font(s(24), "Regular"), fill=_MUTED)

    # Headline: the Balanced 5 s time, in the mark's gradient.
    d.text((X0, s(330)), COPY["card_headline_label"], font=_font(s(20), "Semibold"),
           fill=_MUTED)
    head = steps.get(HEADLINE_STEP) or {}
    head_txt = fmt_sec(head.get("wall_sec")) if head.get("status") == "done" else "—"
    f_big = _font(s(150), "Bold")
    bbox = d.textbbox((0, 0), head_txt, font=f_big)
    tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
    mask = Image.new("L", (tw + s(8), th + s(8)), 0)
    ImageDraw.Draw(mask).text((-bbox[0], -bbox[1]), head_txt, font=f_big, fill=255)
    img.paste(_gradient(mask.size[0], mask.size[1]), (X0, s(372)), mask)
    canvas_note = head.get("canvas") or ""
    if canvas_note:
        d.text((X0, s(372) + th + s(28)), f"{canvas_note} · 121 frames · 24 fps",
               font=_font(s(20), "Regular", mono=True), fill=_MUTED)
    if summ.get("core_total_sec"):
        peaks = [st["peak_mem_gb"] for st in doc["steps"]
                 if st.get("core") and st["status"] == "done" and st.get("peak_mem_gb") is not None]
        tot = f"Core suite {fmt_sec(summ['core_total_sec'])}"
        if peaks:
            tot += f"  ·  peak {max(peaks)} GB in use"
        y_tot = s(372) + th + s(84)
        d.rounded_rectangle((X0, y_tot, X0 + d.textlength(tot, font=_font(s(22), "Semibold")) + s(40),
                             y_tot + s(48)), radius=s(24), fill=(19, 27, 63), outline=(61, 71, 122),
                            width=max(1, S))
        d.text((X0 + s(20), y_tot + s(10)), tot, font=_font(s(22), "Semibold"), fill=_TEXT)

    # Step table (right column).
    tx, ty, tw_col = s(860), s(330), s(656)
    d.rounded_rectangle((tx - s(28), ty - s(26), tx + tw_col, ty + s(380)), radius=s(22),
                        fill=_PANEL, outline=(36, 45, 92), width=max(1, S))
    f_row = _font(s(22), "Semibold")
    f_sub = _font(s(16), "Regular")
    f_time = _font(s(28), "Semibold")
    timed = [st for st in doc["steps"] if st.get("timed")]
    done_times = [st["wall_sec"] for st in timed if st["status"] == "done" and st.get("wall_sec")]
    tmax = max(done_times) if done_times else 1.0
    y = ty
    for st in timed:
        label = st["label"]
        d.text((tx, y), label, font=f_row, fill=_TEXT if st["core"] else _MUTED)
        if st["status"] == "done":
            t = fmt_sec(st["wall_sec"])
            sub = " · ".join(x for x in (
                st.get("canvas") or "",
                f"peak {st['peak_mem_gb']} GB in use" if st.get("peak_mem_gb") is not None else "",
                "optional" if not st["core"] else "") if x)
            col = _TEXT
        else:
            t = {"skipped": "not run", "failed": "failed", "cancelled": "stopped"}.get(st["status"], st["status"])
            sub = "optional extra" if not st["core"] else (st.get("reason") or "")[:60]
            col = _FAINT if st["status"] == "skipped" else _AMBER
        tw_ = d.textlength(t, font=f_time)
        d.text((tx + tw_col - s(28) - tw_, y - s(2)), t, font=f_time, fill=col)
        d.text((tx, y + s(32)), sub, font=f_sub, fill=_FAINT)
        # Bar: the share of the slowest timed step.
        by = y + s(60)
        d.rounded_rectangle((tx, by, tx + tw_col - s(28), by + s(6)), radius=s(3), fill=(29, 39, 82))
        if st["status"] == "done" and st.get("wall_sec"):
            frac = max(0.02, min(1.0, float(st["wall_sec"]) / tmax))
            bar = _gradient(max(1, int((tw_col - s(28)) * frac)), s(6))
            m = Image.new("L", bar.size, 0)
            ImageDraw.Draw(m).rounded_rectangle((0, 0, bar.size[0] - 1, bar.size[1] - 1), radius=s(3), fill=255)
            img.paste(bar, (tx, by), m)
        y += s(92)

    # Conditions + footer.
    f_foot = _font(s(17), "Regular", mono=True)
    warm = cond.get("warmup_sec")
    cond_line = " · ".join((
        {"ac": "On charger", "battery": "On battery", "unknown": "Power not reported"}[cond["power"]],
        f"Low Power Mode {'on' if cond.get('low_power_mode') else 'off'}",
        f"thermal {_THERMAL_WORDS.get(cond['thermal_worst'])}",
        f"warm-up {fmt_sec(warm)} untimed",
    ))
    d.text((X0, s(760)), cond_line, font=f_foot, fill=_MUTED)
    status_txt = ("Complete run" if summ["complete"] else "INCOMPLETE run: not comparable")
    d.text((X0, s(792)), f"{status_txt} · run {doc['run_id']} · {doc['finished_at'][:10]}",
           font=f_foot, fill=_MUTED if summ["complete"] else _AMBER)
    d.line((X0, s(838), W - X0, s(838)), fill=(36, 45, 92), width=max(1, S))
    d.text((X0, s(852)), COPY["card_footer"], font=_font(s(18), "Medium"), fill=_TEXT)
    out = Path(out_path)
    out.parent.mkdir(parents=True, exist_ok=True)
    img.save(out, "PNG", optimize=True)
    return out