#!/usr/bin/env php
<?php
/**
 * shotbot | PHP CLI for the Shotbot screenshot API.
 *
 * Single-file standalone script. Requires PHP 8.0+ with the curl extension.
 * Run `./shotbot help` for usage.
 *
 * Copyright (c) 2026 Valentin Beck
 * SPDX-License-Identifier: MIT
 */
declare(strict_types=1);

const SHOTBOT_VERSION  = '0.3.0';
const SHOTBOT_API_BASE_DEFAULT = 'https://api.shotbot.net';
const SHOTBOT_POLL_INITIAL_S   = 2;
const SHOTBOT_POLL_INTERVAL_S  = 2;
const SHOTBOT_POLL_TIMEOUT_S   = 180;

// ── Bootstrap ────────────────────────────────────────────────────────────────
if (PHP_SAPI !== 'cli')         { fwrite(STDERR, "shotbot: must be run from the command line\n"); exit(2); }
if (PHP_VERSION_ID < 80000)     { fwrite(STDERR, "shotbot: requires PHP 8.0+ (got " . PHP_VERSION . ")\n"); exit(2); }
if (!extension_loaded('curl'))  { fwrite(STDERR, "shotbot: the php-curl extension is required\n"); exit(2); }

// ── Output helpers ───────────────────────────────────────────────────────────
function sb_use_color(): bool {
    static $cached = null;
    if ($cached !== null) return $cached;
    if (getenv('NO_COLOR') !== false) return $cached = false;
    $cached = function_exists('stream_isatty') ? @stream_isatty(STDOUT) : false;
    return $cached;
}
function sb_clr(string $s, string $code): string {
    return sb_use_color() ? "\033[{$code}m{$s}\033[0m" : $s;
}
function sb_note(string $s = ''): void { fwrite(STDOUT, $s . "\n"); }
function sb_ok(string $s):   void { fwrite(STDOUT, sb_clr('✓', '32') . ' ' . $s . "\n"); }
function sb_warn(string $s): void { fwrite(STDERR, sb_clr('!', '33') . ' ' . $s . "\n"); }
function sb_err(string $s):  void { fwrite(STDERR, sb_clr('✗', '31') . ' ' . $s . "\n"); }
function sb_dim(string $s): string { return sb_clr($s, '2'); }
function sb_b(string $s):   string { return sb_clr($s, '1'); }

// ── Config ───────────────────────────────────────────────────────────────────
function sb_home(): string {
    $h = getenv('HOME') ?: (getenv('USERPROFILE') ?: '');
    if ($h === '') { sb_err('cannot determine home directory'); exit(2); }
    return rtrim($h, '/\\');
}
function sb_config_dir():  string { return sb_home() . '/.shotbot-php-cli'; }
function sb_config_path(): string { return sb_config_dir() . '/config.json'; }

function sb_config_load(): array {
    $p = sb_config_path();
    if (!is_file($p)) return [];
    $j = json_decode((string)@file_get_contents($p), true);
    return is_array($j) ? $j : [];
}
function sb_config_save(array $c): void {
    $d = sb_config_dir();
    if (!is_dir($d) && !@mkdir($d, 0700, true) && !is_dir($d)) {
        sb_err("cannot create config directory: $d"); exit(2);
    }
    @chmod($d, 0700);
    $p = sb_config_path();
    if (@file_put_contents($p, json_encode($c, JSON_PRETTY_PRINT) . "\n", LOCK_EX) === false) {
        sb_err("cannot write config file: $p"); exit(2);
    }
    @chmod($p, 0600);
}

function sb_api_key(): string {
    $env = getenv('SHOTBOT_API_KEY');
    if (is_string($env) && trim($env) !== '') return trim($env);
    $cfg = sb_config_load();
    if (!empty($cfg['api_key'])) return (string)$cfg['api_key'];
    return sb_prompt_for_key();
}

// ── Persistent capture defaults ──────────────────────────────────────────────
// Keys allowed in config.json `defaults`. Type drives coercion in `set` and
// validation when merging into the parsed CLI options at capture time.
function sb_default_keys(): array {
    return [
        // All tiers
        'preset'          => 'string',  // og|mobile|youtube_thumbnail|square|reel|pinterest|tablet|desktop|desktop_hd|twitter_header|linkedin_banner|hero_banner
        'frame'           => 'string',  // rounded|shadow|browser_chrome|browser_chrome_dark|mobile|mobile_light|tablet|tablet_light|laptop|polaroid|gradient|shotbot_brand
        'format'          => 'string',  // jpg|png|webp|avif|pdf
        'viewport'        => 'int',     // 280..3840 (Pro custom; common 360..1920)
        'output-size'     => 'int',     // 120..1920
        'wait'            => 'int',     // 0..120
        'ratio'           => 'string',  // 16:9, 4:3, 1:1, ...
        'color-scheme'    => 'string',  // dark|light (sets prefers-color-scheme)
        'full-page'       => 'bool',
        'nojs'            => 'bool',
        'hidpi'           => 'bool',
        'reduce-motion'   => 'bool',    // emulate prefers-reduced-motion: reduce
        // Pro
        'dismiss-cookies' => 'string',  // accept|reject
        'scroll'          => 'bool',
        'scroll-offset'   => 'int',     // 0..30000, scroll N px before capture
        'scroll-to'       => 'string',  // CSS selector, scrollIntoView before capture
        'block-ads'       => 'bool',
        'crop-height'     => 'int',
        'selector'        => 'string',
        'autoplay-videos'     => 'bool',
        'omit-background'     => 'bool',
        'emulate-print-media' => 'bool',
        'http-auth-user'  => 'string',
        'http-auth-pass'  => 'string',
        // PDF (only meaningful when format=pdf)
        'pdf-page-size'   => 'string',  // A4|A3|A5|Letter|Legal|Tabloid
        'pdf-margin'      => 'int',     // 0..50 mm
        'pdf-scale'       => 'float',   // 0.10..2.00
        'pdf-landscape'   => 'bool',
        // CLI ergonomics
        'output'          => 'string',  // path or "true" for cwd-auto-name
        'cdn'             => 'bool',     // upload to the public CDN (default: private)
        'timeout'         => 'int',     // poll timeout, seconds
    ];
}

function sb_coerce(string $key, string $raw, string $type): mixed {
    if ($type === 'bool') {
        $v = strtolower(trim($raw));
        if (in_array($v, ['1', 'true', 'yes', 'on'],  true)) return true;
        if (in_array($v, ['0', 'false', 'no', 'off'], true)) return false;
        sb_err("invalid boolean for $key: '$raw' (use true|false)"); exit(2);
    }
    if ($type === 'int') {
        if (!preg_match('/^-?\d+$/', trim($raw))) {
            sb_err("invalid integer for $key: '$raw'"); exit(2);
        }
        return (int)$raw;
    }
    if ($type === 'float') {
        if (!is_numeric(trim($raw))) {
            sb_err("invalid number for $key: '$raw'"); exit(2);
        }
        return (float)$raw;
    }
    // Enum keys: validate against the canonical set defined in capture_options.php.
    static $enums = [
        'color-scheme'    => ['dark', 'light'],
        'dismiss-cookies' => ['accept', 'reject'],
        'format'          => ['jpg', 'png', 'webp', 'avif', 'pdf'],
        'pdf-page-size'   => ['A4', 'A3', 'A5', 'Letter', 'Legal', 'Tabloid'],
    ];
    if (isset($enums[$key]) && !in_array($raw, $enums[$key], true)) {
        sb_err("invalid value for $key: '$raw' (allowed: " . implode('|', $enums[$key]) . ')');
        exit(2);
    }
    return $raw;
}

function sb_apply_defaults(array $opts): array {
    $cfg = sb_config_load();
    $defaults = is_array($cfg['defaults'] ?? null) ? $cfg['defaults'] : [];
    if (!$defaults) return $opts;
    $allowed = sb_default_keys();
    foreach ($defaults as $k => $v) {
        if (!isset($allowed[$k]))   continue;     // unknown key: ignore silently
        if (array_key_exists($k, $opts)) continue; // CLI flag wins
        $opts[$k] = $v;
    }
    return $opts;
}
function sb_api_base(): string {
    $b = getenv('SHOTBOT_API_BASE');
    return is_string($b) && trim($b) !== '' ? rtrim(trim($b), '/') : SHOTBOT_API_BASE_DEFAULT;
}

function sb_prompt_for_key(): string {
    sb_note();
    sb_note(sb_b('No Shotbot API key configured.'));
    sb_note('Get one at ' . sb_clr('https://www.shotbot.net/api-key/', '36'));
    sb_note();
    fwrite(STDOUT, 'API key: ');
    $key = trim((string)fgets(STDIN));
    if ($key === '') { sb_err('empty key, aborting'); exit(2); }
    if (!preg_match('/^[0-9A-Za-z]{12}$/', $key)) {
        sb_warn('key does not match expected format (12 alphanumeric chars), saving anyway');
    }
    $cfg = sb_config_load();
    $cfg['api_key'] = $key;
    sb_config_save($cfg);
    sb_ok('Saved to ' . sb_config_path() . ' (chmod 600)');
    sb_note();
    return $key;
}

// ── HTTP ─────────────────────────────────────────────────────────────────────
function sb_http(string $method, string $path, ?array $body = null): array {
    $url = sb_api_base() . $path;
    $ch  = curl_init($url);
    $headers = [
        'Accept: application/json',
        'User-Agent: shotbot-php-cli/' . SHOTBOT_VERSION,
    ];
    $opts = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT        => 60,
        CURLOPT_FOLLOWLOCATION => false,
    ];
    if ($method === 'POST') {
        $opts[CURLOPT_POST]       = true;
        $opts[CURLOPT_POSTFIELDS] = json_encode($body ?? new stdClass);
        $headers[]                = 'Content-Type: application/json';
    } elseif ($method !== 'GET') {
        $opts[CURLOPT_CUSTOMREQUEST] = $method;
    }
    $opts[CURLOPT_HTTPHEADER] = $headers;
    curl_setopt_array($ch, $opts);
    $raw  = curl_exec($ch);
    $code = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $cerr = curl_error($ch);
    curl_close($ch);
    if ($raw === false) { sb_err("network error: $cerr"); exit(3); }
    $j = json_decode((string)$raw, true);
    return ['code' => $code, 'json' => is_array($j) ? $j : null, 'raw' => (string)$raw];
}

function sb_download(string $url, string $dest): int {
    $fp = @fopen($dest, 'wb');
    if (!$fp) { sb_err("cannot open $dest for writing"); exit(2); }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_FILE           => $fp,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT        => 120,
        CURLOPT_USERAGENT      => 'shotbot-php-cli/' . SHOTBOT_VERSION,
    ]);
    $ok   = curl_exec($ch);
    $code = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    fclose($fp);
    if (!$ok || $code !== 200) {
        @unlink($dest);
        sb_err("download failed (HTTP $code)"); exit(3);
    }
    return (int)@filesize($dest);
}

// ── Args parser ──────────────────────────────────────────────────────────────
/**
 * Parse argv into [cmd, opts(assoc), pos(list)].
 * Recognises --flag, --key=value, --key value, and bare positional args.
 */
function sb_parse_args(array $argv): array {
    array_shift($argv); // script
    $cmd = '';
    if (!empty($argv) && !str_starts_with($argv[0], '-')) {
        $cmd = (string)array_shift($argv);
    }
    $opts = []; $pos = [];
    $n = count($argv);
    for ($i = 0; $i < $n; $i++) {
        $a = $argv[$i];
        if (str_starts_with($a, '--')) {
            $tail = substr($a, 2);
            if (str_contains($tail, '=')) {
                [$k, $v] = explode('=', $tail, 2);
                $opts[$k] = $v;
            } else {
                $next = $argv[$i + 1] ?? null;
                if ($next !== null && !str_starts_with($next, '-')) {
                    $opts[$tail] = $next; $i++;
                } else {
                    $opts[$tail] = true;
                }
            }
        } elseif (str_starts_with($a, '-') && strlen($a) > 1) {
            $opts[substr($a, 1)] = true;
        } else {
            $pos[] = $a;
        }
    }
    return ['cmd' => $cmd, 'opts' => $opts, 'pos' => $pos];
}

// ── Commands ─────────────────────────────────────────────────────────────────
function sb_cmd_help(): void {
    $v   = SHOTBOT_VERSION;
    $cfg = sb_config_path();
    echo <<<HELP

  shotbot v{$v}  PHP CLI for the Shotbot screenshot API

  USAGE
    shotbot <command> [options]

  COMMANDS
    capture                Capture a single URL (see CAPTURE OPTIONS).
    status                 Show account plan, credits, quota and in-flight captures.
    set <key> [value]      Set a persistent default for `capture` (see DEFAULTS).
                           Booleans accept true/false/yes/no/1/0; bare `set <key>`
                           on a boolean is shorthand for `set <key> true`.
    unset <key>            Remove a persistent default.
    defaults               List currently-set persistent defaults.
    defaults --keys        List every key you can `set` and its type.
    config                 Print the path to the config file.
    reset                  Re-prompt for the API key (overwrites the stored one).
    version                Print the version and exit.
    help                   Print this help.

  CAPTURE OPTIONS  (free tier)
    --url=URL              Required. The page to capture (http/https).
    --preset=NAME          Named output bundle: og, mobile, youtube_thumbnail,
                           square, reel, pinterest, tablet (free); desktop,
                           desktop_hd, twitter_header, linkedin_banner,
                           hero_banner (Pro).
                           Fills viewport/output-size/crop-height in one go.
    --frame=NAME           Decorative frame around the image: rounded, shadow,
                           browser_chrome, browser_chrome_dark, mobile,
                           mobile_light, tablet, tablet_light, laptop, polaroid,
                           gradient, shotbot_brand.
                           Free accounts get a "shotbot.fr" mark | clean with Pro.
    --format=FMT           jpg | png | webp | avif | pdf           (default: jpg)
    --viewport=N           Viewport width, common 360..1920; Pro 280..3840 (default: 1280)
    --output-size=N        Resize the result. 120..1920 px (default: same as viewport)
    --wait=N               Seconds to wait after page load 0..120  (default: 5)
    --ratio=R              16:9, 4:3, 1:1, 9:16, etc.              (default: 16:9)
    --full-page            Capture the full scrollable page (max 30000 px).
    --nojs                 Disable JavaScript before navigation.
    --color-scheme=dark|light  Force prefers-color-scheme (matches API field).
    --hidpi                Render at 2x device pixel ratio.
    --reduce-motion        Emulate prefers-reduced-motion: reduce (well-built
                           sites skip animations | cleaner captures).

  CAPTURE OPTIONS  (Pro)
    --dismiss-cookies=accept|reject   Auto-handle cookie consent banners.
    --scroll                          Scroll the page before capture
                                      (triggers lazy-loaded images).
    --scroll-offset=N                 Scroll down N px before capture (0..30000).
    --scroll-to=CSS                   Scroll the matched element into view before
                                      capture (mutually exclusive with --scroll-offset).
    --block-ads                       Block ad-network requests.
    --crop-height=N                   Crop the result to N px tall (10..20000),
                                      overrides --ratio, implies full-page.
    --selector=CSS                    Capture only the matched DOM element.
    --autoplay-videos                 Allow unmuted <video autoplay> to start
                                      without a user gesture.
    --omit-background                 Transparent backdrop (PNG/WebP/AVIF only;
                                      JPG flattens to black).
    --emulate-print-media             Render with the page's print stylesheet.
    --http-auth-user=U
    --http-auth-pass=P                HTTP Basic Auth credentials.

  CAPTURE OPTIONS  (PDF only - when --format=pdf)
    --pdf-page-size=SIZE   A4 | A3 | A5 | Letter | Legal | Tabloid (default: A4)
    --pdf-margin=N         Page margin in mm 0..50                  (default: 10)
    --pdf-scale=F          Rendering scale 0.10..2.00               (default: 1.00)
    --pdf-landscape        Landscape orientation.

  CLI OPTIONS
    By default a capture is private and saved to the current directory as
    ./HOST-TOKEN.FMT. Use --output to choose where, --cdn for a public URL,
    or --json for machine output (the last two do not save a file).
    --output[=PATH]        Choose where to save (default: cwd, auto-named):
                             --output                 -> ./HOST-TOKEN.FMT (cwd, auto-named)
                             --output=DIR/            -> save into DIR/ (auto-named)
                             --output=path/file.jpg   -> save to that exact path
    --cdn                  Upload to the public CDN and return a permanent URL
                           (no local file is saved). Without it, captures stay
                           private (not on the CDN) and auto-expire server-side.
    --json                 Print the full API response as JSON (no file saved).
    --timeout=N            Max seconds to wait for the capture      (default: 180)

  DEFAULTS
    `shotbot set <key> [value]` stores a default in the config file. Any default
    is applied to every `capture` call; per-call flags always override.

    Settable keys (run `shotbot defaults --keys` for the full list):
      Free tier:
        format          (string)   viewport        (int)   output-size  (int)
        wait            (int)      ratio           (string)
        color-scheme    (dark|light)               full-page (bool)
        nojs            (bool)     hidpi           (bool)   reduce-motion (bool)
      Pro:
        dismiss-cookies (accept|reject)            scroll    (bool)
        block-ads       (bool)     crop-height     (int)
        selector        (string)   autoplay-videos (bool)
        omit-background (bool)     emulate-print-media (bool)
        http-auth-user / http-auth-pass (string)
      PDF:
        pdf-page-size   (A4|A3|A5|Letter|Legal|Tabloid)
        pdf-margin      (int)      pdf-scale       (float) pdf-landscape (bool)
      CLI:
        output          (string)   cdn             (bool)  timeout      (int)

    Examples:
      shotbot set full-page                     # always full-page
      shotbot set output ./shots/               # always save into ./shots/
      shotbot set cdn true                      # always publish to the public CDN
      shotbot set viewport 1440                 # always render at 1440 px
      shotbot set format webp                   # always webp
      shotbot set color-scheme dark             # always emulate prefers-color-scheme: dark
      shotbot defaults                          # show what's stored
      shotbot unset full-page                   # forget that default

    Note: captures are private by default and saved to the current directory.
    They are never published on the CDN unless you pass `--cdn` (or `set cdn
    true`), which returns a permanent public URL instead of saving a file.

  ENVIRONMENT
    SHOTBOT_API_KEY        Override the stored API key.
    SHOTBOT_API_BASE       Override the API base URL (default: https://api.shotbot.net).
    NO_COLOR               Disable ANSI color output.

  CONFIG FILE
    {$cfg}
    Stores: api_key (string), defaults (object). Chmod 600.

  EXIT CODES
    0  success                       4  API returned an error response
    2  bad invocation / config       5  waitlisted (quota exhausted)
    3  network error                 6  capture failed server-side
                                     7  polling timeout

  EXAMPLES
    shotbot capture --url=https://example.com
    shotbot capture --url=https://example.com --format=webp --viewport=1440
    shotbot capture --url=https://example.com --full-page --output=shot.jpg
    shotbot capture --url=https://example.com --json | jq .

HELP;
}

function sb_cmd_status(array $opts): void {
    $key = sb_api_key();
    $r   = sb_http('GET', '/account?key=' . rawurlencode($key));
    if ($r['code'] === 401) {
        sb_err('invalid API key  (run ' . sb_b('shotbot reset') . ' to update it)');
        exit(2);
    }
    if ($r['code'] !== 200 || !$r['json']) {
        sb_err('request failed: ' . ($r['json']['error'] ?? 'HTTP ' . $r['code']));
        exit(3);
    }
    if (!empty($opts['json'])) {
        echo json_encode($r['json'], JSON_PRETTY_PRINT) . "\n";
        return;
    }
    $d   = $r['json'];
    $col = 14;
    $lbl = fn($s) => sb_dim(str_pad($s, $col));

    $plan = $d['plan'];
    if ($d['plan'] === 'pro' && !empty($d['pro_until'])) {
        $dt   = date('Y-m-d', (int)$d['pro_until']);
        $plan = sb_b('pro') . sb_dim('  (until ' . $dt . ')');
    }
    $quota = ($d['quota_total'] > 0)
        ? $d['quota_used'] . ' / ' . $d['quota_total'] . '  ' . sb_dim('(' . $d['quota_remaining'] . ' remaining)')
        : sb_dim('—');
    $credit   = $d['credit'] > 0 ? (string)$d['credit'] : sb_dim('0');
    $inflight = $d['inflight'] . ' / ' . $d['inflight_cap'];

    sb_note('');
    sb_note($lbl('plan')      . $plan);
    sb_note($lbl('credits')   . $credit);
    sb_note($lbl('quota')     . $quota);
    sb_note($lbl('in flight') . $inflight);
    sb_note('');
}

function sb_cmd_version(): void { echo SHOTBOT_VERSION . "\n"; }
function sb_cmd_config():  void { echo sb_config_path() . "\n"; }

function sb_cmd_reset(): void {
    $cfg = sb_config_load();
    unset($cfg['api_key']);
    sb_config_save($cfg);
    sb_ok('API key cleared.');
    sb_prompt_for_key();
}

function sb_cmd_set(array $pos): void {
    if (count($pos) < 1) {
        sb_err('usage: shotbot set <key> [value]');
        sb_note(sb_dim('list keys: ') . sb_b('shotbot defaults --keys'));
        exit(2);
    }
    $key = $pos[0];
    $allowed = sb_default_keys();
    if (!isset($allowed[$key])) {
        sb_err("unknown key '$key'");
        sb_note(sb_dim('valid keys: ') . implode(', ', array_keys($allowed)));
        exit(2);
    }
    $type = $allowed[$key];
    if (count($pos) < 2) {
        if ($type !== 'bool') {
            sb_err("'$key' is a $type, value required: shotbot set $key <value>");
            exit(2);
        }
        $value = true;
    } else {
        $value = sb_coerce($key, (string)$pos[1], $type);
    }
    $cfg = sb_config_load();
    $cfg['defaults'] ??= [];
    $cfg['defaults'][$key] = $value;
    sb_config_save($cfg);
    $shown = is_bool($value) ? ($value ? 'true' : 'false') : (string)$value;
    sb_ok("default $key = $shown");
}

function sb_cmd_unset(array $pos): void {
    if (count($pos) < 1) { sb_err('usage: shotbot unset <key>'); exit(2); }
    $key = $pos[0];
    $cfg = sb_config_load();
    if (!isset($cfg['defaults'][$key])) {
        sb_warn("no default set for '$key'"); return;
    }
    unset($cfg['defaults'][$key]);
    if (empty($cfg['defaults'])) unset($cfg['defaults']);
    sb_config_save($cfg);
    sb_ok("cleared default $key");
}

function sb_cmd_defaults(array $opts): void {
    if (!empty($opts['keys'])) {
        foreach (sb_default_keys() as $k => $t) sb_note("  $k " . sb_dim("($t)"));
        return;
    }
    $cfg = sb_config_load();
    $d   = is_array($cfg['defaults'] ?? null) ? $cfg['defaults'] : [];
    if (!$d) {
        sb_note('no persistent defaults set.');
        sb_note(sb_dim('try: ') . sb_b('shotbot set full-page true'));
        return;
    }
    sb_note(sb_b('persistent defaults') . sb_dim(' (in ' . sb_config_path() . ')'));
    foreach ($d as $k => $v) {
        $shown = is_bool($v) ? ($v ? 'true' : 'false') : (string)$v;
        sb_note('  ' . $k . sb_dim(' = ') . $shown);
    }
}

function sb_cmd_capture(array $opts): void {
    $opts = sb_apply_defaults($opts);

    $url = $opts['url'] ?? null;
    if (!is_string($url) || $url === '') {
        sb_err('missing required --url');
        sb_note('try: ' . sb_dim('shotbot capture --url=https://example.com'));
        exit(2);
    }
    if (!preg_match('#^https?://#i', $url)) {
        sb_err('--url must start with http:// or https://'); exit(2);
    }

    $body = ['key' => sb_api_key(), 'url' => $url];

    // Captures are private by default: not published on static.shotbot.net,
    // retrieved on demand from the API and auto-expired. Pass --cdn to opt into
    // a permanent public CDN URL instead.
    $body['private'] = empty($opts['cdn']);

    if (!empty($opts['preset']))      $body['preset']         = (string)$opts['preset'];
    if (!empty($opts['frame']))       $body['frame']          = (string)$opts['frame'];
    if (!empty($opts['format']))      $body['format']         = (string)$opts['format'];
    if (!empty($opts['viewport']))    $body['viewport_width'] = (int)$opts['viewport'];
    if (!empty($opts['output-size'])) $body['output_size']    = (int)$opts['output-size'];
    if (!empty($opts['ratio']))       $body['ratio']          = (string)$opts['ratio'];
    if (isset($opts['wait']))         $body['wait_time']      = (int)$opts['wait'];
    if (!empty($opts['full-page']))   $body['fullpage']       = true;
    if (!empty($opts['nojs']))        $body['nojs']           = true;
    if (!empty($opts['hidpi']))       $body['hidpi']          = true;
    if (!empty($opts['color-scheme'])) {
        $cs = (string)$opts['color-scheme'];
        if (!in_array($cs, ['dark', 'light'], true)) {
            sb_err("--color-scheme must be 'dark' or 'light' (got '$cs')"); exit(2);
        }
        $body['color_scheme'] = $cs;
    }
    if (!empty($opts['dismiss-cookies'])) {
        $d = (string)$opts['dismiss-cookies'];
        if (!in_array($d, ['accept', 'reject'], true)) {
            sb_err("--dismiss-cookies must be 'accept' or 'reject' (got '$d')"); exit(2);
        }
        $body['dismiss_cookies'] = $d;
    }
    if (!empty($opts['scroll']))      $body['scroll_before_capture'] = true;
    if (isset($opts['scroll-offset'])) $body['scroll_offset_px'] = (int)$opts['scroll-offset'];
    if (!empty($opts['scroll-to']))   $body['scroll_to']      = (string)$opts['scroll-to'];
    if (!empty($opts['block-ads']))   $body['block_ads']      = true;
    if (!empty($opts['crop-height'])) $body['crop_height']    = (int)$opts['crop-height'];
    if (!empty($opts['selector']))    $body['selector']       = (string)$opts['selector'];
    if (!empty($opts['autoplay-videos']))     $body['autoplay_videos']    = true;
    if (!empty($opts['reduce-motion']))       $body['prefers_reduced_motion'] = true;
    if (!empty($opts['omit-background']))     $body['omit_background']    = true;
    if (!empty($opts['emulate-print-media'])) $body['emulate_print_media'] = true;
    if (!empty($opts['http-auth-user'])) {
        $body['http_auth'] = [
            'user' => (string)$opts['http-auth-user'],
            'pass' => (string)($opts['http-auth-pass'] ?? ''),
        ];
    }
    // PDF options (silently ignored by API when format != pdf)
    if (!empty($opts['pdf-page-size']))      $body['pdf_page_size'] = (string)$opts['pdf-page-size'];
    if (isset($opts['pdf-margin']))          $body['pdf_margin_mm'] = (int)$opts['pdf-margin'];
    if (isset($opts['pdf-scale']))           $body['pdf_scale']     = (float)$opts['pdf-scale'];
    if (!empty($opts['pdf-landscape']))      $body['pdf_landscape'] = true;

    $timeout    = (int)($opts['timeout'] ?? SHOTBOT_POLL_TIMEOUT_S);
    $jsonOnly   = !empty($opts['json']);
    $outputArg  = array_key_exists('output', $opts) ? $opts['output'] : null;

    // CLI default: save to the current directory (auto-named) unless the user
    // asked for a public CDN URL (--cdn) or machine-readable JSON (--json).
    // Captures are private and expire, so a local file is the durable artifact.
    if ($outputArg === null && !$jsonOnly && empty($opts['cdn'])) {
        $outputArg = true;
    }

    // Pre-validate explicit directory targets (so we don't waste a capture).
    if (is_string($outputArg) && $outputArg !== '' &&
        (str_ends_with($outputArg, '/') || str_ends_with($outputArg, '\\'))) {
        $dir = rtrim($outputArg, '/\\') ?: '.';
        if (!is_dir($dir)) { sb_err("output directory does not exist: $dir"); exit(2); }
    }

    if (!$jsonOnly) {
        sb_note(sb_dim('→') . ' POST ' . sb_api_base() . '/capture');
        sb_note('  ' . sb_dim('url:    ') . $url);
        sb_note('  ' . sb_dim('format: ') . ($body['format'] ?? 'jpg') . sb_dim(' · viewport: ') . ($body['viewport_width'] ?? 1280) . sb_dim(' · wait: ') . ($body['wait_time'] ?? 5) . 's');
    }

    $r = sb_http('POST', '/capture', $body);
    $j = $r['json'];

    if ($r['code'] >= 400 || !$j) {
        $msg = $j['error'] ?? $j['message'] ?? $j['detail'] ?? ('HTTP ' . $r['code']);
        sb_err('API error: ' . $msg);
        if ($r['code'] === 401) {
            sb_note(sb_dim('hint: ') . 'run ' . sb_b('shotbot reset') . ' to update your API key');
        } elseif ($r['code'] === 403) {
            $fields = $j['fields'] ?? [];
            if (in_array('url', (array)$fields, true)) {
                sb_note(sb_dim('hint: ') . 'the URL contains a custom TCP port — upgrade to Pro to use it, see ' . sb_clr('https://www.shotbot.net/pro/', '36'));
            } else {
                sb_note(sb_dim('hint: ') . 'this option may require a Pro account, see ' . sb_clr('https://www.shotbot.net/pro/', '36'));
            }
        }
        if ($jsonOnly) sb_note($r['raw']);
        exit(4);
    }

    $status = $j['status'] ?? '';
    if ($status === 'waitlisted') {
        if ($jsonOnly) { echo json_encode($j, JSON_UNESCAPED_SLASHES) . "\n"; exit(5); }
        sb_warn('waitlisted: ' . ($j['detail'] ?? 'quota exhausted'));
        exit(5);
    }
    if (!isset($j['token'])) {
        sb_err('unexpected response (no token)');
        if ($jsonOnly) sb_note($r['raw']);
        exit(4);
    }

    $token = (string)$j['token'];
    $eta   = (int)($j['eta_seconds'] ?? 5);
    $dedup = !empty($j['deduplicated']);
    $jid   = isset($j['job_id']) ? (int)$j['job_id'] : null;

    if (!$jsonOnly) {
        sb_note(sb_dim('  job:    ') . $token . ($jid !== null ? sb_dim(' #' . $jid) : '') . ($dedup ? sb_dim(' (deduplicated)') : ''));
        sb_note(sb_dim('  eta:    ') . '~' . $eta . 's');
        sb_note();
    }

    // Poll
    $start  = time();
    $first  = max(SHOTBOT_POLL_INITIAL_S, min($eta, 8));
    $frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
    $tick   = 0;
    sleep($first);
    while (true) {
        $r2 = sb_http('GET', '/capture/' . rawurlencode($token));
        $s  = $r2['json'] ?? null;
        if ($r2['code'] >= 400 || !$s) {
            if (!$jsonOnly) fwrite(STDOUT, "\r\033[K");
            sb_err('status check failed (HTTP ' . $r2['code'] . ')');
            if ($jsonOnly) sb_note($r2['raw']);
            exit(4);
        }
        $st = $s['status'] ?? '';
        if ($st === 'done') {
            if (!$jsonOnly && sb_use_color()) fwrite(STDOUT, "\r\033[K");
            if ($jsonOnly) { echo json_encode($s, JSON_UNESCAPED_SLASHES) . "\n"; return; }
            $img      = $s['image']    ?? '';
            $download = $s['download'] ?? '';
            $willSave = $outputArg !== null && ($download || $img);
            $elapsed  = time() - $start;
            sb_ok('captured in ' . $elapsed . 's');
            if (!empty($s['meta_page_title'])) sb_note(sb_dim('  title:  ') . $s['meta_page_title']);
            if (!empty($s['meta_http_status'])) sb_note(sb_dim('  status: ') . $s['meta_http_status']);
            // Skip the (expiring) private URL when we're saving a local file | the
            // saved path below is what the user wants.
            if ($download && !$willSave)  sb_note(sb_dim('  private:') . ' ' . sb_clr($download, '36') . sb_dim(' (expires)'));
            elseif ($img)                sb_note(sb_dim('  image:  ') . sb_clr($img, '36'));
            if (!empty($s['preview']))   sb_note(sb_dim('  preview:') . ' ' . sb_clr((string)$s['preview'], '36'));
            if ($willSave) {
                $finalPath = sb_resolve_output_path($outputArg, $url, $token, (string)($body['format'] ?? 'jpg'));
                $bytes = sb_download($download ?: $img, $finalPath);
                sb_ok('saved ' . $finalPath . sb_dim(' (' . sb_human_bytes($bytes) . ')'));
            }
            return;
        }
        if ($st === 'failed') {
            if (!$jsonOnly && sb_use_color()) fwrite(STDOUT, "\r\033[K");
            $code = $s['error_code'] ?? 'unknown';
            if ($jsonOnly) { echo json_encode($s, JSON_UNESCAPED_SLASHES) . "\n"; exit(6); }
            sb_err('capture failed: ' . $code);
            if (!empty($s['image'])) sb_note(sb_dim('  partial:') . ' ' . sb_clr((string)$s['image'], '36'));
            exit(6);
        }
        if (time() - $start > $timeout) {
            if (!$jsonOnly && sb_use_color()) fwrite(STDOUT, "\r\033[K");
            sb_err('timed out after ' . $timeout . 's (job ' . $token . ' still ' . $st . ')');
            sb_note(sb_dim('hint: ') . 'check later with ' . sb_b('curl ' . sb_api_base() . '/capture/' . $token));
            exit(7);
        }
        if (!$jsonOnly && sb_use_color()) {
            $f = $frames[$tick++ % count($frames)];
            fwrite(STDOUT, "\r" . sb_clr($f, '36') . ' ' . $st . sb_dim(' · ' . (time() - $start) . 's elapsed'));
        }
        sleep(SHOTBOT_POLL_INTERVAL_S);
    }
}

function sb_resolve_output_path(mixed $opt, string $url, string $token, string $format): string {
    $host = parse_url($url, PHP_URL_HOST) ?: 'shotbot';
    $host = preg_replace('/^www\./i', '', $host);
    $host = preg_replace('/[^a-z0-9.\-]/i', '_', (string)$host);
    $auto = $host . '-' . substr($token, 0, 8) . '.' . $format;

    if ($opt === true || $opt === '' || $opt === null) {
        return './' . $auto;
    }
    $s = (string)$opt;
    if (str_ends_with($s, '/') || str_ends_with($s, '\\')) {
        $dir = rtrim($s, '/\\');
        if ($dir === '') $dir = '.';
        return $dir . '/' . $auto;
    }
    if (is_dir($s)) {
        return rtrim($s, '/\\') . '/' . $auto;
    }
    return $s;
}

function sb_human_bytes(int $b): string {
    if ($b < 1024) return $b . 'B';
    if ($b < 1024 * 1024) return round($b / 1024, 1) . 'KB';
    return round($b / 1024 / 1024, 2) . 'MB';
}

// ── Dispatch ─────────────────────────────────────────────────────────────────
$args = sb_parse_args($argv);
$cmd  = $args['cmd'];
$opts = $args['opts'];

if ($cmd === '' && (!empty($opts['version']) || !empty($opts['v']))) $cmd = 'version';
if ($cmd === '' && (!empty($opts['help']) || !empty($opts['h'])))    $cmd = 'help';
if ($cmd === '') $cmd = 'help';

switch ($cmd) {
    case 'capture':           sb_cmd_capture($opts); break;
    case 'status':            sb_cmd_status($opts); break;
    case 'config':            sb_cmd_config(); break;
    case 'set':               sb_cmd_set($args['pos']); break;
    case 'unset':             sb_cmd_unset($args['pos']); break;
    case 'defaults':          sb_cmd_defaults($opts); break;
    case 'reset':
    case 'reset-key':         sb_cmd_reset(); break;
    case 'version':
    case '-v':
    case '--version':         sb_cmd_version(); break;
    case 'help':
    case '-h':
    case '--help':            sb_cmd_help(); break;
    default:
        sb_err('unknown command: ' . $cmd);
        sb_note(sb_dim('try: ') . sb_b('shotbot help'));
        exit(2);
}