frames

#!/usr/bin/env python3
"""frames — Apple Frames CLI

Frame device screenshots with Apple product bezels. Auto-detects devices from
screenshot dimensions, applies colored frames with masks, merges multiple
screenshots side by side. Replicates Apple Frames shortcut functionality for
use in terminal workflows and AI agent pipelines.

Assets default to the Apple Frames Shortcuts location on macOS and standard
app data directories elsewhere.
"""

import argparse
import json
import math
import os
import random
import re
import shutil
import ssl
import stat
import subprocess
import sys
import tempfile
import warnings
from functools import lru_cache
from pathlib import Path, PurePosixPath

try:
    from PIL import Image, UnidentifiedImageError
except ImportError:
    print("Error: Pillow is required. Install with: pip3 install Pillow", file=sys.stderr)
    sys.exit(1)

warnings.simplefilter("error", Image.DecompressionBombWarning)

VERSION = "1.5.1"
APP_NAME = "frames"
HOME = Path.home()
CONFIG_DIR = HOME / ".config" / "frames"
CONFIG_FILE = CONFIG_DIR / "config.json"
ASSETS_URL = "https://cdn.macstories.net/images/uploads/2026/09/30/appleframes402-1790756136687-572a1ccddd.zip"
ASSETS_MIN_VERSION = 4
# Newest devices in the standard pack, each with a frame that proves it is
# installed; doctor suggests updating packs that lack any of them.
LATEST_PACK_FRAMES = {"iPhone 18 Pro": "iPhone 18 Pro Portrait", "iPhone Duo": "iPhone Duo Outer Open"}
LARGE_IMAGE_WARN_DIMENSION = 20000
LARGE_IMAGE_MAX_DIMENSION = 50000
VALID_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".heic", ".tiff", ".webp"}
VALID_VIDEO_EXTS = {".mp4", ".mov", ".m4v"}
MIN_FFMPEG_VERSION = (5, 1)
DEFAULT_VIDEO_PRESET = "best"
VIDEO_PRESETS = {
    "compact": {
        "h264_bitrate": "6M",
        "hevc_bitrate": "4M",
        "h264_crf": 24,
        "hevc_crf": 28,
    },
    "balanced": {
        "h264_bitrate": "10M",
        "hevc_bitrate": "7M",
        "h264_crf": 20,
        "hevc_crf": 24,
    },
    "best": {
        "h264_bitrate": "16M",
        "hevc_bitrate": "10M",
        "h264_crf": 18,
        "hevc_crf": 20,
    },
}
VIDEO_ROTATIONS = {
    "none": None,
    "clockwise": "transpose=1",
    "counterclockwise": "transpose=2",
    "180": "hflip,vflip",
}


def get_shortcuts_assets_dir(home=None):
    """Return the Apple Frames Shortcuts asset location on macOS."""
    home = Path(home) if home is not None else HOME
    return home / "Library/Mobile Documents/iCloud~is~workflow~my~workflows/Documents/Frames"


def get_app_data_assets_dir(home=None, platform=None, environ=None):
    """Return the standard per-platform app data assets directory."""
    home = Path(home) if home is not None else HOME
    platform = platform or sys.platform
    environ = environ or os.environ

    if platform == "darwin":
        return Path(environ.get("FRAMES_DATA_HOME", home / "Library/Application Support")) / APP_NAME / "assets"
    if platform.startswith("win"):
        return Path(environ.get("LOCALAPPDATA", home / "AppData/Local")) / APP_NAME / "assets"
    return Path(environ.get("XDG_DATA_HOME", home / ".local/share")) / APP_NAME / "assets"


def get_default_assets_dir(home=None, platform=None, environ=None):
    """Return the preferred default assets directory for the current platform."""
    platform = platform or sys.platform
    if platform == "darwin":
        return get_shortcuts_assets_dir(home)
    return get_app_data_assets_dir(home, platform, environ)


SHORTCUTS_ASSETS = get_shortcuts_assets_dir()
APPDATA_ASSETS = get_app_data_assets_dir()
DEFAULT_ASSETS = get_default_assets_dir()


def _expand_path(path_value):
    return Path(path_value).expanduser()


def read_config_file():
    """Read and validate config, returning the data or an actionable error."""
    if not CONFIG_FILE.exists():
        return None, None
    try:
        with open(CONFIG_FILE, encoding="utf-8") as f:
            config = json.load(f)
        if not isinstance(config, dict):
            raise ValueError("Config must contain a JSON object.")
        if "assets_path" in config:
            assets_path = config["assets_path"]
            if not isinstance(assets_path, str) or not assets_path.strip():
                raise ValueError("assets_path must be a non-empty path string.")
        if "default_colors" in config and not isinstance(config["default_colors"], dict):
            raise ValueError("default_colors must be an object mapping devices to colors.")
        if "use_subfolder" in config:
            subfolder = config["use_subfolder"]
            if isinstance(subfolder, str):
                validate_subfolder_name(subfolder)
            elif not isinstance(subfolder, bool):
                raise ValueError("use_subfolder must be true, false, or a directory name.")
        return config, None
    except (ValueError, OSError) as e:
        return None, str(e)


def validate_subfolder_name(name):
    """Allow only a single relative directory component for --subfolder."""
    candidate = str(name).strip()
    if not candidate:
        raise ValueError("Subfolder name cannot be empty.")

    pure = PurePosixPath(candidate.replace("\\", "/"))
    if pure.is_absolute() or len(pure.parts) != 1 or pure.parts[0] in {".", ".."}:
        raise ValueError(
            "Subfolder must be a single directory name without path separators or '..'."
        )

    return pure.parts[0]


def resolve_assets_dir(args_assets=None, config=None):
    """Resolve assets directory and report which source won."""
    if args_assets is not None:
        return _expand_path(args_assets), "--assets"
    env = os.environ.get("FRAMES_ASSETS")
    if env:
        return _expand_path(env), "FRAMES_ASSETS"
    config = load_config() if config is None else config
    if "assets_path" in config:
        return _expand_path(config["assets_path"]), "config"
    if check_assets_version(DEFAULT_ASSETS)[0]:
        return DEFAULT_ASSETS, "default"
    if DEFAULT_ASSETS != APPDATA_ASSETS and check_assets_version(APPDATA_ASSETS)[0]:
        return APPDATA_ASSETS, "app-data"
    return DEFAULT_ASSETS, "default"


def get_assets_dir(args_assets=None):
    """Resolve assets directory: CLI flag > env var > config file > default."""
    return resolve_assets_dir(args_assets)[0]

def get_subfolder_setting(args, config=None):
    """Get subfolder name if enabled. Returns folder name string or None.
    CLI flag > config > default (None). -f alone = 'framed', -f custom = 'custom'."""
    if hasattr(args, 'subfolder') and args.subfolder is not None:
        return validate_subfolder_name(args.subfolder)
    cfg = config if config is not None else load_config()
    sub = cfg.get("use_subfolder", False)
    if sub is True:
        return "framed"
    elif isinstance(sub, str):
        return validate_subfolder_name(sub)
    return None

# ── Asset Management ────────────────────────────────────────────────────────

def check_assets_version(assets_dir):
    """Check if assets directory has valid Apple Frames 4+ assets.
    Returns (ok, version_or_none)."""
    assets_dir = Path(assets_dir)
    json_path = assets_dir / "NewFrames.json"

    if not assets_dir.exists() or not json_path.exists():
        return False, None

    version_path = assets_dir / "version.txt"
    if version_path.exists():
        try:
            ver = version_path.read_text(encoding="utf-8").strip().split('\n')[0].strip()
            major = int(ver.split('.')[0])
            return major >= ASSETS_MIN_VERSION, major
        except (ValueError, OSError):
            pass

    # No version.txt — check for v4 indicators in JSON
    try:
        with open(json_path, encoding="utf-8") as f:
            data = json.load(f)
        if isinstance(data, dict) and "variants" in data:
            return True, 4
        return False, None
    except (json.JSONDecodeError, UnicodeError, OSError):
        return False, None


def _zip_member_is_symlink(member):
    unix_mode = member.external_attr >> 16
    return stat.S_ISLNK(unix_mode)


def _iter_safe_zip_members(zip_file):
    members = []
    top_items = set()

    for member in zip_file.infolist():
        filename = member.filename.replace("\\", "/")
        if not filename or filename.startswith("__MACOSX/"):
            continue
        members.append((member, filename))
        top_items.add(filename.split("/", 1)[0])

    prefix = ""
    if len(top_items) == 1:
        prefix = next(iter(top_items)) + "/"

    for member, filename in members:
        relative_name = filename
        if prefix and relative_name.startswith(prefix):
            relative_name = relative_name[len(prefix):]
        if not relative_name:
            continue

        relative_path = PurePosixPath(relative_name)
        if relative_path.is_absolute() or ".." in relative_path.parts:
            raise ValueError(f"Archive contains unsafe path: {filename}")
        if _zip_member_is_symlink(member):
            raise ValueError(f"Archive contains unsupported symlink: {filename}")

        yield member, relative_path


def _extract_zip_to_dir(zip_file, destination):
    for member, relative_path in _iter_safe_zip_members(zip_file):
        target = destination.joinpath(*relative_path.parts)
        if member.is_dir():
            target.mkdir(parents=True, exist_ok=True)
            continue

        target.parent.mkdir(parents=True, exist_ok=True)
        with zip_file.open(member) as src, open(target, "wb") as dst:
            shutil.copyfileobj(src, dst)


def _find_assets_root(path):
    json_path = path / "NewFrames.json"
    if json_path.exists():
        return path
    found = list(path.rglob("NewFrames.json"))
    if found:
        return found[0].parent
    return None

def _is_ssl_download_error(exc):
    reason = getattr(exc, "reason", exc)
    if isinstance(reason, ssl.SSLError):
        return True

    text = str(reason).lower()
    ssl_markers = (
        "certificate verify failed",
        "self-signed certificate",
        "tlsv1 alert",
        "ssl:",
    )
    return any(marker in text for marker in ssl_markers)

def _download_with_urllib(tmp_path, reporthook):
    import urllib.request

    urllib.request.urlretrieve(ASSETS_URL, tmp_path, reporthook=reporthook)

def _download_with_curl(tmp_path, curl_path=None):
    curl_path = curl_path or shutil.which("curl")
    if curl_path is None:
        raise FileNotFoundError("curl is not installed")

    result = subprocess.run(
        [curl_path, "--location", "--fail", "--progress-bar", "--show-error", "-o", tmp_path, ASSETS_URL],
        check=False,
    )
    if result.returncode != 0:
        raise OSError(f"curl download failed with exit code {result.returncode}")

def download_assets(dest_dir):
    """Download and extract Apple Frames 4 assets. Returns True on success."""
    import urllib.request, urllib.error, zipfile

    dest_dir = Path(dest_dir)

    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
        tmp_path = tmp.name

    try:
        def progress(block_num, block_size, total_size):
            if total_size > 0:
                pct = min(100, int(block_num * block_size * 100 / total_size))
                filled = int(25 * pct / 100)
                bar = '\u2588' * filled + '\u2591' * (25 - filled)
                mb = total_size / (1024 * 1024)
                print(f"\r  Downloading [{C.rgb(232,114,42, bar)}] {pct}% of {mb:.0f} MB ", end="", flush=True)

        print(f"  {C.dim('Connecting to cdn.macstories.net...')}", flush=True)
        try:
            _download_with_urllib(tmp_path, progress)
            print()
        except urllib.error.URLError as e:
            if not _is_ssl_download_error(e):
                raise

            curl_path = shutil.which("curl")
            if curl_path is None:
                raise

            print()
            print(f"  {C.dim('Python SSL verification failed; retrying with curl...')}", flush=True)
            _download_with_curl(tmp_path, curl_path=curl_path)
            print()

        print(f"  {C.dim('Extracting...')}", end=" ", flush=True)
        with tempfile.TemporaryDirectory(prefix="frames-assets-") as stage_dir:
            stage_path = Path(stage_dir)
            with zipfile.ZipFile(tmp_path, "r") as zf:
                _extract_zip_to_dir(zf, stage_path)

            source_root = _find_assets_root(stage_path)
            if source_root is None:
                print(C.red('failed'))
                print(f"  {C.red('Error')}: NewFrames.json not found in archive.", file=sys.stderr)
                return False

            dest_dir.mkdir(parents=True, exist_ok=True)
            for item in source_root.iterdir():
                target = dest_dir / item.name
                if item.is_dir():
                    shutil.copytree(item, target, dirs_exist_ok=True)
                else:
                    shutil.copy2(item, target)

        pngs = list(dest_dir.glob("*.png"))
        print(C.green('done!'))
        print(f"  {C.bold(str(len(pngs)))} frame assets installed")
        return True

    except urllib.error.URLError as e:
        print(f"\n  {C.red('Download failed')}: {e.reason}", file=sys.stderr)
        return False
    except zipfile.BadZipFile:
        print(f"\n  {C.red('Error')}: Downloaded file is corrupted.", file=sys.stderr)
        return False
    except ValueError as e:
        print(C.red("failed"))
        print(f"  {C.red('Error')}: {e}", file=sys.stderr)
        return False
    except OSError as e:
        print(f"\n  {C.red('Error')}: {e}", file=sys.stderr)
        return False
    finally:
        try:
            os.unlink(tmp_path)
        except OSError:
            pass

def guided_setup(reason=None):
    """Interactive guided setup — download and install Apple Frames 4 assets.
    Returns True on success, False if cancelled or failed."""
    default_path = get_default_assets_dir()
    short_default = str(default_path).replace(str(HOME), "~")

    print()
    if reason:
        print(f"  {C.bold('Apple Frames 4')} assets {reason}.")
    else:
        print(f"  {C.bold('Apple Frames 4')} asset setup")
    print()
    print(f"  Download device frames from {C.cyan('cdn.macstories.net')}? (~60 MB)")
    print()
    print(f"  Install to {C.cyan(short_default)}")
    print()
    print(f"  {C.bold('Enter')} {C.dim('to confirm  |')}  {C.bold('q')} {C.dim('to cancel  |  or type a different path')}")
    print()

    try:
        choice = input(f"  {C.bold('›')} ").strip()
    except (EOFError, KeyboardInterrupt):
        print(f"\n\n  {C.dim('Cancelled.')}\n")
        return False

    if choice.lower() in ('q', 'quit', 'n', 'no'):
        print(f"\n  {C.dim('Cancelled.')}\n")
        return False

    dest = Path(choice).expanduser().resolve() if choice else default_path

    print()
    if not download_assets(dest):
        return False

    config = load_config()
    config["assets_path"] = str(dest)
    save_config(config)

    short_dest = str(dest).replace(str(HOME), "~")
    print()
    print(f"  {C.green('Setup complete!')}")
    print(f"  {C.bold('Assets:')}  {short_dest}")
    print(f"  {C.bold('Config:')}  {CONFIG_FILE}")
    offer_video_tools_setup()
    print()
    print(f"  {C.dim('Run')} {C.cyan('frames')} screenshot.png {C.dim('to get started.')}")
    print()
    return True

# ── Color System ─────────────────────────────────────────────────────────────

class C:
    """ANSI color helpers. Respects NO_COLOR env and --no-color flag."""
    enabled = True

    @staticmethod
    def _c(code, text):
        return f"\033[{code}m{text}\033[0m" if C.enabled else str(text)

    @staticmethod
    def red(t):     return C._c("31", t)
    @staticmethod
    def green(t):   return C._c("32", t)
    @staticmethod
    def yellow(t):  return C._c("33", t)
    @staticmethod
    def blue(t):    return C._c("34", t)
    @staticmethod
    def magenta(t): return C._c("35", t)
    @staticmethod
    def cyan(t):    return C._c("36", t)
    @staticmethod
    def dim(t):     return C._c("2", t)
    @staticmethod
    def bold(t):    return C._c("1", t)
    @staticmethod
    def rgb(r, g, b, t):
        return f"\033[38;2;{r};{g};{b}m{t}\033[0m" if C.enabled else str(t)

# ── Splash Screen ────────────────────────────────────────────────────────────

LOGO_LINES = [
    r" █████  ██████  ██████  ██      ███████ ",
    r"██   ██ ██   ██ ██   ██ ██      ██      ",
    r"███████ ██████  ██████  ██      █████   ",
    r"██   ██ ██      ██      ██      ██      ",
    r"██   ██ ██      ██      ███████ ███████ ",
    r"",
    r"███████ ██████   █████  ███    ███ ███████ ███████ ",
    r"██      ██   ██ ██   ██ ████  ████ ██      ██      ",
    r"█████   ██████  ███████ ██ ████ ██ █████   ███████ ",
    r"██      ██   ██ ██   ██ ██  ██  ██ ██           ██ ",
    r"██      ██   ██ ██   ██ ██      ██ ███████ ███████ ",
]

LOGO_COLORS = [
    (232, 114, 42),   # Cosmic Orange
    (235, 125, 50),
    (238, 136, 58),
    (235, 125, 50),
    (232, 114, 42),
    (0, 0, 0),
    (232, 114, 42),
    (235, 125, 50),
    (238, 136, 58),
    (235, 125, 50),
    (232, 114, 42),
]

def show_splash():
    """Display colored ASCII art splash screen."""
    print()
    for line, (r, g, b) in zip(LOGO_LINES, LOGO_COLORS):
        if line:
            print(f"  {C.rgb(r, g, b, line)}")
        else:
            print()

    ver = C.dim(f"v{VERSION}")
    author = C.dim("by Federico Viticci")
    print(f"\n  {C.bold('Apple Frames CLI')} {ver}  {author}")
    print(f"  {C.dim('Frame screenshots and videos with Apple device bezels')}\n")
    print(f"  {C.dim('Quick start:')}")
    examples = [
        ("screenshot.png", "Frame a screenshot"),
        ("*.png", "Frame all PNGs in directory"),
        ("-m *.png", "Merge side by side (proportional)"),
        ("-b 3 *.png", "Merge in batches of 3"),
        ("-m --no-scale *.png", "Merge without proportional scaling"),
        ("-c random *.png", "Random frame colors"),
        ("video recording.mp4", "Frame video on white background"),
        ("video --codec hevc-alpha clip.mp4", "Smaller transparent MOV (macOS)"),
        ("video-info clip.mp4", "Inspect video match first"),
        ("video -m 1.mp4 2.mp4", "Merge framed videos"),
        ("~/Screenshots/", "Frame all images in a folder"),
        ("-f *.png", "Save to /framed/ subfolder"),
        ("--subfolder mockups *.png", "Save to custom subfolder"),
        ("info shot.png", "Identify device, colors, variants"),
        ("info ~/Screenshots/", "Scan folder for device matches"),
        ("colors", "Pick default colors per device"),
        ("list", "Show supported devices"),
        ("setup", "Download + configure assets"),
    ]
    width = max(len(command) for command, _ in examples)
    for command, description in examples:
        print(f"    {C.cyan('frames')} {command:<{width}}  {C.dim(description)}")
    print(f"  More options: {C.cyan('frames frame --help')} | {C.cyan('frames video --help')}")
    print()

    # Show asset status
    assets_dir = get_assets_dir()
    ok, ver = check_assets_version(assets_dir)
    if ok:
        short = str(assets_dir).replace(str(HOME), "~")
        pngs = len(list(assets_dir.glob("*.png")))
        print(f"  {C.green('Assets installed')} {C.dim(f'(v{ver}, {pngs} frames)')}")
        print(f"  {C.dim(short)}")
    else:
        print(f"  {C.yellow('Assets not installed.')} Run {C.cyan('frames setup')} to download device frames.")
    print()

# ── Frame Colors Dictionary ──────────────────────────────────────────────────

FRAME_COLORS = {
    "iPhone Duo Outer Portrait":   ["Night Sky", "Star White"],
    "iPhone Duo Outer Landscape":  ["Night Sky", "Star White"],
    "iPhone Duo Inner Portrait":   ["Night Sky", "Star White"],
    "iPhone Duo Inner Landscape":  ["Night Sky", "Star White"],
    "iPhone Duo Outer Open":       ["Night Sky", "Star White"],
    "iPhone 18 Pro Portrait":      ["Burgundy", "Glacier", "Silver", "Black"],
    "iPhone 18 Pro Landscape":     ["Burgundy", "Glacier", "Silver", "Black"],
    "iPhone 18 Pro Max Portrait":  ["Burgundy", "Glacier", "Silver", "Black"],
    "iPhone 18 Pro Max Landscape": ["Burgundy", "Glacier", "Silver", "Black"],
    "iPhone 17 Pro Portrait":      ["Cosmic Orange", "Deep Blue", "Silver"],
    "iPhone 17 Pro Landscape":     ["Cosmic Orange", "Deep Blue", "Silver"],
    "iPhone 17 Pro Max Portrait":  ["Cosmic Orange", "Deep Blue", "Silver"],
    "iPhone 17 Pro Max Landscape": ["Cosmic Orange", "Deep Blue", "Silver"],
    "iPhone 17 Portrait":          ["Black", "Lavender", "Mist Blue", "Sage", "White"],
    "iPhone 17 Landscape":         ["Black", "Lavender", "Mist Blue", "Sage", "White"],
    "iPhone Air Portrait":         ["Black", "White", "Gold", "Blue"],
    "iPhone Air Landscape":        ["Black", "White", "Gold", "Blue"],
    "MacBook Pro M5 14":           ["Silver", "Space Black"],
    "MacBook Pro M5 16":           ["Silver", "Space Black"],
    "MacBook Neo":                 ["Blush", "Citrus", "Indigo", "Silver"],
    "iPhone 16 Pro Portrait":      ["Natural", "Desert", "Black", "White"],
    "iPhone 16 Pro Landscape":     ["Natural", "Desert", "Black", "White"],
    "iPhone 16 Pro Max Portrait":  ["White", "Desert", "Natural", "Black"],
    "iPhone 16 Pro Max Landscape": ["Black", "Desert", "Natural", "White"],
    "iPhone 16 Portrait":          ["Ultramarine", "Teal", "Pink", "Black", "White"],
    "iPhone 16 Landscape":         ["Ultramarine", "Teal", "Pink", "Black", "White"],
    "iPhone 16 Plus Portrait":     ["Ultramarine", "White", "Teal", "Pink", "Black"],
    "iPhone 16 Plus Landscape":    ["Ultramarine", "Teal", "Pink", "Black", "White"],
    "Watch Ultra 3":               ["Black + Alpine Loop Black", "Black + Alpine Loop Light Blue", "Black + Milanese Loop", "Black + Ocean Band Anchor Blue", "Black + Ocean Band Black", "Black + Trail Loop Black Charcoal", "Natural + Alpine Loop Light Blue", "Natural + Alpine Loop Terra Cotta", "Natural + Milanese Loop", "Natural + Ocean Band Anchor Blue", "Natural + Ocean Band Neon Green", "Natural + Trail Loop Blue Bright Blue", "Natural + Trail Loop Green Neon"],
    "Watch Ultra 2024":            ["Orange Beige Trail Loop", "Blue Alpine Loop", "Orange Ocean Band", "Black + Alpine Loop Dark Green", "Black + Alpine Loop Navy", "Black + Alpine Loop Tan", "Black + Ocean Band Black", "Black + Ocean Band Ice Blue", "Black + Ocean Band Navy", "Black + Titanium Milanese Loop", "Black + Trail Loop Black", "Black + Trail Loop Blue", "Black + Trail Loop Green", "Natural + Alpine Loop Dark Green", "Natural + Alpine Loop Navy", "Natural + Alpine Loop Tan", "Natural + Ocean Band Black", "Natural + Ocean Band Ice Blue", "Natural + Ocean Band Navy", "Natural + Titanium Milanese Loop", "Natural + Trail Loop Black", "Natural + Trail Loop Blue"],
    "MacBook Air M5 13":           ["Midnight", "Silver", "Sky Blue", "Starlight"],
    "MacBook Air M5 15":           ["Midnight", "Silver", "Sky Blue", "Starlight"],
    "iMac M4":                     ["Silver", "Blue", "Green", "Orange", "Pink", "Purple", "Yellow"],
    "Studio Display":              ["Light", "Dark"],
    "Studio Display XDR":          ["Light", "Dark"],
    "Watch Series 11 42":           ["Aluminum Jet Black + Sport Band Black", "Aluminum Jet Black + Sport Loop Dark Gray", "Aluminum Rose Gold + Sport Band Light Blush", "Aluminum Rose Gold + Sport Loop Purple Fog", "Aluminum Silver + Sport Band Neon Yellow", "Aluminum Silver + Sport Band Purple Fog", "Aluminum Silver + Sport Loop Forest", "Aluminum Silver + Sport Loop Neon Yellow", "Aluminum Space Gray + Sport Band Anchor Blue", "Aluminum Space Gray + Sport Band Black", "Aluminum Space Gray + Sport Loop Anchor Blue", "Aluminum Space Gray + Sport Loop Forest", "Titanium Gold + Magnetic Link Sage Gray", "Titanium Gold + Milanese Loop", "Titanium Gold + Sport Band Light Blush", "Titanium Gold + Sport Band Purple Fog", "Titanium Natural + Magnetic Link Caramel", "Titanium Natural + Milanese Loop", "Titanium Natural + Sport Band Stone Gray", "Titanium Slate + Magnetic Link Navy", "Titanium Slate + Milanese Loop", "Titanium Slate + Sport Band Black"],
    "Watch Series 11 46":           ["Aluminum Jet Black + Sport Band Black", "Aluminum Jet Black + Sport Loop Dark Gray", "Aluminum Rose Gold + Sport Band Light Blush", "Aluminum Rose Gold + Sport Loop Purple Fog", "Aluminum Silver + Sport Band Neon Yellow", "Aluminum Silver + Sport Band Purple Fog", "Aluminum Silver + Sport Loop Forest", "Aluminum Silver + Sport Loop Neon Yellow", "Aluminum Space Gray + Sport Band Anchor Blue", "Aluminum Space Gray + Sport Band Black", "Aluminum Space Gray + Sport Loop Anchor Blue", "Aluminum Space Gray + Sport Loop Forest", "Titanium Gold + Magnetic Link Sage Gray", "Titanium Gold + Milanese Loop", "Titanium Gold + Sport Band Light Blush", "Titanium Gold + Sport Band Purple Fog", "Titanium Natural + Magnetic Link Caramel", "Titanium Natural + Milanese Loop", "Titanium Natural + Sport Band Stone Gray", "Titanium Slate + Magnetic Link Navy", "Titanium Slate + Milanese Loop", "Titanium Slate + Sport Band Black"],
}

# Frame Variants: the first entry installed in the asset pack is the default.
# Older packs without iPhone 18 Pro fall back to the next entry.
FRAME_VARIANTS = {
    "iPhone 17 Portrait":          ["iPhone 18 Pro Portrait", "iPhone 17 Pro Portrait", "iPhone 17 Portrait", "iPhone 16 Pro Portrait"],
    "iPhone 17 Landscape":         ["iPhone 18 Pro Landscape", "iPhone 17 Pro Landscape", "iPhone 17 Landscape", "iPhone 16 Pro Landscape"],
    "iPhone 17 Pro Max Portrait":  ["iPhone 18 Pro Max Portrait", "iPhone 17 Pro Max Portrait", "iPhone 16 Pro Max Portrait"],
    "iPhone 17 Pro Max Landscape": ["iPhone 18 Pro Max Landscape", "iPhone 17 Pro Max Landscape", "iPhone 16 Pro Max Landscape"],
    "iPhone 16 Portrait":          ["iPhone 16 Portrait", "iPhone 15 Pro Portrait"],
    "iPhone 16 Landscape":         ["iPhone 16 Landscape", "iPhone 15 Pro Landscape"],
    "iPhone 16 Plus Portrait":     ["iPhone 16 Plus Portrait", "iPhone 15 Pro Max Portrait"],
    "iPhone 16 Plus Landscape":    ["iPhone 16 Plus Landscape", "iPhone 15 Pro Max Landscape"],
    "MacBook Pro M5 14":           ["MacBook Pro M5 14", "MacBook Pro 2021 14"],
    "MacBook Pro M5 16":           ["MacBook Pro M5 16", "MacBook Pro 2021 16"],
    "MacBook Air M5 13":           ["MacBook Air M5 13", "MacBook Air 2022"],
    "Studio Display":              ["Studio Display", "Studio Display XDR"],
    "Watch Series 11 42":          ["Watch Series 11 42", "Watch Series 10 42"],
    "Watch Series 11 46":          ["Watch Series 11 46", "Watch Series 10 46"],
}

# Width keys the published NewFrames.json lacks even though the frame PNG ships.
# The pack's own entry wins if a later release adds one.
MISSING_DEVICE_ENTRIES = {
    # iPhone 12/13 mini screenshots are 1125x2436, scaled to the 1080x2340 panel.
    "1125": {
        "name": "iPhone 12-13 mini Portrait",
        "resizeWidth": 1080,
        "resizeHeight": 2340,
        "x": "80",
        "y": "80",
        "physicalHeight": 131.5,
    },
}

# ── Core Engine ──────────────────────────────────────────────────────────────

def load_json(assets_dir):
    """Load the device dictionary from NewFrames.json."""
    json_path = assets_dir / "NewFrames.json"
    if not json_path.exists():
        print(f"{C.red('Error')}: NewFrames.json not found at {json_path}", file=sys.stderr)
        sys.exit(1)
    try:
        with open(json_path, encoding="utf-8") as f:
            device_dict = json.load(f)
    except json.JSONDecodeError as e:
        print(f"{C.red('Error')}: Invalid JSON in {json_path}: {e}", file=sys.stderr)
        sys.exit(1)
    for key, entry in MISSING_DEVICE_ENTRIES.items():
        device_dict.setdefault(key, entry)
    return device_dict


def resize_target(entry, width, height):
    """Return the size an input is scaled to, or None when it already fits the opening."""
    resize_width = entry.get("resizeWidth")
    if not resize_width:
        return None
    resize_width = int(resize_width)
    resize_height = int(entry.get("resizeHeight", int(height * (resize_width / width))))
    if (resize_width, resize_height) == (width, height):
        return None
    return resize_width, resize_height

def detect_device_size(width, height, device_dict):
    """Detect device from dimensions using width + overlap height check."""
    w, h = width, height
    width_key = str(w)

    if width_key not in device_dict:
        return None, None

    entry = device_dict[width_key]

    # Check overlap (height disambiguation)
    if "overlap" in entry:
        height_key = str(h)
        if height_key in entry["overlap"]:
            entry = entry["overlap"][height_key]
        else:
            return None, None

    return entry, entry["name"]


def detect_device(img, device_dict):
    """Detect device from screenshot dimensions using width + overlap height check."""
    return detect_device_size(*img.size, device_dict)


def resolve_variant(model_name, device_dict):
    """Return the first installed variant, stopping at the primary match."""
    installed = device_dict.get("variants", {})
    for candidate in FRAME_VARIANTS.get(model_name, []):
        if candidate == model_name:
            break
        if candidate in installed:
            variant_data = installed[candidate]
            return variant_data, variant_data["name"]

    return None, model_name


def installed_variants(model_name, device_dict):
    """List the variants of a primary match that the asset pack can render."""
    installed = device_dict.get("variants", {})
    return [name for name in FRAME_VARIANTS.get(model_name, [])
            if name == model_name or name in installed]


def resolve_device_entry(width, height, device_dict, force_device=None, device_index=None, verbose=False):
    """Resolve dimensions or an explicit device into a final frame entry."""
    if force_device:
        entry = (device_index or build_device_name_index(device_dict)).get(force_device)
        if not entry:
            raise ValueError(f"Device '{force_device}' not found in dictionary")
        return entry, entry["name"], entry["name"], False

    entry, primary_name = detect_device_size(width, height, device_dict)
    if not entry:
        raise ValueError(
            f"Unknown device for {width}x{height} input. Use 'frames list' to see supported devices."
        )

    model_name = primary_name
    variant_data, resolved_name = resolve_variant(model_name, device_dict)
    is_variant = False
    if variant_data:
        entry = variant_data
        model_name = resolved_name
        is_variant = True
        if verbose:
            print(f"  {C.dim('Variant resolved:')} {model_name}", file=sys.stderr)

    return entry, model_name, primary_name, is_variant


def load_config():
    """Load user config from ~/.config/frames/config.json."""
    config, error = read_config_file()
    if error:
        raise ValueError(f"Invalid config at {CONFIG_FILE}: {error} Run 'frames doctor' for details.")
    return config if config is not None else {}

def save_config(config):
    """Save user config."""
    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
    with tempfile.NamedTemporaryFile("w", dir=CONFIG_DIR, delete=False, encoding="utf-8") as tmp:
        json.dump(config, tmp, indent=2)
        tmp.write("\n")
        tmp_path = Path(tmp.name)
    os.replace(tmp_path, CONFIG_FILE)


def get_color(model_name, color_arg, user_defaults=None, strict=False):
    """Resolve frame color for a device. Checks: CLI arg > user config > first in list."""
    if model_name not in FRAME_COLORS:
        return None

    colors = FRAME_COLORS[model_name]
    if not colors:
        return None

    if color_arg == "default":
        color_arg = None

    if color_arg == "random":
        return random.choice(colors)
    elif color_arg:
        for c in colors:
            if c.lower() == color_arg.lower():
                return c
        try:
            idx = int(color_arg) - 1
            if 0 <= idx < len(colors):
                return colors[idx]
        except ValueError:
            pass
        if strict:
            raise ValueError(f"Color '{color_arg}' not found for {model_name}.")
        print(f"{C.yellow('Warning')}: Color '{color_arg}' not found for {model_name}. Using default.", file=sys.stderr)

    # Check user config for saved default
    user_defaults = user_defaults or {}
    # Strip orientation for lookup (user sets "iPhone 17 Pro" not "iPhone 17 Pro Portrait")
    base = model_name.replace(" Portrait", "").replace(" Landscape", "")
    if base in user_defaults:
        saved = user_defaults[base]
        if saved in colors:
            return saved

    return colors[0]  # Fallback = first color


def parse_per_input_colors(colors_arg, count):
    """Parse comma-separated per-input colors and validate count."""
    if colors_arg is None:
        return None
    values = [part.strip() for part in colors_arg.split(",")]
    if any(not value for value in values):
        raise ValueError("--colors cannot contain empty values.")
    if len(values) != count:
        raise ValueError(f"--colors expected {count} values, got {len(values)}.")
    return values


def validate_color_args(args):
    if getattr(args, "color", None) and getattr(args, "colors", None):
        raise ValueError("--color and --colors cannot be used together.")


def color_arg_for_index(args, color_values, index):
    if color_values is not None:
        return color_values[index]
    return getattr(args, "color", None)


@lru_cache(maxsize=4)
def _load_rgba_asset_cached(path_str):
    # Keep two frame/mask pairs warm without retaining an entire device catalog.
    with Image.open(path_str) as image:
        return image.convert("RGBA")

def _frame_asset_path(assets_dir, model_name, color):
    """Resolve the colored frame path, falling back to the colorless asset."""
    if color:
        frame_path = assets_dir / f"{model_name} {color}.png"
        if not frame_path.exists():
            # Fall back to colorless
            frame_path = assets_dir / f"{model_name}.png"
    else:
        frame_path = assets_dir / f"{model_name}.png"
    return frame_path

def asset_is_sideways(model_name, size):
    """True for a Landscape frame or mask stored in portrait orientation.

    Apple Frames 4 ships the iPhone 12-13 and iPhone 15 Pro landscape frames this
    way; a 90° counterclockwise turn puts the notch on the left like other frames."""
    width, height = size
    return model_name.endswith(" Landscape") and height > width

def load_mask(assets_dir, model_name):
    """Load a read-only cached mask PNG if it exists."""
    mask_path = assets_dir / f"{model_name}_mask.png"
    if mask_path.exists():
        return _load_rgba_asset_cached(str(mask_path))
    return None

def apply_mask(screenshot, mask):
    """Apply mask to screenshot — black pixels in mask make screenshot transparent."""
    result = screenshot.copy()
    result.putalpha(mask.getchannel("R"))
    return result

def composite(screenshot, frame, x, y):
    """Alpha-composite: place screenshot on canvas, composite frame on top.
    Produces fully opaque output at semi-transparent bezel inner edges."""
    canvas = Image.new("RGBA", frame.size, (0, 0, 0, 0))
    canvas.paste(screenshot, (x, y))
    return Image.alpha_composite(canvas, frame)

def _body_rows(img):
    """Top and bottom rows of an image's visible pixels (the device, not its padding)."""
    box = img.getchannel("A").getbbox() if img.mode == "RGBA" else None
    return (box[1], box[3]) if box else (0, img.height)


def physical_scale_factors(bodies, physical_heights):
    """Scale factors that give every device the same pixels per millimeter.

    Each body is the (top, bottom) rows of the visible device. Apple pads frame
    canvases differently, so canvas heights would skew real-world proportions.
    The coarsest device keeps its size and the others scale down, never up."""
    px_per_mm = [(bottom - top) / ph for (top, bottom), ph in zip(bodies, physical_heights)]
    ref_ppm = min(px_per_mm)
    return [ref_ppm / ppm for ppm in px_per_mm]


def merge_images(images, spacing=60, physical_heights=None):
    """Merge multiple images horizontally with spacing.

    When physical_heights is provided and values differ, devices are scaled to
    their real-world proportions and bottom-aligned. Otherwise, images keep
    their size and are center-aligned."""
    if len(images) == 1:
        return images[0]

    do_scale = (
        physical_heights is not None
        and len(physical_heights) == len(images)
        and len(set(physical_heights)) > 1
    )

    if do_scale:
        bodies = [_body_rows(img) for img in images]
        scaled, body_bottoms = [], []
        for img, (_, bottom), scale in zip(images, bodies, physical_scale_factors(bodies, physical_heights)):
            if scale < 0.999:
                width = max(1, round(img.width * scale))
                height = max(1, round(img.height * scale))
                scale = height / img.height  # The rounded, effective scale.
                img = img.resize((width, height), Image.LANCZOS)
            else:
                scale = 1.0
            scaled.append(img)
            body_bottoms.append(round(bottom * scale))
        images = scaled
        # Align the devices themselves, not their differently padded canvases.
        offsets = [max(body_bottoms) - bottom for bottom in body_bottoms]
    else:
        tallest = max(img.height for img in images)
        offsets = [(tallest - img.height) // 2 for img in images]

    total_width = sum(img.width for img in images) + spacing * (len(images) - 1)
    max_height = max(offset + img.height for offset, img in zip(offsets, images))

    merged = Image.new("RGBA", (total_width, max_height), (0, 0, 0, 0))
    x_offset = 0
    for img, y_offset in zip(images, offsets):
        # Inputs occupy separate regions. Copy their alpha instead of applying it twice.
        merged.paste(img, (x_offset, y_offset))
        x_offset += img.width + spacing

    return merged

def ensure_output_dir(path):
    """Create output directory or raise a clean write error."""
    try:
        path.mkdir(parents=True, exist_ok=True)
    except OSError as e:
        raise OSError(f"Could not create output directory {path}: {e}") from e

def save_png(image, path):
    """Save a PNG or raise a clean write error."""
    try:
        image.save(path, "PNG")
    except OSError as e:
        raise OSError(f"Could not save {path}: {e}") from e

def guard_image_size(width, height, source):
    """Warn on very large images and reject extreme dimensions."""
    largest = max(width, height)
    if largest > LARGE_IMAGE_MAX_DIMENSION:
        raise ValueError(
            f"Refusing to process {source}: image dimensions exceed "
            f"{LARGE_IMAGE_MAX_DIMENSION}px ({width}x{height})."
        )
    if largest > LARGE_IMAGE_WARN_DIMENSION:
        print(
            f"{C.yellow('Warning')}: Large image {source} ({width}x{height}) "
            f"may use significant memory.",
            file=sys.stderr,
        )


def build_device_name_index(device_dict):
    """Build a name→device-entry lookup for exact --device matches."""
    index = {}
    for key, val in device_dict.items():
        if key == "variants":
            continue
        sub_entries = list(val.get("overlap", {}).values()) or [val]
        for entry in sub_entries:
            index[entry["name"]] = entry
    for name, entry in device_dict.get("variants", {}).items():
        index[name] = entry
    return index


def frame_screenshot(
    img_path,
    assets_dir,
    device_dict,
    color_arg=None,
    strict_color=False,
    force_device=None,
    verbose=False,
    user_defaults=None,
    device_index=None,
):
    """Frame a single screenshot. Returns (framed_image, device_info_dict) or raises."""
    with Image.open(img_path) as opened:
        w, h = opened.size
        guard_image_size(w, h, img_path)
        img = opened.convert("RGBA")

    entry, model_name, primary_name, is_variant = resolve_device_entry(
        w, h, device_dict,
        force_device=force_device,
        device_index=device_index,
        verbose=verbose,
    )

    # 3. Color
    has_colors = entry.get("colors") == "yes"
    color = get_color(model_name, color_arg, user_defaults=user_defaults, strict=strict_color) if has_colors else None

    # 4. Resize for an asset whose opening differs from the native screenshot.
    target = resize_target(entry, img.width, img.height)
    if target:
        img = img.resize(target, Image.LANCZOS)
        if verbose:
            print(f"  {C.dim('Resized:')} {w}x{h} → {target[0]}x{target[1]}", file=sys.stderr)

    # 5. Load frame
    frame_path = _frame_asset_path(assets_dir, model_name, color)
    if not frame_path.exists():
        raise FileNotFoundError(f"Frame asset not found: {frame_path}")
    # Compositing only reads the frame, so it can use the cached image directly.
    frame = _load_rgba_asset_cached(str(frame_path))
    if asset_is_sideways(model_name, frame.size):
        frame = frame.transpose(Image.ROTATE_90)

    # 6. Apply mask
    has_mask = entry.get("mask") == "yes"
    mask_missing = False
    if has_mask:
        mask = load_mask(assets_dir, model_name)
        if mask:
            if asset_is_sideways(model_name, mask.size):
                mask = mask.transpose(Image.ROTATE_90)
            # Ensure mask matches screenshot dimensions
            if mask.size != img.size:
                mask = mask.resize(img.size, Image.LANCZOS)
            img = apply_mask(img, mask)
            if verbose:
                print(f"  {C.dim('Mask applied')}", file=sys.stderr)
        else:
            mask_missing = True
            print(f"  {C.yellow('Warning')}: mask file missing for {model_name} "
                  f"(expected {model_name}_mask.png). Rendering without mask — "
                  f"corners may show screenshot bleed.", file=sys.stderr)

    # 7. Composite
    x, y = int(entry["x"]), int(entry["y"])
    result = composite(img, frame, x, y)

    info = {
        "source": str(img_path),
        "device": model_name,
        "primary_match": primary_name,
        "color": color,
        "dimensions": f"{w}x{h}",
        "frame_size": f"{result.width}x{result.height}",
        "resized": bool(target),
        "masked": has_mask and not mask_missing,
        "mask_missing": mask_missing,
        "physicalHeight": float(entry.get("physicalHeight", 0)),
        "is_variant": is_variant,
    }

    return result, info


# ── Video Engine ────────────────────────────────────────────────────────────

def _run_json_command(cmd):
    result = subprocess.run(cmd, text=True, capture_output=True, check=True)
    return json.loads(result.stdout)


def _parse_tool_version(tool, output):
    first = (output or "").splitlines()[0] if output else ""
    # Arch builds print "version n9.0.1" (git-describe tags), so allow an "n" prefix.
    match = re.search(r"\bversion\s+n?([0-9]+)(?:\.([0-9]+))?", first)
    token_match = re.search(r"\bversion\s+(\S+)", first)
    display = token_match.group(1) if token_match else "unknown"
    if not match:
        raise RuntimeError(f"Could not determine {tool} version from: {first or 'empty output'}")
    return (int(match.group(1)), int(match.group(2) or 0)), display


def require_ffmpeg_tools():
    missing = [tool for tool in ("ffmpeg", "ffprobe") if not shutil.which(tool)]
    if missing:
        raise RuntimeError(
            f"Missing required video tool(s): {', '.join(missing)}. "
            f"Install ffmpeg {MIN_FFMPEG_VERSION[0]}.{MIN_FFMPEG_VERSION[1]}+ "
            "and ensure ffmpeg and ffprobe are on PATH."
        )

    for tool in ("ffmpeg", "ffprobe"):
        try:
            result = subprocess.run(
                [tool, "-version"],
                text=True,
                capture_output=True,
                check=True,
            )
            version_tuple, version = _parse_tool_version(tool, result.stdout)
        except (subprocess.CalledProcessError, FileNotFoundError) as e:
            raise RuntimeError(f"Could not verify {tool} version: {e}") from e

        if version_tuple < MIN_FFMPEG_VERSION:
            raise RuntimeError(
                f"{tool} {MIN_FFMPEG_VERSION[0]}.{MIN_FFMPEG_VERSION[1]}+ "
                f"is required for video framing; found {version}."
            )


def _require_hevc_alpha_support():
    """Check the optional macOS alpha encoder before creating output files.

    Returns the pixel format to feed it: ayuv when the encoder accepts it
    (ffmpeg 8+), otherwise bgra."""
    if sys.platform != "darwin":
        raise RuntimeError("--codec hevc-alpha requires macOS. Use --alpha for ProRes MOV instead.")
    try:
        result = subprocess.run(
            ["ffmpeg", "-hide_banner", "-h", "encoder=hevc_videotoolbox"],
            text=True, capture_output=True,
        )
    except OSError as e:
        raise RuntimeError(f"Could not check HEVC alpha support: {e}") from e
    help_text = (result.stdout or "") + (result.stderr or "")
    if (
        result.returncode != 0
        or "Encoder hevc_videotoolbox " not in help_text
        or not re.search(r"(?m)^\s*-alpha_quality\s", help_text)
        or not re.search(r"Supported pixel formats:.*\bbgra\b", help_text)
    ):
        raise RuntimeError(
            "This ffmpeg build lacks HEVC alpha support (hevc_videotoolbox, alpha_quality, and BGRA are required). "
            "Update ffmpeg or use --alpha for ProRes MOV."
        )
    # On macOS 27, VideoToolbox's own BGRA conversion stores opaque alpha as 254,
    # so prefer handing it YUV with alpha that ffmpeg has already converted.
    return "ayuv" if re.search(r"Supported pixel formats:.*\bayuv\b", help_text) else "bgra"


def _validate_video_codec(args):
    if args.codec == "hevc-alpha":
        if args.quality is not None:
            raise ValueError("--quality is not supported with --codec hevc-alpha. Use --preset instead.")
        args.hevc_alpha_pix_fmt = _require_hevc_alpha_support()


def _video_tools_error():
    try:
        require_ffmpeg_tools()
        return None
    except RuntimeError as e:
        return str(e)


def _brew_path():
    candidates = [shutil.which("brew"), "/opt/homebrew/bin/brew", "/usr/local/bin/brew"]
    for candidate in candidates:
        if candidate and Path(candidate).exists():
            return candidate
    return None


def _video_tools_install_hint(error_text):
    if sys.platform == "darwin":
        if "is required for video framing" in error_text:
            return "brew upgrade ffmpeg"
        return "brew install ffmpeg"
    if sys.platform.startswith("linux"):
        return "Install ffmpeg with your package manager, e.g. `sudo apt install ffmpeg`."
    if sys.platform.startswith("win"):
        return "Install ffmpeg 5.1+ and add both ffmpeg and ffprobe to PATH."
    return "Install ffmpeg 5.1+ and ensure both ffmpeg and ffprobe are on PATH."


def offer_video_tools_setup():
    """Check optional video tools during setup and offer a simple macOS install."""
    error_text = _video_tools_error()
    if error_text is None:
        print(f"  {C.green('Video tools ready')} {C.dim('ffmpeg/ffprobe detected')}")
        return True

    print()
    print(f"  {C.yellow('Video tools needed')} {C.dim('for screen recording framing')}")
    print(f"  {C.dim(error_text)}")

    hint = _video_tools_install_hint(error_text)
    brew = _brew_path()
    can_install = sys.platform == "darwin" and brew and sys.stdin.isatty()
    if not can_install:
        print(f"  {C.dim('Run:')} {C.cyan(hint)}")
        return False

    brew_action = "upgrade" if "upgrade" in hint else "install"
    print()
    print(f"  Install ffmpeg with Homebrew now? {C.dim(f'({Path(brew).name} {brew_action} ffmpeg)')}")
    print(f"  {C.bold('Enter')} {C.dim('to install  |')}  {C.bold('q')} {C.dim('to skip')}")
    try:
        choice = input(f"  {C.bold('›')} ").strip().lower()
    except (EOFError, KeyboardInterrupt):
        print(f"\n  {C.dim('Skipped video tools setup.')}")
        return False

    if choice in {"q", "quit", "n", "no"}:
        print(f"  {C.dim('Skipped. Run')} {C.cyan(hint)} {C.dim('when you need video framing.')}")
        return False

    result = subprocess.run([brew, brew_action, "ffmpeg"])
    if result.returncode != 0:
        print(f"  {C.yellow('Homebrew install failed.')} {C.dim('Run manually:')} {C.cyan(hint)}")
        return False

    verify_error = _video_tools_error()
    if verify_error is None:
        print(f"  {C.green('Video tools ready')} {C.dim('ffmpeg/ffprobe detected')}")
        return True

    print(f"  {C.yellow('Video tools still unavailable')}: {verify_error}")
    print(f"  {C.dim('Run:')} {C.cyan(hint)}")
    return False


def _positive_int(value, label, path):
    try:
        parsed = int(value)
    except (TypeError, ValueError) as e:
        raise ValueError(f"Invalid {label} for {path}: {value!r}.") from e
    if parsed <= 0:
        raise ValueError(f"Invalid {label} for {path}: {value!r}.")
    return parsed


def _positive_float(value, label, path):
    try:
        parsed = float(value)
    except (TypeError, ValueError) as e:
        raise ValueError(f"Invalid {label} for {path}: {value!r}.") from e
    if not math.isfinite(parsed) or parsed <= 0:
        raise ValueError(f"Invalid {label} for {path}: {value!r}.")
    return parsed


def probe_video(path):
    data = _run_json_command([
        "ffprobe", "-hide_banner", "-v", "error",
        "-print_format", "json",
        "-show_streams", "-show_format",
        str(path),
    ])
    video_stream = next((s for s in data.get("streams", []) if s.get("codec_type") == "video"), None)
    if not video_stream:
        raise ValueError(f"No video stream found in {path}.")

    audio_stream = next((s for s in data.get("streams", []) if s.get("codec_type") == "audio"), None)
    duration_value = data.get("format", {}).get("duration") or video_stream.get("duration")
    duration = _positive_float(duration_value, "duration", path)
    width = _positive_int(video_stream.get("width"), "video width", path)
    height = _positive_int(video_stream.get("height"), "video height", path)
    guard_image_size(width, height, path)
    fps_rate = video_stream.get("avg_frame_rate") or video_stream.get("r_frame_rate") or "30/1"
    fps = _parse_rate(fps_rate)
    normalized_fps_rate = fps_rate if _valid_rate(fps_rate) else "30/1"
    return {
        "width": width,
        "height": height,
        "duration": duration,
        "fps": fps,
        "fps_rate": normalized_fps_rate,
        "codec": video_stream.get("codec_name"),
        "audio": audio_stream is not None,
        "audio_codec": audio_stream.get("codec_name") if audio_stream else None,
    }


def _valid_rate(rate):
    try:
        num, den = str(rate).split("/", 1)
        num = float(num)
        den = float(den)
    except (AttributeError, ValueError):
        return False
    return (
        math.isfinite(num)
        and math.isfinite(den)
        and num > 0
        and den > 0
    )


def _parse_rate(rate):
    try:
        num, den = rate.split("/", 1)
        num = float(num)
        den = float(den)
        parsed = 0.0 if den == 0 else num / den
    except (AttributeError, ValueError, ZeroDivisionError):
        return 30.0
    return parsed if math.isfinite(parsed) and parsed > 0 else 30.0


def _normalize_rate(rate):
    if not _valid_rate(rate):
        return "30/1"
    return rate


def _background_color(value):
    if value == "transparent":
        return "black@0.0"
    if re.fullmatch(r"#[0-9A-Fa-f]{6}", value or ""):
        return "0x" + value[1:]
    if value in {"white", "black"}:
        return value
    raise ValueError("--background must be white, black, transparent, or #RRGGBB.")


def _video_background(args):
    background = getattr(args, "background", None)
    if background is not None:
        return background
    transparent = getattr(args, "alpha", False) or getattr(args, "codec", None) == "hevc-alpha"
    return "transparent" if transparent else "white"


def _video_output_codec(args):
    if args.codec == "hevc-alpha":
        return "hevc-alpha"
    if args.alpha or args.codec == "prores" or _video_background(args) == "transparent":
        return "prores"
    return args.codec


def _output_uses_alpha(args):
    return _video_output_codec(args) in {"prores", "hevc-alpha"}


def _video_pixel_format(args):
    # 12-bit matches ProRes 4444 and keeps opaque alpha exact in both ProRes encoders;
    # prores_videotoolbox turns 10-bit opaque alpha into 99.9%, prores_ks dithers 16-bit.
    return {"hevc-alpha": "bgra", "prores": "yuva444p12le"}.get(_video_output_codec(args), "yuv420p")


def _hevc_alpha_uses_ayuv(args):
    return _video_output_codec(args) == "hevc-alpha" and getattr(args, "hevc_alpha_pix_fmt", "bgra") == "ayuv"


def _encoder_input_filter(args):
    """Final filter step that converts a finished canvas to the encoder's input format."""
    if _hevc_alpha_uses_ayuv(args):
        # Planar gbrap keeps alpha exact; ffmpeg 9 rounds packed BGRA alpha up on the way
        # to ayuv. BT.709 matches what Apple decoders assume for HD, and the encoder tags it.
        return "format=gbrap,scale=out_color_matrix=bt709:out_range=tv,format=ayuv"
    return f"format={_video_pixel_format(args)}"


def _video_rotation(args):
    return getattr(args, "rotate", "none") or "none"


def _video_rotation_filter(rotation):
    return VIDEO_ROTATIONS[rotation]


def _rotated_video_meta(video_meta, rotation):
    rotated = dict(video_meta)
    rotated["source_width"] = video_meta["width"]
    rotated["source_height"] = video_meta["height"]
    rotated["source_dimensions"] = f"{video_meta['width']}x{video_meta['height']}"
    rotated["rotation"] = rotation
    if rotation in {"clockwise", "counterclockwise"}:
        rotated["width"], rotated["height"] = video_meta["height"], video_meta["width"]
    return rotated


def _video_source_filter(args):
    filters = []
    rotation_filter = _video_rotation_filter(_video_rotation(args))
    if rotation_filter:
        filters.append(rotation_filter)
    filters.append("format=rgba")
    return ",".join(filters)


def _encoded_video_dimensions(width, height, args):
    if _video_output_codec(args) == "prores":
        return width, height
    return width + (width % 2), height + (height % 2)


def _video_pad_filter(width, height, args):
    out_w, out_h = _encoded_video_dimensions(width, height, args)
    if (out_w, out_h) == (width, height):
        return None
    background = _video_background(args)
    return f"pad={out_w}:{out_h}:0:0:color={_background_color(background)}"


def _video_output_dimension_info(width, height, args=None):
    if args is None:
        out_w, out_h = width + (width % 2), height + (height % 2)
    else:
        out_w, out_h = _encoded_video_dimensions(width, height, args)
    return {
        "output_width": out_w,
        "output_height": out_h,
        "output_dimensions": f"{out_w}x{out_h}",
        "padded": (out_w, out_h) != (width, height),
    }


def _video_extension(args):
    return ".mov" if _output_uses_alpha(args) else ".mp4"


def _video_output_path(src_path, args, default_name=None, multiple=False):
    ext = _video_extension(args)
    if args.output:
        output = Path(args.output)
        if output.suffix and not multiple:
            return output
        name = default_name or f"{src_path.stem}_framed{ext}"
        return output / name
    if default_name:
        return src_path.parent / default_name
    return src_path.parent / f"{src_path.stem}_framed{ext}"


def _validate_video_output_args(args, input_count):
    if not args.output:
        return None
    output = Path(args.output)
    if output.suffix and input_count > 1 and not args.merge:
        return "--output can be a file only when framing one video."
    if output.suffix and _output_uses_alpha(args) and output.suffix.lower() != ".mov":
        if _video_output_codec(args) == "hevc-alpha":
            return "HEVC alpha video output requires a .mov output file."
        return "Transparent/ProRes video output requires a .mov output file."
    return None


def _gather_video_paths(paths):
    result = []
    for p in paths:
        p = Path(p)
        if p.is_dir():
            for f in sorted(p.iterdir()):
                if f.suffix.lower() in VALID_VIDEO_EXTS and not f.name.startswith("."):
                    result.append(f)
        elif p.is_file():
            if p.suffix.lower() in VALID_VIDEO_EXTS:
                result.append(p)
            else:
                print(f"{C.red('Error')}: {p} is not a supported video file", file=sys.stderr)
        else:
                print(f"{C.red('Error')}: {p} not found", file=sys.stderr)
    return result


def _video_info_for_path(
    path,
    assets_dir,
    device_dict,
    color_arg=None,
    strict_color=False,
    force_device=None,
    rotation="none",
    verbose=False,
    user_defaults=None,
    device_index=None,
):
    source_meta = probe_video(path)
    video_meta = _rotated_video_meta(source_meta, rotation)
    frame_meta = resolve_frame_metadata(
        video_meta["width"],
        video_meta["height"],
        assets_dir,
        device_dict,
        color_arg=color_arg,
        strict_color=strict_color,
        force_device=force_device,
        verbose=verbose,
        user_defaults=user_defaults,
        device_index=device_index,
    )
    return {
        "file": str(path),
        "name": path.name,
        "width": video_meta["width"],
        "height": video_meta["height"],
        "dimensions": f"{video_meta['width']}x{video_meta['height']}",
        "duration": round(video_meta["duration"], 6),
        "fps": round(video_meta["fps"], 4),
        "fps_rate": video_meta["fps_rate"],
        "codec": video_meta["codec"],
        "audio": video_meta["audio"],
        "audio_codec": video_meta["audio_codec"],
        "device": frame_meta["device"],
        "primary_match": frame_meta["primary_match"],
        "color": frame_meta["color"],
        "frame_size": frame_meta["frame_size"],
        "x": frame_meta["x"],
        "y": frame_meta["y"],
        "resize_width": frame_meta["resize_width"],
        "resize_height": frame_meta["resize_height"],
        "has_mask": frame_meta["has_mask"],
        "mask_missing": frame_meta["mask_missing"],
        "physicalHeight": frame_meta["physicalHeight"],
        "is_variant": frame_meta["is_variant"],
        "rotation": rotation,
        "source_width": source_meta["width"],
        "source_height": source_meta["height"],
        "source_dimensions": f"{source_meta['width']}x{source_meta['height']}",
        **_video_output_dimension_info(frame_meta["frame_width"], frame_meta["frame_height"]),
    }


def resolve_frame_metadata(
    width,
    height,
    assets_dir,
    device_dict,
    color_arg=None,
    strict_color=False,
    force_device=None,
    verbose=False,
    user_defaults=None,
    device_index=None,
):
    entry, model_name, primary_name, is_variant = resolve_device_entry(
        width, height, device_dict,
        force_device=force_device,
        device_index=device_index,
        verbose=verbose,
    )
    has_colors = entry.get("colors") == "yes"
    color = get_color(model_name, color_arg, user_defaults=user_defaults, strict=strict_color) if has_colors else None
    frame_path = _frame_asset_path(assets_dir, model_name, color)
    if not frame_path.exists():
        raise FileNotFoundError(f"Frame asset not found: {frame_path}")
    # Video rendering uses ffmpeg; metadata only needs the PNG header.
    with Image.open(frame_path) as frame:
        frame_size = frame.size
    rotate_frame = asset_is_sideways(model_name, frame_size)
    if rotate_frame:
        frame_size = frame_size[::-1]

    has_mask = entry.get("mask") == "yes"
    mask_path = assets_dir / f"{model_name}_mask.png"
    mask_missing = has_mask and not mask_path.exists()
    rotate_mask = False
    if mask_missing:
        print(
            f"  {C.yellow('Warning')}: mask file missing for {model_name} "
            f"(expected {model_name}_mask.png). Rendering without mask.",
            file=sys.stderr,
        )
    elif has_mask:
        with Image.open(mask_path) as mask:
            rotate_mask = asset_is_sideways(model_name, mask.size)

    resize_width, resize_height = resize_target(entry, width, height) or (None, None)

    return {
        "device": model_name,
        "primary_match": primary_name,
        "is_variant": is_variant,
        "entry": entry,
        "x": int(entry["x"]),
        "y": int(entry["y"]),
        "color": color,
        "frame_path": str(frame_path),
        "rotate_frame": rotate_frame,
        "frame_width": frame_size[0],
        "frame_height": frame_size[1],
        "frame_size": f"{frame_size[0]}x{frame_size[1]}",
        "has_mask": has_mask,
        "mask_path": str(mask_path) if has_mask and not mask_missing else None,
        "rotate_mask": rotate_mask,
        "mask_missing": mask_missing,
        "resize_width": resize_width,
        "resize_height": resize_height,
        "physicalHeight": float(entry.get("physicalHeight", 0)),
    }


def _video_preset(args):
    return getattr(args, "preset", DEFAULT_VIDEO_PRESET) or DEFAULT_VIDEO_PRESET


def _video_crf(args, codec):
    if getattr(args, "quality", None) is not None:
        return args.quality
    preset = VIDEO_PRESETS[_video_preset(args)]
    return preset["hevc_crf" if codec == "hevc" else "h264_crf"]


def _encoder_args(args, use_hardware=True, prefer_software=False):
    codec = _video_output_codec(args)
    preset = VIDEO_PRESETS[_video_preset(args)]
    if codec == "hevc-alpha":
        pix_fmt = ["-pix_fmt", "ayuv", "-colorspace", "bt709"] if _hevc_alpha_uses_ayuv(args) else ["-pix_fmt", "bgra"]
        # VideoToolbox may choose software, but never retry with an opaque codec.
        return [
            "-c:v", "hevc_videotoolbox", *pix_fmt, "-alpha_quality", "1",
            "-allow_sw", "1", "-tag:v", "hvc1", "-b:v", preset["hevc_bitrate"],
        ], False
    if codec == "prores":
        if sys.platform == "darwin" and use_hardware and not prefer_software and shutil.which("ffmpeg"):
            return ["-c:v", "prores_videotoolbox", "-profile:v", "4444", "-pix_fmt", "ayuv64le",
                    "-colorspace", "smpte170m"], True
        return ["-c:v", "prores_ks", "-profile:v", "4", "-pix_fmt", "yuva444p10le"], False
    if codec == "hevc":
        if sys.platform == "darwin" and use_hardware and not prefer_software and shutil.which("ffmpeg"):
            return ["-c:v", "hevc_videotoolbox", "-b:v", preset["hevc_bitrate"]], True
        return ["-c:v", "libx265", "-crf", str(_video_crf(args, "hevc")), "-preset", "veryfast"], False
    if sys.platform == "darwin" and use_hardware and not prefer_software and shutil.which("ffmpeg"):
        return ["-c:v", "h264_videotoolbox", "-b:v", preset["h264_bitrate"], "-profile:v", "high"], True
    return ["-c:v", "libx264", "-crf", str(_video_crf(args, "h264")), "-preset", "veryfast"], False


def _format_bytes(num_bytes):
    if num_bytes is None:
        return None
    size = float(num_bytes)
    for unit in ("B", "KB", "MB", "GB", "TB"):
        if size < 1024 or unit == "TB":
            if unit == "B":
                return f"{int(size)} B"
            return f"{size:.1f} {unit}"
        size /= 1024


def _format_signed_bytes(num_bytes):
    if num_bytes is None:
        return None
    sign = "-" if num_bytes < 0 else ""
    return sign + _format_bytes(abs(num_bytes))


def _video_size_metrics(source_paths, out_path, source_size=None):
    if source_size is None:
        source_size = sum(Path(p).stat().st_size for p in source_paths)
    output_size = Path(out_path).stat().st_size
    savings = source_size - output_size
    savings_percent = (savings / source_size * 100) if source_size else 0.0
    return {
        "source_size_bytes": source_size,
        "source_size": _format_bytes(source_size),
        "output_size_bytes": output_size,
        "output_size": _format_bytes(output_size),
        "savings_bytes": savings,
        "savings": _format_signed_bytes(savings),
        "savings_percent": round(savings_percent, 2),
    }


def _add_video_size_metrics(info, source_paths, out_path, source_size=None):
    info.update(_video_size_metrics(source_paths, out_path, source_size=source_size))
    return info


def _video_size_line(metrics):
    return (
        f"  {C.dim('Size')} {C.bold(metrics['output_size'])} "
        f"{C.dim('(source')} {metrics['source_size']}{C.dim(', savings')} "
        f"{metrics['savings']} / {metrics['savings_percent']:.1f}%{C.dim(')')}"
    )


def _ffmpeg_progress_cmd(cmd):
    return [cmd[0], "-progress", "pipe:1", "-nostats", *cmd[1:]]


def _format_progress_time(seconds):
    seconds = max(0.0, float(seconds))
    if seconds < 10:
        return f"{seconds:.1f}s"
    rounded = int(round(seconds))
    minutes, secs = divmod(rounded, 60)
    hours, minutes = divmod(minutes, 60)
    if hours:
        return f"{hours:d}:{minutes:02d}:{secs:02d}"
    return f"{minutes:02d}:{secs:02d}"


def _progress_bar(fraction, width=24):
    fraction = min(1.0, max(0.0, fraction))
    filled = int(round(width * fraction))
    return "\u2588" * filled + "\u2591" * (width - filled)


def _print_video_progress(label, current, total, done=False):
    total = max(total, 0.001)
    current = min(max(current, 0.0), total)
    fraction = current / total
    columns = shutil.get_terminal_size((100, 20)).columns
    bar_width = max(12, min(28, columns - len(label) - 42))
    bar = _progress_bar(fraction, bar_width)
    pct = int(round(fraction * 100))
    time_text = f"{_format_progress_time(current)}/{_format_progress_time(total)}"
    line = (
        f"  {C.dim(label)} "
        f"[{C.rgb(232, 114, 42, bar)}] "
        f"{pct:3d}% {C.dim(time_text)}"
    )
    print(f"\r{line}\033[K", end="\n" if done else "", flush=True)


def _run_ffmpeg_with_progress(cmd, progress_label, progress_total):
    # A file keeps stderr draining while stdout delivers progress. Two pipes
    # can deadlock when ffmpeg fills stderr before writing its next update.
    with tempfile.TemporaryFile(mode="w+t") as error_log:
        process = subprocess.Popen(
            _ffmpeg_progress_cmd(cmd),
            text=True,
            stdout=subprocess.PIPE,
            stderr=error_log,
        )
        completed = False
        _print_video_progress(progress_label, 0.0, progress_total)
        try:
            for line in process.stdout or []:
                line = line.strip()
                if not line or "=" not in line:
                    continue
                key, value = line.split("=", 1)
                if key == "out_time_ms":
                    try:
                        current = int(value) / 1_000_000
                    except ValueError:
                        continue
                    _print_video_progress(progress_label, current, progress_total)
                elif key == "progress" and value == "end":
                    _print_video_progress(progress_label, progress_total, progress_total, done=True)
                    completed = True
            returncode = process.wait()
            error_log.seek(0)
            stderr = error_log.read()
        except BaseException:
            process.terminate()
            try:
                process.wait(timeout=5)
            except subprocess.TimeoutExpired:
                process.kill()
                process.wait()
            raise
        finally:
            if process.stdout:
                process.stdout.close()
    if returncode == 0:
        if not completed:
            _print_video_progress(progress_label, progress_total, progress_total, done=True)
        return subprocess.CompletedProcess(cmd, returncode, "", stderr)
    print()
    return subprocess.CompletedProcess(cmd, returncode, "", stderr)


def _run_ffmpeg(cmd, fallback_cmd=None, progress_label=None, progress_total=None):
    if progress_label and progress_total and sys.stdout.isatty():
        result = _run_ffmpeg_with_progress(cmd, progress_label, progress_total)
    else:
        result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode == 0:
        return result
    if fallback_cmd is not None:
        fallback_label = f"{progress_label} (software)" if progress_label else None
        if fallback_label and progress_total and sys.stdout.isatty():
            fallback = _run_ffmpeg_with_progress(fallback_cmd, fallback_label, progress_total)
        else:
            fallback = subprocess.run(fallback_cmd, text=True, capture_output=True)
        if fallback.returncode == 0:
            return fallback
        raise RuntimeError(fallback.stderr.strip() or fallback.stdout.strip() or "ffmpeg failed")
    raise RuntimeError(result.stderr.strip() or result.stdout.strip() or "ffmpeg failed")


def _paths_alias(first, second):
    first, second = Path(first), Path(second)
    return first.resolve() == second.resolve() or (
        first.exists() and second.exists() and os.path.samefile(first, second)
    )


def _individual_video_output_paths(items, args):
    """Reject batch outputs that would replace another source or each other."""
    outputs = [_video_output_path(item["src"], args, multiple=len(items) > 1) for item in items]
    for index, (item, output) in enumerate(zip(items, outputs)):
        for other in items:
            if not _paths_alias(item["src"], other["src"]) and _paths_alias(output, other["src"]):
                raise ValueError(
                    f"Output {output} would replace another input video. Choose a separate output directory with --output."
                )
        for previous in range(index):
            if _paths_alias(output, outputs[previous]) and not _paths_alias(item["src"], items[previous]["src"]):
                raise ValueError(
                    f"Multiple input videos would write to {output}. Use distinct source filenames or separate output directories."
                )
    return outputs


def _run_video_export(cmd, out_path, sources, fallback_cmd=None, progress_label=None, progress_total=None):
    """Stage output that aliases an input so ffmpeg cannot truncate a source."""
    aliases_source = any(_paths_alias(out_path, source) for source in sources)
    if not aliases_source:
        return _run_ffmpeg(cmd, fallback_cmd=fallback_cmd,
                           progress_label=progress_label, progress_total=progress_total)

    with tempfile.NamedTemporaryFile(
        prefix=".frames-video-", suffix=out_path.suffix, dir=out_path.parent, delete=False,
    ) as staged:
        staged_path = Path(staged.name)
    try:
        staged_cmd = cmd[:-1] + [str(staged_path)]
        staged_fallback = fallback_cmd[:-1] + [str(staged_path)] if fallback_cmd else None
        result = _run_ffmpeg(staged_cmd, fallback_cmd=staged_fallback,
                             progress_label=progress_label, progress_total=progress_total)
        os.replace(staged_path, out_path)
        return result
    finally:
        if staged_path.exists():
            staged_path.unlink()


def _framed_video_filters(src_path, frame_meta, video_meta, args, input_index=0, prefix="", pad_output=True,
                          merge_fps=None):
    """Build one framed stream for single exports and direct video merges."""
    inputs = ["-i", str(src_path)]
    mask_index = None
    frame_index = input_index + 1
    if frame_meta["mask_path"]:
        inputs += ["-i", frame_meta["mask_path"]]
        mask_index = input_index + 1
        frame_index = input_index + 2
    inputs += ["-i", frame_meta["frame_path"]]

    filters = []
    source_chain = f"[{input_index}:v]{_video_source_filter(args)}"
    if merge_fps:
        source_chain = f"[{input_index}:v]tpad=stop_mode=clone:stop=1,fps={merge_fps},{_video_source_filter(args)}"
    if frame_meta["resize_width"]:
        source_chain += f",scale={frame_meta['resize_width']}:{frame_meta['resize_height']}"
    source_chain += "[v0]"
    filters.append(source_chain)

    video_label = "v0"
    if mask_index is not None:
        mask_chain = f"[{mask_index}:v]{STILL_LOOP},format=gray"
        if frame_meta.get("rotate_mask"):
            mask_chain += "," + VIDEO_ROTATIONS["counterclockwise"]
        if frame_meta["resize_width"]:
            mask_chain += f",scale={frame_meta['resize_width']}:{frame_meta['resize_height']}"
        mask_chain += "[m0]"
        filters.append(mask_chain)
        filters.append("[v0][m0]alphamerge[vm]")
        video_label = "vm"

    background = _background_color(_video_background(args))
    canvas = (
        f"color=c={background}:s={frame_meta['frame_width']}x{frame_meta['frame_height']}:"
        f"r={merge_fps or _normalize_rate(video_meta['fps_rate'])}:"
        f"d={round(video_meta['duration'] + 1 / merge_fps, 6) if merge_fps else video_meta['duration']}"
    )
    canvas += ",format=rgba"
    canvas += "[base]"
    filters.append(canvas)
    overlay_format = ":format=auto"
    out_format = "rgba" if merge_fps else _video_pixel_format(args)
    filters.append(f"[base][{video_label}]overlay={frame_meta['x']}:{frame_meta['y']}{overlay_format}[tmp]")
    rotate_frame = "," + VIDEO_ROTATIONS["counterclockwise"] if frame_meta.get("rotate_frame") else ""
    filters.append(f"[{frame_index}:v]{STILL_LOOP}{rotate_frame}[f0]")
    frame_label = "f0"
    filters.append(f"[tmp][{frame_label}]overlay=0:0:format=auto[framed]")
    output_filters = []
    pad_filter = _video_pad_filter(frame_meta["frame_width"], frame_meta["frame_height"], args) if pad_output else None
    if pad_filter:
        if out_format == "bgra":
            output_filters.append("format=bgra")
        output_filters.append(pad_filter)
    # HEVC alpha merge tiles skip padding and stay in the working format until the final canvas.
    output_filters.append(_encoder_input_filter(args) if pad_output and not merge_fps else f"format={out_format}")
    filters.append(f"[framed]{','.join(output_filters)}[out]")

    if prefix:
        for label in ("v0", "m0", "vm", "base", "tmp", "f0", "framed", "out"):
            filters = [part.replace("[" + label + "]", "[" + prefix + label + "]") for part in filters]
    return inputs, filters, prefix + "out", frame_index + 1


STILL_LOOP = "loop=loop=-1:size=1"


def render_framed_video(src_path, out_path, frame_meta, video_meta, args, progress_label=None):
    _validate_video_codec(args)
    ensure_output_dir(out_path.parent)
    inputs, filters, _, _ = _framed_video_filters(src_path, frame_meta, video_meta, args)
    enc_args, used_hw = _encoder_args(args, use_hardware=True, prefer_software=False)
    fallback_enc_args, _ = _encoder_args(args, use_hardware=False, prefer_software=True)
    base_cmd = [
        "ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
        *inputs,
        "-filter_complex", ";".join(filters),
        "-map", "[out]",
    ]
    if args.strip_audio or not video_meta["audio"]:
        audio_args = ["-an"]
    else:
        audio_args = ["-map", "0:a?", "-c:a", "copy"]
    tail = ["-t", f"{video_meta['duration']:.6f}", *enc_args, *audio_args, "-movflags", "+faststart", str(out_path)]
    cmd = base_cmd + tail

    fallback_cmd = None
    if used_hw:
        fallback_tail = [
            "-t", f"{video_meta['duration']:.6f}",
            *fallback_enc_args,
            *audio_args,
            "-movflags", "+faststart",
            str(out_path),
        ]
        fallback_cmd = base_cmd + fallback_tail

    _run_video_export(
        cmd, out_path, [src_path],
        fallback_cmd=fallback_cmd,
        progress_label=progress_label,
        progress_total=video_meta["duration"],
    )


def compute_video_merge_layout(items, spacing, no_scale=False):
    frames = []
    for item in items:
        info = item.get("info", {})
        frames.append({
            "width": int(info.get("output_width", item["frame_meta"]["frame_width"])),
            "height": int(info.get("output_height", item["frame_meta"]["frame_height"])),
            "physicalHeight": float(item["frame_meta"].get("physicalHeight", 0)),
        })

    do_scale = (
        not no_scale
        and all(frame["physicalHeight"] > 0 for frame in frames)
        and len({frame["physicalHeight"] for frame in frames}) > 1
    )
    if do_scale:
        bodies = [_frame_body_rows(item["frame_meta"], frame["height"]) for item, frame in zip(items, frames)]
        factors = physical_scale_factors(bodies, [frame["physicalHeight"] for frame in frames])
        for frame, (_, bottom), scale in zip(frames, bodies, factors):
            if scale < 0.999:
                height = max(1, round(frame["height"] * scale))
                frame["width"] = max(1, round(frame["width"] * scale))
                scale = height / frame["height"]  # Report the rounded, effective scale.
                frame["height"] = height
            else:
                scale = 1.0
            frame["scale_factor"] = round(scale, 4)
            frame["body_bottom"] = round(bottom * scale)
    else:
        for frame in frames:
            frame["scale_factor"] = 1.0
            frame["body_bottom"] = frame["height"]

    # Bottom-align the devices themselves, not their differently padded canvases.
    body_line = max(frame["body_bottom"] for frame in frames)
    total_width = sum(frame["width"] for frame in frames) + spacing * (len(frames) - 1)
    x = 0
    for frame in frames:
        frame["x"] = x
        frame["y"] = body_line - frame.pop("body_bottom")
        x += frame["width"] + spacing
    max_height = max(frame["y"] + frame["height"] for frame in frames)
    return total_width, max_height, frames


def _frame_body_rows(frame_meta, height):
    """Top and bottom rows of the device in a video's frame asset."""
    frame_path = frame_meta.get("frame_path")
    if not frame_path:
        return (0, height)
    frame = _load_rgba_asset_cached(str(frame_path))
    if frame_meta.get("rotate_frame"):
        frame = frame.transpose(Image.ROTATE_90)
    return _body_rows(frame)


def render_merged_video(items, out_path, args, progress_label=None):
    _validate_video_codec(args)
    ensure_output_dir(out_path.parent)
    hevc_alpha = _video_output_codec(args) == "hevc-alpha"
    if hevc_alpha:
        # Only the final encoder needs even dimensions; keep merge tiles native.
        for item in items:
            width = item["frame_meta"]["frame_width"]
            height = item["frame_meta"]["frame_height"]
            item["info"].update({
                "output_width": width, "output_height": height,
                "output_dimensions": f"{width}x{height}", "padded": False,
            })
    width, height, layout = compute_video_merge_layout(items, args.spacing, no_scale=args.no_scale)
    total_duration = (
        sum(item["video_meta"]["duration"] for item in items)
        if args.playback_offset
        else max(item["video_meta"]["duration"] for item in items)
    )

    input_args = []
    filters = []
    source_indices = []
    framed_labels = []
    next_index = 0
    for idx, item in enumerate(items):
        source_indices.append(next_index)
        inputs, frame_filters, label, next_index = _framed_video_filters(
            item["src"], item["frame_meta"], item["video_meta"], args,
            input_index=next_index, prefix=f"f{idx}_", pad_output=not hevc_alpha, merge_fps=30,
        )
        input_args.extend(inputs)
        filters.extend(frame_filters)
        framed_labels.append(label)

    overlay_chain = f"color=c={_background_color(_video_background(args))}:s={width}x{height}:r=30:d={total_duration}"
    overlay_chain += ",format=rgba"
    overlay_chain += "[base]"
    filters.append(overlay_chain)
    current = "base"
    elapsed = 0.0
    for idx, (item, frame) in enumerate(zip(items, layout)):
        duration = item["video_meta"]["duration"]
        if args.playback_offset:
            start_pad = elapsed
            stop_pad = max(0.0, total_duration - elapsed - duration)
            elapsed += duration
        else:
            start_pad = 0.0
            stop_pad = max(0.0, total_duration - duration)

        chain = f"[{framed_labels[idx]}]fps=30,setpts=PTS-STARTPTS,format=rgba"
        info = item.get("info", {})
        source_width = int(info.get("output_width", item["frame_meta"]["frame_width"]))
        source_height = int(info.get("output_height", item["frame_meta"]["frame_height"]))
        if frame["width"] != source_width or frame["height"] != source_height:
            chain += f",scale={frame['width']}:{frame['height']}"
        tpad_args = []
        if start_pad > 0:
            tpad_args.append(f"start_mode=clone:start_duration={start_pad:.6f}")
        if stop_pad > 0:
            tpad_args.append(f"stop_mode=clone:stop_duration={stop_pad:.6f}")
        if tpad_args:
            chain += ",tpad=" + ":".join(tpad_args)
        chain += f"[v{idx}]"
        filters.append(chain)

        next_label = "outv" if idx == len(items) - 1 else f"tmp{idx}"
        overlay_format = ":format=auto"
        filters.append(f"[{current}][v{idx}]overlay={frame['x']}:{frame['y']}{overlay_format}[{next_label}]")
        current = next_label

    out_format = _video_pixel_format(args)
    output_filters = []
    pad_filter = _video_pad_filter(width, height, args)
    if pad_filter:
        if out_format == "bgra":
            output_filters.append("format=bgra")
        output_filters.append(pad_filter)
    output_filters.append(_encoder_input_filter(args))
    filters.append(f"[{current}]{','.join(output_filters)}[out]")

    map_args = ["-map", "[out]"]
    audio_filters = []
    audio_map = []
    if args.strip_audio:
        audio_map = ["-an"]
    elif args.playback_offset:
        audio_labels = []
        for idx, item in enumerate(items):
            duration = item["video_meta"]["duration"]
            if item["video_meta"]["audio"]:
                audio_filters.append(f"[{source_indices[idx]}:a]atrim=0:{duration:.6f},asetpts=PTS-STARTPTS[a{idx}]")
            else:
                audio_filters.append(
                    f"anullsrc=channel_layout=stereo:sample_rate=44100,"
                    f"atrim=0:{duration:.6f},asetpts=PTS-STARTPTS[a{idx}]"
                )
            audio_labels.append(f"[a{idx}]")
        audio_filters.append(f"{''.join(audio_labels)}concat=n={len(items)}:v=0:a=1[aout]")
        audio_map = ["-map", "[aout]", "-c:a", "aac", "-b:a", "128k"]
    else:
        audio_map = ["-an"]

    filters.extend(audio_filters)
    # Only ProRes merges use hardware. Fixed hardware bitrates made H.264/HEVC merges of
    # screen recordings 5-9x larger than software CRF for about a second of speedup.
    use_hardware = _video_output_codec(args) == "prores"
    enc_args, used_hw = _encoder_args(args, use_hardware=use_hardware, prefer_software=not use_hardware)

    def merge_cmd(enc_args):
        return [
            "ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
            *input_args,
            "-filter_complex", ";".join(filters),
            *map_args,
            *audio_map,
            "-t", f"{total_duration:.6f}",
            *enc_args,
            "-movflags", "+faststart",
            str(out_path),
        ]

    fallback_cmd = merge_cmd(_encoder_args(args, use_hardware=False, prefer_software=True)[0]) if used_hw else None
    _run_video_export(merge_cmd(enc_args), out_path, [item["src"] for item in items], fallback_cmd=fallback_cmd,
                      progress_label=progress_label, progress_total=total_duration)

    output_width, output_height = _encoded_video_dimensions(width, height, args)
    for item, frame in zip(items, layout):
        item["info"]["scale_factor"] = frame["scale_factor"]
    return {
        "width": output_width,
        "height": output_height,
        "duration": total_duration,
        "layout": layout,
    }


def cmd_video(args):
    """Frame one or more videos."""
    try:
        require_ffmpeg_tools()
        validate_color_args(args)
        _background_color(_video_background(args))
        _validate_video_codec(args)
        if args.spacing < 0:
            raise ValueError("--spacing must be 0 or greater.")
        if args.quality is not None and (args.quality < 0 or args.quality > 51):
            raise ValueError("--quality must be between 0 and 51.")
    except (RuntimeError, ValueError) as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    assets_dir = Path(args.assets) if hasattr(args, 'assets') and args.assets else get_assets_dir()
    device_dict = load_json(assets_dir)
    config = load_config()
    user_defaults = config.get("default_colors", {})
    device_index = build_device_name_index(device_dict)

    expanded = _gather_video_paths(args.files)
    if not expanded:
        print(f"{C.red('Error')}: No videos found in the specified paths.", file=sys.stderr)
        sys.exit(1)
    output_error = _validate_video_output_args(args, len(expanded))
    if output_error:
        print(f"{C.red('Error')}: {output_error}", file=sys.stderr)
        sys.exit(1)
    try:
        color_values = parse_per_input_colors(getattr(args, "colors", None), len(expanded))
    except ValueError as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    strict_colors = color_values is not None
    items = []
    try:
        for idx, src in enumerate(expanded):
            source_video_meta = probe_video(src)
            video_meta = _rotated_video_meta(source_video_meta, _video_rotation(args))
            frame_meta = resolve_frame_metadata(
                video_meta["width"],
                video_meta["height"],
                assets_dir,
                device_dict,
                color_arg=color_arg_for_index(args, color_values, idx),
                strict_color=strict_colors,
                force_device=args.device,
                verbose=args.verbose,
                user_defaults=user_defaults,
                device_index=device_index,
            )
            info = {
                "source": str(src),
                "device": frame_meta["device"],
                "primary_match": frame_meta["primary_match"],
                "color": frame_meta["color"],
                "dimensions": f"{video_meta['width']}x{video_meta['height']}",
                "frame_size": frame_meta["frame_size"],
                "duration": round(video_meta["duration"], 6),
                "fps": round(video_meta["fps"], 4),
                "codec": video_meta["codec"],
                "output_codec": _video_output_codec(args),
                "audio": video_meta["audio"] and not args.strip_audio,
                "audio_stripped": bool(args.strip_audio),
                "background": _video_background(args),
                "preset": _video_preset(args),
                "quality": args.quality,
                "alpha": _output_uses_alpha(args),
                "resized": bool(frame_meta["resize_width"]),
                "masked": frame_meta["has_mask"] and not frame_meta["mask_missing"],
                "mask_missing": frame_meta["mask_missing"],
                "physicalHeight": frame_meta["physicalHeight"],
                "rotation": _video_rotation(args),
                "source_dimensions": video_meta["source_dimensions"],
                **_video_output_dimension_info(frame_meta["frame_width"], frame_meta["frame_height"], args),
            }
            items.append({
                "src": src,
                "video_meta": video_meta,
                "frame_meta": frame_meta,
                "info": info,
            })
    except (ValueError, FileNotFoundError, subprocess.CalledProcessError, RuntimeError) as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    if args.merge and len(items) < 2:
        print(f"{C.red('Error')}: --merge requires at least two videos.", file=sys.stderr)
        sys.exit(1)
    if args.playback_offset and not args.merge:
        print(f"{C.red('Error')}: --playback-offset requires --merge.", file=sys.stderr)
        sys.exit(1)

    if args.merge:
        out_path = _video_output_path(expanded[0], args, default_name=f"merged_framed{_video_extension(args)}", multiple=False)
        try:
            source_size = sum(src.stat().st_size for src in expanded)
            merge_label = "Framing and merging videos" if not args.json else None
            merge_info = render_merged_video(items, out_path, args, progress_label=merge_label)
            merge_metrics = _video_size_metrics(expanded, out_path, source_size=source_size)
            for item in items:
                item["info"]["output"] = str(out_path)
            result_json = {
                "merged": str(out_path),
                "count": len(items),
                "duration": round(merge_info["duration"], 6),
                "dimensions": f"{merge_info['width']}x{merge_info['height']}",
                "playback_offset": bool(args.playback_offset),
                "audio": not args.strip_audio and bool(args.playback_offset),
                "audio_stripped": bool(args.strip_audio),
                "preset": _video_preset(args),
                "frames": [item["info"] for item in items],
                "output_codec": _video_output_codec(args),
            }
            result_json.update(merge_metrics)
            if args.json:
                print(json.dumps(result_json, indent=2))
            else:
                print(f"\n  {C.green('Merged')} {len(items)} videos → {C.bold(str(out_path))}")
                print(_video_size_line(result_json))
        except (RuntimeError, OSError, subprocess.CalledProcessError) as e:
            print(f"{C.red('Error')}: {e}", file=sys.stderr)
            sys.exit(1)
        return

    try:
        output_paths = _individual_video_output_paths(items, args)
    except (ValueError, OSError) as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    outputs = []
    for item, out_path in zip(items, output_paths):
        try:
            source_size = item["src"].stat().st_size
            progress_label = f"Framing {item['src'].name}" if not args.json else None
            if not args.json and not sys.stdout.isatty():
                print(f"  {C.dim('Framing')} {item['src'].name}...", end=" ", flush=True)
            render_framed_video(
                item["src"],
                out_path,
                item["frame_meta"],
                item["video_meta"],
                args,
                progress_label=progress_label,
            )
            item["info"]["output"] = str(out_path)
            _add_video_size_metrics(item["info"], [item["src"]], out_path, source_size=source_size)
            outputs.append(item["info"])
            if not args.json:
                print(f"  {C.green('✓')} {item['info']['device']}")
                print(f"  {C.dim('→')} {C.bold(str(out_path))}")
                print(_video_size_line(item["info"]))
        except (RuntimeError, OSError, subprocess.CalledProcessError) as e:
            print(f"{C.red('Error')}: {e}", file=sys.stderr)
            sys.exit(1)

    if args.json:
        print(json.dumps(outputs[0] if len(outputs) == 1 else {"videos": outputs}, indent=2))
    elif outputs:
        print()

# ── CLI Commands ─────────────────────────────────────────────────────────────

def cmd_frame(args):
    """Frame one or more screenshots."""
    assets_dir = Path(args.assets) if hasattr(args, 'assets') and args.assets else get_assets_dir()
    device_dict = load_json(assets_dir)
    config = load_config()
    user_defaults = config.get("default_colors", {})
    device_index = build_device_name_index(device_dict)

    if not args.files:
        print(f"{C.red('Error')}: No input files specified.", file=sys.stderr)
        sys.exit(1)

    batch_size = getattr(args, 'batch', None)
    if batch_size is not None and batch_size < 2:
        print(f"{C.red('Error')}: --batch must be at least 2.", file=sys.stderr)
        sys.exit(1)
    if args.spacing < 0:
        print(f"{C.red('Error')}: --spacing must be 0 or greater.", file=sys.stderr)
        sys.exit(1)
    try:
        validate_color_args(args)
    except ValueError as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    # Expand directories into image files
    expanded = _gather_image_paths(args.files)
    if not expanded:
        print(f"{C.red('Error')}: No images found in the specified paths.", file=sys.stderr)
        sys.exit(1)
    try:
        color_values = parse_per_input_colors(getattr(args, "colors", None), len(expanded))
    except ValueError as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    try:
        subfolder = get_subfolder_setting(args, config=config)
    except ValueError as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    framed = []
    infos = []

    strict_colors = color_values is not None
    for input_index, p in enumerate(expanded):

        try:
            if not args.json:
                print(f"  {C.dim('Framing')} {p.name}...", end=" ", flush=True)

            result, info = frame_screenshot(
                p, assets_dir, device_dict,
                color_arg=color_arg_for_index(args, color_values, input_index),
                strict_color=strict_colors,
                force_device=args.device,
                verbose=args.verbose,
                user_defaults=user_defaults,
                device_index=device_index,
            )
            framed.append((result, p, info))
            infos.append(info)

            if not args.json:
                color_str = f" ({C.rgb(235, 125, 40, info['color'])})" if info["color"] else ""
                print(f"{C.green(info['device'])}{color_str}")

        except (
            ValueError,
            FileNotFoundError,
            OSError,
            UnidentifiedImageError,
            Image.DecompressionBombWarning,
            Image.DecompressionBombError,
        ) as e:
            print(f"{C.red('Error')}: {e}", file=sys.stderr)
            continue

    if not framed:
        print(f"{C.red('No screenshots were framed.')}", file=sys.stderr)
        sys.exit(1)

    # Merge if requested (--merge or --batch implies merge)
    do_merge = args.merge or batch_size

    if do_merge and len(framed) > 1:
        # Split into batches
        if batch_size and batch_size > 0:
            batches = [framed[i:i+batch_size] for i in range(0, len(framed), batch_size)]
        else:
            batches = [framed]  # Single batch = merge all

        if args.output:
            out_dir = Path(args.output)
        elif subfolder:
            out_dir = framed[0][1].parent / subfolder
        else:
            out_dir = framed[0][1].parent
        try:
            ensure_output_dir(out_dir)
        except OSError as e:
            print(f"{C.red('Error')}: {e}", file=sys.stderr)
            sys.exit(1)

        merged_outputs = []
        for batch_idx, batch in enumerate(batches):
            images = [f[0] for f in batch]

            # Collect physical heights for proportional scaling
            no_scale = getattr(args, 'no_scale', False)
            if not no_scale:
                phs = [f[2].get("physicalHeight", 0) for f in batch]
                physical_heights = phs if all(ph > 0 for ph in phs) else None
            else:
                physical_heights = None

            if len(images) == 1:
                merged = images[0]
            else:
                merged = merge_images(images, spacing=args.spacing, physical_heights=physical_heights)

            if args.json and physical_heights and len(set(physical_heights)) > 1:
                # Each batch has its own pixels-per-mm reference, just like merge_images.
                ref_ppm = min(img.height / ph for img, ph in zip(images, physical_heights))
                for (img, _, info), ph in zip(batch, physical_heights):
                    scale = round(ph * ref_ppm) / img.height
                    info["scale_factor"] = round(scale, 4) if scale < 0.999 else 1.0

            if len(batches) == 1:
                out_name = "merged_framed.png"
            else:
                out_name = f"merged_{batch_idx + 1}_framed.png"

            out_path = out_dir / out_name
            try:
                save_png(merged, out_path)
            except OSError as e:
                print(f"{C.red('Error')}: {e}", file=sys.stderr)
                sys.exit(1)
            merged_outputs.append(str(out_path))

            if not args.json:
                batch_count = len(batch)
                scaled_msg = ""
                if physical_heights and len(set(physical_heights)) > 1:
                    scaled_msg = f" {C.dim('(proportional)')}"
                print(f"\n  {C.green('Merged')} {batch_count} frames → {C.bold(str(out_path))}{scaled_msg}")

        if args.copy and len(merged_outputs) == 1:
            copy_to_clipboard(Path(merged_outputs[0]), announce=not args.json)

        if args.json:
            if len(batches) == 1:
                result_json = {"merged": merged_outputs[0], "count": len(framed), "frames": infos}
            else:
                result_json = {
                    "batches": [{"merged": p, "count": len(b)} for p, b in zip(merged_outputs, batches)],
                    "batch_size": batch_size,
                    "total": len(framed),
                    "frames": infos,
                }
            print(json.dumps(result_json, indent=2))

    else:
        # Save individual framed images
        outputs = []
        for result_img, src_path, info in framed:
            if args.output:
                out_dir = Path(args.output)
            elif subfolder:
                out_dir = src_path.parent / subfolder
            else:
                out_dir = src_path.parent
            try:
                ensure_output_dir(out_dir)
                out_path = out_dir / f"{src_path.stem}_framed.png"
                save_png(result_img, out_path)
            except OSError as e:
                print(f"{C.red('Error')}: {e}", file=sys.stderr)
                sys.exit(1)

            info["output"] = str(out_path)
            outputs.append(str(out_path))

            if not args.json:
                print(f"  {C.dim('→')} {C.bold(str(out_path))}")

        if args.copy and len(outputs) == 1:
            copy_to_clipboard(Path(outputs[0]), announce=not args.json)

        if args.json:
            if len(infos) == 1:
                print(json.dumps(infos[0], indent=2))
            else:
                print(json.dumps({"frames": infos}, indent=2))

    if not args.json:
        print()

def cmd_list(args):
    """List all supported devices."""
    assets_dir = Path(args.assets) if hasattr(args, 'assets') and args.assets else get_assets_dir()
    device_dict = load_json(assets_dir)

    print(f"\n  {C.bold('Supported Devices')}\n")

    # Group by category
    categories = {
        "iPhone Duo": [], "iPhone 17": [], "iPhone Air": [], "iPhone 16": [],
        "iPhone 12-13": [], "iPhone 8": [],
        "iPad": [], "MacBook": [], "iMac": [], "Studio Display": [], "Watch": [],
    }

    for key in sorted(device_dict.keys(), key=lambda k: int(k) if k != "variants" else 0):
        if key == "variants":
            continue
        entry = device_dict[key]

        # Expand overlap entries (detect_device only checks overlap sub-entries)
        if "overlap" in entry:
            sub_entries = list(entry["overlap"].values())
        else:
            sub_entries = [entry]

        for sub in sub_entries:
            name = sub["name"]
            has_colors = sub.get("colors") == "yes"
            resize = sub.get("resizeWidth") and str(sub["resizeWidth"]) != key

            for cat in categories:
                if name.startswith(cat) or (cat == "MacBook" and "MacBook" in name) or (cat == "Watch" and "Watch" in name) or (cat == "Studio Display" and "Studio Display" in name):
                    flags = []
                    if has_colors:
                        colors = FRAME_COLORS.get(name, [])
                        if colors:
                            flags.append(f"{len(colors)} colors")
                    if resize:
                        flags.append("scaled")
                    flag_str = C.dim(f" ({', '.join(flags)})") if flags else ""
                    categories[cat].append(f"    {C.cyan(f'{key:>5}px')} → {name}{flag_str}")
                    break

    for cat, entries in categories.items():
        if entries:
            print(f"  {C.bold(cat)}")
            for e in entries:
                print(e)
            print()

    # Variants no size selects automatically, such as the iPhone Duo rear view.
    automatic = {name for names in FRAME_VARIANTS.values() for name in names}
    manual = [name for name in device_dict.get("variants", {}) if name not in automatic]
    if manual:
        print(f"  {C.bold('Manual frames')} {C.dim('(select with --device)')}")
        for name in manual:
            print(f"    {name}")
        print()

    # Show variant defaults
    print(f"  {C.bold('Default Variants')} {C.dim('(newest installed device used automatically)')}")
    for primary in FRAME_VARIANTS:
        _, default = resolve_variant(primary, device_dict)
        if default != primary:
            print(f"    {C.dim(primary)} → {C.green(default)}")
    print()

def cmd_list_colors(args):
    """List colors for a specific device (partial match)."""
    device = args.device_name
    matches = [(k, v) for k, v in FRAME_COLORS.items() if device.lower() in k.lower()]

    if not matches:
        print(f"{C.red('Error')}: No device matching '{device}'", file=sys.stderr)
        sys.exit(1)

    print()
    for name, colors in matches:
        print(f"  {C.bold(name)}")
        for i, color in enumerate(colors):
            default = C.dim(" (default)") if i == 0 else ""
            print(f"    {C.cyan(str(i+1))}. {color}{default}")
        print()

def _build_device_list():
    """Build deduplicated device→colors list (no portrait/landscape dupes)."""
    devices = []
    seen = set()
    for name, colors in FRAME_COLORS.items():
        base = name.replace(" Portrait", "").replace(" Landscape", "")
        if base not in seen:
            seen.add(base)
            devices.append((base, list(colors)))
    return devices

def _print_colors_fallback():
    """Print device colors without curses."""
    O = lambda t: C.rgb(232, 114, 42, t)
    devices = _build_device_list()
    cfg = load_config()
    user_defaults = cfg.get("default_colors", {})
    print(f"\n  {C.bold('All Device Colors')}\n")
    for base, colors in devices:
        print(f"  {C.bold(base)}")
        for i, color in enumerate(colors):
            is_default = (base in user_defaults and user_defaults[base] == color) or (base not in user_defaults and i == 0)
            marker = O("●") if is_default else C.dim("○")
            print(f"    {marker} {color}")
        print()

def _colors_curses(stdscr):
    """Curses-based interactive color picker."""
    import curses

    curses.curs_set(0)
    curses.use_default_colors()
    curses.start_color()
    curses.init_pair(1, 209, -1)   # Orange
    curses.init_pair(2, 250, -1)   # Dim

    devices = _build_device_list()
    cfg = load_config()
    user_defaults = cfg.get("default_colors", {})
    selected = {}
    for base, colors in devices:
        if base in user_defaults and user_defaults[base] in colors:
            selected[base] = colors.index(user_defaults[base])
        else:
            selected[base] = 0

    # Flat list of navigable items
    items = []
    for base, colors in devices:
        for ci in range(len(colors)):
            items.append((base, ci))

    cursor = 0
    changed = False

    while True:
        stdscr.clear()
        h, w = stdscr.getmaxyx()

        # Header
        try:
            stdscr.addstr(0, 2, "Default Colors", curses.A_BOLD)
            stdscr.addstr(0, 18, "  ↑↓ navigate  space select  enter save  q cancel", curses.color_pair(2))
        except curses.error:
            pass

        row = 2
        idx = 0
        # Calculate scroll offset so cursor is always visible
        # Each device takes len(colors) + 2 rows (header + colors + blank)
        # Simple approach: center the view around cursor
        total_rows = sum(len(c) + 2 for _, c in devices)
        scroll_offset = 0
        if total_rows > h - 4:
            # Find which row the cursor is on
            cursor_row = 2
            ci = 0
            for base, colors in devices:
                cursor_row += 1  # device header
                for c_idx in range(len(colors)):
                    if ci == cursor:
                        break
                    cursor_row += 1
                    ci += 1
                else:
                    cursor_row += 1  # blank line
                    continue
                break
            scroll_offset = max(0, cursor_row - h // 2)

        row = 2 - scroll_offset
        idx = 0
        for base, colors in devices:
            if 0 <= row < h:
                try:
                    stdscr.addstr(row, 2, base, curses.A_BOLD)
                except curses.error:
                    pass
            row += 1

            for ci, color in enumerate(colors):
                if 0 <= row < h - 1:
                    is_cursor = (idx == cursor)
                    is_selected = (selected[base] == ci)

                    try:
                        if is_cursor:
                            stdscr.addstr(row, 2, "▸ ", curses.A_BOLD)
                        else:
                            stdscr.addstr(row, 2, "  ")

                        if is_selected:
                            stdscr.addstr(row, 4, "● ", curses.color_pair(1))
                        else:
                            stdscr.addstr(row, 4, "○ ", curses.color_pair(2))

                        attr = curses.A_BOLD if is_cursor else 0
                        stdscr.addstr(row, 6, color, attr)
                    except curses.error:
                        pass
                row += 1
                idx += 1
            row += 1  # blank between devices

        stdscr.refresh()

        key = stdscr.getch()
        if key == curses.KEY_DOWN:
            cursor = min(cursor + 1, len(items) - 1)
        elif key == curses.KEY_UP:
            cursor = max(cursor - 1, 0)
        elif key == ord(' '):
            base, ci = items[cursor]
            selected[base] = ci
            changed = True
        elif key in (ord('\n'), ord('\r')):
            if changed:
                defaults = {}
                for base, colors in devices:
                    defaults[base] = colors[selected[base]]
                cfg["default_colors"] = defaults
                save_config(cfg)
            return changed, selected, devices
        elif key in (ord('q'), 27):  # q or Esc
            return False, selected, devices

def cmd_colors(args):
    """Interactive color picker — arrow keys to navigate, space to select, enter to save."""
    O = lambda t: C.rgb(232, 114, 42, t)

    if not sys.stdin.isatty():
        _print_colors_fallback()
        return

    try:
        import curses
    except ImportError:
        print(f"{C.yellow('Warning')}: curses is unavailable. Showing non-interactive color list instead.", file=sys.stderr)
        _print_colors_fallback()
        return

    changed, selected, devices = curses.wrapper(_colors_curses)

    if changed:
        print(f"\n  {C.green('Defaults saved!')}\n")
        for base, colors in devices:
            color = colors[selected[base]]
            print(f"    {O('●')} {C.bold(base)}: {color}")
        print()
    else:
        print(f"\n  {C.dim('No changes saved.')}\n")

def cmd_setup(args):
    """Configure the assets directory path, or download assets interactively."""
    config = load_config()
    if args.path is None:
        if getattr(args, "subfolder", None) is not None:
            config["use_subfolder"] = args.subfolder
            save_config(config)
            destination = "framed subfolder" if args.subfolder else "next to originals"
            print(f"  {C.green('Default saved:')} {destination}")
            return
        if not sys.stdin.isatty():
            print(f"{C.red('Error')}: Run 'frames setup' in an interactive terminal, or provide a path.", file=sys.stderr)
            sys.exit(1)
        if guided_setup():
            return
        sys.exit(1)

    assets_path = Path(args.path).resolve()

    # Validate the path
    if not assets_path.exists():
        print(f"{C.red('Error')}: Path does not exist: {assets_path}", file=sys.stderr)
        sys.exit(1)

    json_file = assets_path / "NewFrames.json"
    if not json_file.exists():
        print(f"{C.red('Error')}: NewFrames.json not found in {assets_path}", file=sys.stderr)
        print(f"  {C.dim('The path should point to the folder containing NewFrames.json and frame PNGs.')}", file=sys.stderr)
        sys.exit(1)

    ok, ver = check_assets_version(assets_path)
    if not ok:
        reason = "missing or invalid Apple Frames 4 assets" if ver is None else f"outdated asset version {ver}"
        print(f"{C.red('Error')}: {reason} in {assets_path}", file=sys.stderr)
        sys.exit(1)

    # Count assets
    pngs = list(assets_path.glob("*.png"))
    with open(json_file, encoding="utf-8") as f:
        device_dict = json.load(f)
    device_count = len([k for k in device_dict if k != "variants"])

    # Save config
    config["assets_path"] = str(assets_path)
    if hasattr(args, 'subfolder') and args.subfolder is not None:
        config["use_subfolder"] = args.subfolder
    save_config(config)

    subfolder_status = config.get("use_subfolder", False)

    print()
    print(f"  {C.green('Setup complete!')}")
    print(f"  {C.bold('Assets path:')} {assets_path}")
    print(f"  {C.bold('Frame PNGs:')}  {len(pngs)}")
    print(f"  {C.bold('Devices:')}     {device_count}")
    print(f"  {C.bold('Subfolder:')}   {'on' if subfolder_status else 'off'} {C.dim('(save to /framed/ subfolder)')}")
    print(f"  {C.bold('Config:')}      {CONFIG_FILE}")
    offer_video_tools_setup()
    print()
    print(f"  {C.dim('You can now run')} {C.cyan('frames screenshot.png')} {C.dim('from anywhere.')}")
    print()

def _gather_image_paths(paths):
    """Expand a mix of files and directories into image file paths."""
    result = []
    for p in paths:
        p = Path(p)
        if p.is_dir():
            for f in sorted(p.iterdir()):
                if f.suffix.lower() in VALID_IMAGE_EXTS and not f.name.startswith("."):
                    result.append(f)
        elif p.is_file():
            result.append(p)
        else:
            print(f"{C.red('Error')}: {p} not found", file=sys.stderr)
    return result

def _info_for_image(p, device_dict):
    """Analyze a single image. Returns an info dict."""
    with Image.open(p) as img:
        w, h = img.size
        guard_image_size(w, h, p)
        entry, model_name = detect_device(img, device_dict)
    info = {"file": str(p), "name": p.name, "width": w, "height": h}

    if not entry:
        info["device"] = None
        info["error"] = f"Unknown device (width {w}px)"
        return info

    # Resolve variant
    variant_entry, resolved_name = resolve_variant(model_name, device_dict)
    if variant_entry:
        entry = variant_entry

    colors = FRAME_COLORS.get(resolved_name, [])
    variants = installed_variants(model_name, device_dict)
    scaled = resize_target(entry, w, h) is not None

    info.update({
        "device": resolved_name,
        "primary_match": model_name,
        "x": entry["x"], "y": entry["y"],
        "colors": colors,
        "color_count": len(colors),
        "has_mask": entry.get("mask") == "yes",
        "resize_width": entry.get("resizeWidth") if scaled else None,
        "resize_height": entry.get("resizeHeight") if scaled else None,
        "variants": variants,
        "is_variant": resolved_name != model_name,
    })
    return info

def cmd_info(args):
    """Detect device for screenshots or scan a folder."""
    assets_dir = Path(args.assets) if hasattr(args, 'assets') and args.assets else get_assets_dir()
    device_dict = load_json(assets_dir)

    image_paths = _gather_image_paths(args.files)
    if not image_paths:
        print(f"{C.red('No images found.')}", file=sys.stderr)
        return

    results = []
    for p in image_paths:
        try:
            info = _info_for_image(p, device_dict)
            results.append(info)
        except (
            ValueError,
            FileNotFoundError,
            OSError,
            UnidentifiedImageError,
            Image.DecompressionBombWarning,
            Image.DecompressionBombError,
        ) as e:
            results.append({"file": str(p), "name": p.name, "error": str(e)})

    if args.json:
        print(json.dumps(results if len(results) > 1 else results[0], indent=2))
        return

    # Pretty print
    matched = [r for r in results if r.get("device")]
    unmatched = [r for r in results if not r.get("device")]

    if len(image_paths) > 1:
        print(f"\n  {C.bold('Scanned')} {len(image_paths)} images: "
              f"{C.green(str(len(matched)) + ' matched')}, "
              f"{C.red(str(len(unmatched)) + ' unknown') if unmatched else C.dim('0 unknown')}")

    for r in results:
        print()
        print(f"  {C.bold(r['name'])}")
        if r.get("error"):
            print(f"  {C.red('✗')} {r['error']}")
            continue

        dims = f'{r["width"]} × {r["height"]}'
        print(f"  {C.dim(dims)}")

        device = r["device"]
        colors = r.get("colors", [])
        variants = r.get("variants", [])

        print(f"  {C.green('✓')} {C.bold(device)}")

        if r.get("is_variant"):
            print(f"    {C.dim('Primary match:')} {r['primary_match']} {C.dim('→ variant resolved')}")

        if colors:
            print(f"    {C.cyan(str(len(colors)))} colors: {C.dim(', '.join(colors[:5]))}"
                  + (f" {C.dim(f'(+{len(colors)-5} more)')}" if len(colors) > 5 else ""))
        else:
            print(f"    {C.dim('No color variants')}")

        if len(variants) > 1:
            alt = [v for v in variants if v != device]
            print(f"    {C.dim('Also available:')} {', '.join(alt)}")

        if r.get("resize_width"):
            print(f"    {C.dim('Scaled from')} {r['width']}px {C.dim('→')} {r['resize_width']}px")
        if r.get("has_mask"):
            print(f"    {C.dim('Mask applied')}")

    # Summary by device when scanning folders with many files
    if len(matched) > 3:
        from collections import Counter
        device_counts = Counter(r["device"] for r in matched)
        print(f"\n  {C.bold('Summary')}")
        for device, count in device_counts.most_common():
            colors = FRAME_COLORS.get(device, [])
            color_tag = f" ({len(colors)} colors)" if colors else ""
            print(f"    {count:3d}× {device}{C.dim(color_tag)}")
        if unmatched:
            print(f"    {C.red(f'{len(unmatched)}× unknown')}")
    print()


def cmd_video_info(args):
    """Probe videos and report matching frame metadata without rendering."""
    try:
        require_ffmpeg_tools()
        validate_color_args(args)
    except (RuntimeError, ValueError) as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    assets_dir = Path(args.assets) if hasattr(args, 'assets') and args.assets else get_assets_dir()
    device_dict = load_json(assets_dir)
    config = load_config()
    user_defaults = config.get("default_colors", {})
    device_index = build_device_name_index(device_dict)

    video_paths = _gather_video_paths(args.files)
    if not video_paths:
        print(f"{C.red('Error')}: No videos found in the specified paths.", file=sys.stderr)
        sys.exit(1)

    try:
        color_values = parse_per_input_colors(getattr(args, "colors", None), len(video_paths))
    except ValueError as e:
        print(f"{C.red('Error')}: {e}", file=sys.stderr)
        sys.exit(1)

    strict_colors = color_values is not None
    results = []
    for idx, path in enumerate(video_paths):
        try:
            info = _video_info_for_path(
                path,
                assets_dir,
                device_dict,
                color_arg=color_arg_for_index(args, color_values, idx),
                strict_color=strict_colors,
                force_device=args.device,
                rotation=_video_rotation(args),
                verbose=args.verbose,
                user_defaults=user_defaults,
                device_index=device_index,
            )
            results.append(info)
        except (ValueError, FileNotFoundError, subprocess.CalledProcessError, RuntimeError) as e:
            results.append({"file": str(path), "name": path.name, "error": str(e)})

    if args.json:
        print(json.dumps(results if len(results) > 1 else results[0], indent=2))
        return

    matched = [r for r in results if r.get("device")]
    failed = [r for r in results if not r.get("device")]
    if len(video_paths) > 1:
        print(f"\n  {C.bold('Scanned')} {len(video_paths)} videos: "
              f"{C.green(str(len(matched)) + ' matched')}, "
              f"{C.red(str(len(failed)) + ' failed') if failed else C.dim('0 failed')}")

    for r in results:
        print()
        print(f"  {C.bold(r['name'])}")
        if r.get("error"):
            print(f"  {C.red('✗')} {r['error']}")
            continue

        dims = f'{r["width"]} × {r["height"]}'
        duration = f'{r["duration"]:.2f}s'
        audio = f", audio: {r['audio_codec']}" if r.get("audio") else ", no audio"
        print(f"  {C.dim(dims)} {C.dim('•')} {duration} {C.dim('•')} {r.get('codec') or 'unknown codec'}{audio}")
        if r.get("rotation") and r["rotation"] != "none":
            print(f"    {C.dim('Rotated:')} {r['source_dimensions']} {C.dim('→')} {r['dimensions']} {C.dim('(' + r['rotation'] + ')')}")
        print(f"  {C.green('✓')} {C.bold(r['device'])}")
        if r.get("is_variant"):
            print(f"    {C.dim('Primary match:')} {r['primary_match']} {C.dim('→ variant resolved')}")
        print(f"    {C.dim('Frame size:')} {r['frame_size']}")
        if r.get("padded"):
            print(f"    {C.dim('Video size:')} {r['output_dimensions']} {C.dim('(padded for MP4)')}")
        if r.get("color"):
            print(f"    {C.dim('Color:')} {r['color']}")
        else:
            print(f"    {C.dim('Color:')} none")
        if r.get("resize_width"):
            print(f"    {C.dim('Scaled from')} {r['width']}px {C.dim('→')} {r['resize_width']}px")
        if r.get("has_mask"):
            mask_note = "missing" if r.get("mask_missing") else "available"
            print(f"    {C.dim('Mask:')} {mask_note}")
    print()


def copy_to_clipboard(path, announce=True):
    """Copy image to macOS clipboard."""
    if sys.platform != "darwin":
        print(f"  {C.yellow('Warning')}: Clipboard copy is only supported on macOS", file=sys.stderr)
        return
    try:
        script = (
            'set the clipboard to '
            '(read (POSIX file (system attribute "FRAMES_CLIPBOARD_PATH")) as «class PNGf»)'
        )
        env = os.environ.copy()
        env["FRAMES_CLIPBOARD_PATH"] = str(path)
        subprocess.run([
            "osascript", "-e",
            script,
        ], check=True, capture_output=True, env=env)
        if announce:
            print(f"  {C.green('Copied to clipboard')}", file=sys.stderr)
    except (subprocess.CalledProcessError, FileNotFoundError):
        print(f"  {C.yellow('Warning')}: Could not copy to clipboard", file=sys.stderr)


def _pack_has_frame(json_path, name):
    """True when NewFrames.json defines a variant with this name."""
    try:
        with open(json_path, encoding="utf-8") as f:
            return name in json.load(f).get("variants", {})
    except (ValueError, OSError, AttributeError):
        return False


def cmd_doctor(args):
    """Diagnose common asset and config problems."""
    config, config_error = read_config_file()
    assets_dir, assets_source = resolve_assets_dir(getattr(args, "assets", None), config or {})
    ok, ver = check_assets_version(assets_dir)
    video_tools_error = _video_tools_error()

    json_path = assets_dir / "NewFrames.json"
    png_count = len(list(assets_dir.glob("*.png"))) if assets_dir.exists() else 0
    issues = []
    notes = []

    if config_error:
        issues.append(f"Config file is unreadable: {config_error}")
    elif config is None:
        notes.append("Config file not found. This is fine if you use defaults or FRAMES_ASSETS.")

    if not assets_dir.exists():
        issues.append(f"Assets directory does not exist: {assets_dir}")
    elif not json_path.exists():
        issues.append(f"NewFrames.json is missing from assets directory: {assets_dir}")
    elif not ok:
        if ver is None:
            issues.append(f"Assets at {assets_dir} do not look like Apple Frames 4.")
        else:
            issues.append(f"Assets are outdated at {assets_dir} (version {ver}).")

    if assets_dir.exists() and ok and png_count == 0:
        issues.append(f"No frame PNGs were found in {assets_dir}.")
    missing = [device for device, frame in LATEST_PACK_FRAMES.items() if not _pack_has_frame(json_path, frame)]
    if ok and missing:
        notes.append(
            f"This asset pack predates {' and '.join(missing)}. "
            "Run `frames setup` to download the current standard pack."
        )

    bad_default_colors = []
    if config and isinstance(config.get("default_colors"), dict):
        for device, color in config["default_colors"].items():
            matches = [
                name for name, colors in FRAME_COLORS.items()
                if name.replace(" Portrait", "").replace(" Landscape", "") == device
            ]
            if matches and all(color not in FRAME_COLORS[name] for name in matches):
                bad_default_colors.append(f"{device}: {color}")
    if bad_default_colors:
        issues.append("Some saved default colors no longer match supported device colors.")
    if video_tools_error:
        issues.append(f"Video tools unavailable: {video_tools_error}")

    if assets_source == "FRAMES_ASSETS":
        notes.append("Using FRAMES_ASSETS from the environment.")
    elif assets_source == "--assets":
        notes.append("Using assets directory from the CLI flag.")
    elif assets_source == "default" and sys.platform == "darwin":
        notes.append("Using the Apple Frames Shortcuts/iCloud assets directory.")
    elif assets_source == "app-data":
        notes.append("Using the fallback Application Support assets directory.")

    next_steps = []
    if any("Config file is unreadable" in issue for issue in issues):
        next_steps.append(f"Fix or remove {CONFIG_FILE}.")
    if any("Assets" in issue or "NewFrames.json" in issue or "frame PNGs" in issue for issue in issues):
        next_steps.append("Run `frames setup` to re-download or re-point your assets.")
    if bad_default_colors:
        next_steps.append("Run `frames colors` to save fresh defaults, or remove stale entries from config.")
    if video_tools_error:
        next_steps.append(f"Install video tools: {_video_tools_install_hint(video_tools_error)}")
    if not next_steps:
        next_steps.append("No action needed.")

    result = {
        "ok": not issues,
        "assets_path": str(assets_dir),
        "assets_source": assets_source,
        "assets_version": ver,
        "frame_pngs": png_count,
        "config_path": str(CONFIG_FILE),
        "config_present": CONFIG_FILE.exists(),
        "video_tools": {
            "ok": video_tools_error is None,
            "error": video_tools_error,
            "install": None if video_tools_error is None else _video_tools_install_hint(video_tools_error),
        },
        "issues": issues,
        "notes": notes,
        "next_steps": next_steps,
    }
    if bad_default_colors:
        result["bad_default_colors"] = bad_default_colors

    if args.json:
        print(json.dumps(result, indent=2))
        return

    print()
    status = C.green("OK") if result["ok"] else C.red("Needs attention")
    print(f"  {C.bold('Frames Doctor')} {status}")
    print(f"  {C.bold('Assets:')} {assets_dir}")
    print(f"  {C.bold('Source:')} {assets_source}")
    version_text = f"v{ver}" if ver is not None else "unknown"
    print(f"  {C.bold('Version:')} {version_text}")
    print(f"  {C.bold('Frame PNGs:')} {png_count}")
    video_status = C.green("OK") if video_tools_error is None else C.yellow("Missing")
    print(f"  {C.bold('Video tools:')} {video_status}")
    print(f"  {C.bold('Config:')} {CONFIG_FILE}")

    if notes:
        print()
        print(f"  {C.bold('Notes')}")
        for note in notes:
            print(f"    {C.dim('-')} {note}")

    if issues:
        print()
        print(f"  {C.bold('Issues')}")
        for issue in issues:
            print(f"    {C.red('•')} {issue}")

    print()
    print(f"  {C.bold('Next steps')}")
    for step in next_steps:
        print(f"    {C.cyan('•')} {step}")
    print()

# ── Argument Parsing ─────────────────────────────────────────────────────────

def build_parser():
    epilog = (
        "Default framing flags also work without the `frame` subcommand.\n"
        "Global options --json, --no-color, --assets, and --verbose work before or after a command.\n"
        "Examples:\n"
        "  frames -m shot1.png shot2.png\n"
        "  frames -m --no-scale shot1.png shot2.png\n"
        "  frames --json video-info recording.mp4\n"
        "  frames -d \"iPhone Duo Outer Open\" duo.png\n"
        "  frames video --codec hevc-alpha recording.mp4\n"
        "  frames video --help\n"
        "  frames frame --help\n"
        "  frames doctor"
    )
    p = argparse.ArgumentParser(
        prog="frames",
        description="Frame screenshots and videos with Apple device bezels",
        add_help=True,
        epilog=epilog,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p.add_argument("--version", action="version", version=f"frames v{VERSION}")
    p.add_argument("--no-color", action="store_true", help="Disable colored output")
    p.add_argument("--json", action="store_true", help="Output JSON for frame, info, video, video-info, and doctor")
    p.add_argument("--assets", default=None, help="Assets directory path")
    p.add_argument("-v", "--verbose", action="store_true", help="Verbose output")

    sub = p.add_subparsers(dest="cmd")

    # Default frame command (also works without subcommand)
    frame_p = sub.add_parser("frame", help="Frame screenshots (default command)")
    frame_p.add_argument("files", nargs="*", help="Screenshot files or directories to frame")
    frame_p.add_argument("--color", "-c", help="Frame color name, index, or 'random'")
    frame_p.add_argument("--colors", help="Comma-separated per-input colors (e.g. Silver,random)")
    frame_p.add_argument("--merge", "-m", action="store_true", help="Merge framed images side by side")
    frame_p.add_argument("--batch", "-b", type=int, metavar="N", help="Merge in batches of N, at least 2 (e.g. -b 3 for groups of 3)")
    frame_p.add_argument("--spacing", "-s", type=int, default=60, help="Merge spacing in pixels (default: 60)")
    frame_p.add_argument("--no-scale", action="store_true", help="Disable proportional scaling when merging different devices")
    frame_p.add_argument("--output", "-o", help="Output directory")
    frame_p.add_argument("--copy", action="store_true", help="Copy a single output to the macOS clipboard")
    frame_p.add_argument("--device", "-d", help='Force a named frame (e.g. "iPhone Duo Outer Open" for outer screen + back)')
    frame_p.add_argument("-f", action="store_const", const="framed", dest="subfolder", help="Save to a framed subfolder next to originals")
    frame_p.add_argument("--subfolder", dest="subfolder", metavar="NAME", help="Save to custom subfolder (e.g. --subfolder mockups)")

    # Video command
    video_epilog = (
        "Video requirements: ffmpeg 5.1+ and ffprobe 5.1+ must be on PATH.\n"
        "Audio: single videos preserve audio unless --strip-audio is used; "
        "simultaneous merges omit mixed audio; --playback-offset concatenates audio.\n"
        "Output: H.264 MP4 with an opaque white canvas by default.\n"
        "Transparency: --alpha or --background transparent uses ProRes 4444 MOV unless --codec hevc-alpha is selected.\n"
        "Use ProRes 4444 for editing, or HEVC alpha for Apple-compatible delivery.\n"
        "HEVC alpha requires macOS and a compatible ffmpeg build.\n"
        "--alpha --codec hevc still selects ProRes; choose --codec hevc-alpha explicitly.\n"
        "Presets: best is the default for H.264/HEVC. balanced and compact use lower hardware bitrate or higher software CRF for smaller files.\n"
        "HEVC alpha target bitrates: compact 4 Mbps, balanced 7 Mbps, best 10 Mbps.\n"
        "Presets do not change ProRes output; compact does not shrink ProRes exports.\n"
        "JSON: codec describes the source; output_codec identifies the export mode.\n"
        "Global options work before or after the command; see frames --help.\n"
        "Examples:\n"
        "  frames video recording.mp4\n"
        "  frames video --preset compact recording.mp4\n"
        "  frames video --preset balanced recording.mp4\n"
        "  frames video --preset best recording.mp4\n"
        "  frames video --rotate counterclockwise ipad-landscape-recording.mp4\n"
        "  frames --json video --strip-audio recording.mp4\n"
        "  frames video -m --alpha 1.mp4 2.mp4\n"
        "  frames video -m --background transparent 1.mp4 2.mp4\n"
        "  frames video -m --playback-offset 1.mp4 2.mp4\n"
        "  frames video --background '#f5f5f5' --codec hevc recording.mp4\n"
        "  frames video --codec hevc-alpha recording.mp4\n"
        "  frames video --codec hevc-alpha --preset compact -o framed.mov recording.mp4\n"
        "  frames video -m --codec hevc-alpha --playback-offset 1.mp4 2.mp4\n"
        "  frames video --alpha recording.mp4"
    )
    video_p = sub.add_parser(
        "video",
        help="Frame screen recordings and videos",
        description="Frame .mp4, .mov, and .m4v videos with Apple device bezels.",
        epilog=video_epilog,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    video_p.add_argument("files", nargs="*", help="Video files or directories to frame")
    video_p.add_argument("--color", "-c", help="Frame color name, index, or 'random'")
    video_p.add_argument("--colors", help="Comma-separated per-input colors (e.g. Silver,random)")
    video_p.add_argument("--merge", "-m", action="store_true", help="Merge framed videos side by side")
    video_p.add_argument("--playback-offset", action="store_true", help="Play merged videos sequentially left to right (requires --merge)")
    video_p.add_argument("--strip-audio", action="store_true", help="Remove audio from output")
    video_p.add_argument("--background", default=None, help="Canvas and padding: white, black, transparent, or #RRGGBB; overrides default white or transparent with --alpha/--codec hevc-alpha")
    video_p.add_argument("--codec", choices=("h264", "hevc", "prores", "hevc-alpha"), default="h264", help="Output codec (default: h264); hevc-alpha is macOS-only; ProRes and HEVC alpha write MOV")
    video_p.add_argument("--alpha", action="store_true", help="Use transparent ProRes MOV unless --codec hevc-alpha is set; --background overrides transparency")
    video_p.add_argument("--preset", choices=tuple(VIDEO_PRESETS), default=DEFAULT_VIDEO_PRESET, help="H.264/HEVC/HEVC-alpha size/quality preset (default: best; no effect on ProRes)")
    video_p.add_argument("--quality", type=int, default=None, help="Software H.264/HEVC CRF override, 0-51; lower is higher quality; not supported for hevc-alpha")
    video_p.add_argument("--rotate", choices=tuple(VIDEO_ROTATIONS), default="none", help="Rotate video before device detection/framing: none, clockwise, counterclockwise, or 180")
    video_p.add_argument("--spacing", "-s", type=int, default=60, help="Merge spacing in pixels (default: 60)")
    video_p.add_argument("--no-scale", action="store_true", help="Disable proportional scaling when merging different devices")
    video_p.add_argument("--output", "-o", help="Output directory or single output file; explicit ProRes/HEVC-alpha filenames must end in .mov")
    video_p.add_argument("--device", "-d", help='Force a named frame (e.g. "iPhone Duo Outer Open" for outer screen + back)')

    # List command
    sub.add_parser("list", help="List supported devices")

    # List colors command (partial match)
    colors_p = sub.add_parser("list-colors", help="Show colors for a specific device")
    colors_p.add_argument("device_name", help="Device name (partial match)")

    # Colors command (browse all)
    sub.add_parser("colors", help="Browse colors and save defaults")

    # Info command
    info_p = sub.add_parser("info", help="Detect device for screenshots or folders")
    info_p.add_argument("files", nargs="+", help="Screenshot files or directories to scan")

    # Video info command
    video_info_epilog = (
        "Use this before rendering when you need the matched device, frame size, "
        "duration, source codec, or audio state.\n"
        "This probe cannot verify HEVC auxiliary alpha; inspect it with a native Apple decoder.\n"
        "Global options work before or after the command; see frames --help.\n"
        "Examples:\n"
        "  frames video-info recording.mp4\n"
        "  frames --json video-info recording.mp4\n"
        "  frames --json video-info --rotate counterclockwise ipad-landscape-recording.mp4\n"
        "  frames --json video-info --colors 'Silver,random' 1.mp4 2.mp4"
    )
    video_info_p = sub.add_parser(
        "video-info",
        help="Probe videos and show matching frame metadata",
        description="Probe videos and resolve Apple frame metadata without rendering.",
        epilog=video_info_epilog,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    video_info_p.add_argument("files", nargs="+", help="Video files or directories to scan")
    video_info_p.add_argument("--color", "-c", help="Frame color name, index, or 'random'")
    video_info_p.add_argument("--colors", help="Comma-separated per-input colors (e.g. Silver,random)")
    video_info_p.add_argument("--device", "-d", help='Force a named frame (e.g. "iPhone Duo Outer Open" for outer screen + back)')
    video_info_p.add_argument("--rotate", choices=tuple(VIDEO_ROTATIONS), default="none", help="Rotate video before device detection: none, clockwise, counterclockwise, or 180")

    # Setup command
    setup_p = sub.add_parser("setup", help="Download assets or configure path")
    setup_p.add_argument("path", nargs='?', default=None, help="Existing assets folder (bare frames setup is interactive)")
    setup_p.add_argument("--subfolder", action="store_true", default=None, help="Set default to a framed subfolder")
    setup_p.add_argument("--no-subfolder", action="store_false", dest="subfolder", help="Set default to next to originals")

    # Doctor command
    sub.add_parser("doctor", help="Diagnose asset and config problems")

    # Accept global options after any command without resetting earlier values.
    for command_parser in sub.choices.values():
        command_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
        command_parser.add_argument("--no-color", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
        command_parser.add_argument("-v", "--verbose", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
        command_parser.add_argument("--assets", default=argparse.SUPPRESS, help=argparse.SUPPRESS)

    return p

def main():
    p = build_parser()

    # Pre-process argv: if the first non-flag arg isn't a known subcommand,
    # assume it's a file and inject "frame" as the subcommand
    known_cmds = {"frame", "video", "video-info", "list", "list-colors", "colors", "info", "setup", "doctor", "-h", "--help", "--version"}
    argv = sys.argv[1:]
    if argv:
        global_flags = {"-h", "--help", "--version", "--no-color", "--json", "-v", "--verbose"}
        insert_at = 0
        idx = 0
        while idx < len(argv):
            arg = argv[idx]
            if arg in known_cmds:
                break
            if arg in global_flags:
                idx += 1
                insert_at = idx
                continue
            if arg == "--assets":
                idx += 2
                insert_at = min(idx, len(argv))
                continue
            if arg.startswith("--assets="):
                idx += 1
                insert_at = idx
                continue
            argv = argv[:insert_at] + ["frame"] + argv[insert_at:]
            break

    args = p.parse_args(argv)

    # Disable colors if requested
    if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
        C.enabled = False

    try:
        # No command → show splash
        if args.cmd is None:
            if not args.json:
                show_splash()
            return

        # Resolve assets directory (setup doesn't need it)
        if args.cmd not in ("setup", "doctor"):
            args.assets = str(get_assets_dir(args.assets))

        # Route commands
        cmds = {
            "frame": cmd_frame,
            "video": cmd_video,
            "video-info": cmd_video_info,
            "list": cmd_list,
            "list-colors": cmd_list_colors,
            "colors": cmd_colors,
            "info": cmd_info,
            "setup": cmd_setup,
            "doctor": cmd_doctor,
        }
        handler = cmds.get(args.cmd)
        if handler:
            # Check assets exist and are v4+ (except for setup, colors, list-colors)
            if args.cmd not in ("setup", "colors", "list-colors", "doctor"):
                ok, ver = check_assets_version(Path(args.assets))
                if not ok:
                    if not sys.stdin.isatty() or args.json:
                        reason = "not found" if ver is None else f"outdated (version {ver})"
                        if args.json:
                            print(json.dumps({"error": f"Assets {reason}", "setup_required": True}))
                        else:
                            print(f"{C.red('Error')}: Assets {reason}. Run 'frames setup' interactively.", file=sys.stderr)
                        sys.exit(1)
                    reason = "not found" if ver is None else f"outdated (version {ver})"
                    if guided_setup(reason=reason):
                        args.assets = str(get_assets_dir())
                    else:
                        sys.exit(1)
            handler(args)
    except ValueError as error:
        if args.json:
            print(json.dumps({"error": str(error)}))
        else:
            print(f"{C.red('Error')}: {error}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()