workgrid.py

#!/usr/bin/env python3
"""workgrid — local browser-based media library viewer/organizer.

Server: multi-source scanner + config, HTTP (127.0.0.1 only) with Range
streaming, thumbnail pipeline, metadata, file ops. UI lives in static/.

Usage: python workgrid.py [folder ...] [--port N] [--no-browser]
"""

import argparse
import hashlib
import json
import os
import re
import shutil
import subprocess
import sys
import threading
import time
import webbrowser
from collections import deque
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import unquote, urlparse, parse_qs

# ---- optional dependencies (degrade gracefully) ---------------------------

try:
    from PIL import Image, ImageOps
    from PIL.ExifTags import TAGS as EXIF_TAGS, GPSTAGS
    # local trusted files; portfolio renders can exceed the default
    # decompression-bomb threshold (~179 MP)
    Image.MAX_IMAGE_PIXELS = None
    HAVE_PIL = True
except ImportError:
    HAVE_PIL = False
    print("[workgrid] Pillow not installed — no image thumbnails/EXIF",
          file=sys.stderr)

try:
    import pillow_heif
    pillow_heif.register_heif_opener()
    HAVE_HEIF = True
except ImportError:
    HAVE_HEIF = False

try:
    import imageio_ffmpeg
    FFMPEG = imageio_ffmpeg.get_ffmpeg_exe()
except ImportError:
    FFMPEG = shutil.which("ffmpeg")
if not FFMPEG:
    print("[workgrid] no ffmpeg — no video thumbnails/metadata",
          file=sys.stderr)

try:
    from send2trash import send2trash
    HAVE_TRASH = True
except ImportError:
    HAVE_TRASH = False

# ---------------------------------------------------------------- constants

IMAGE_EXTS = {"jpg", "jpeg", "png", "gif", "webp", "bmp", "tif", "tiff",
              "svg", "avif", "heic", "heif", "jfif", "ico"}
VIDEO_EXTS = {"mp4", "webm", "mov", "m4v", "mkv", "avi", "ogv", "mpg",
              "mpeg", "wmv", "3gp"}
SKIP_DIRS = {"$recycle.bin", "node_modules", "system volume information",
             ".workgrid-thumbs"}

MIME_TYPES = {
    "jpg": "image/jpeg", "jpeg": "image/jpeg", "jfif": "image/jpeg",
    "png": "image/png", "gif": "image/gif", "webp": "image/webp",
    "bmp": "image/bmp", "tif": "image/tiff", "tiff": "image/tiff",
    "svg": "image/svg+xml", "avif": "image/avif", "heic": "image/heic",
    "heif": "image/heif", "ico": "image/x-icon",
    "mp4": "video/mp4", "m4v": "video/mp4", "webm": "video/webm",
    "mov": "video/quicktime", "mkv": "video/x-matroska",
    "avi": "video/x-msvideo", "ogv": "video/ogg", "mpg": "video/mpeg",
    "mpeg": "video/mpeg", "wmv": "video/x-ms-wmv", "3gp": "video/3gpp",
    "html": "text/html; charset=utf-8", "css": "text/css; charset=utf-8",
    "js": "text/javascript; charset=utf-8", "json": "application/json",
    "woff2": "font/woff2",
}

CHUNK = 64 * 1024
THUMB_SIZE = 320
STATIC_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)),
                          "static")


def app_data_dir():
    if sys.platform == "win32":
        base = os.environ.get("LOCALAPPDATA", os.path.expanduser("~"))
    else:
        base = os.environ.get("XDG_DATA_HOME",
                              os.path.expanduser("~/.local/share"))
    d = os.path.join(base, "workgrid")
    os.makedirs(d, exist_ok=True)
    return d


APP_DATA = app_data_dir()
CONFIG_PATH = os.path.join(APP_DATA, "config.json")
THUMB_DIR = os.path.join(APP_DATA, "thumbs")
os.makedirs(THUMB_DIR, exist_ok=True)


# ------------------------------------------------------------------- config

_config_lock = threading.Lock()


def load_config():
    try:
        with open(CONFIG_PATH, "r", encoding="utf-8") as f:
            return json.load(f)
    except (OSError, ValueError):
        return {}


def save_config_patch(**patch):
    with _config_lock:
        cfg = load_config()
        cfg.update(patch)
        try:
            with open(CONFIG_PATH, "w", encoding="utf-8") as f:
                json.dump(cfg, f, indent=2)
        except OSError as e:
            print(f"[workgrid] could not save config: {e}", file=sys.stderr)


# ------------------------------------------------------------ json stores

class JsonStore:
    """Small thread-safe JSON file store (media meta, annotations, ...)."""

    def __init__(self, filename):
        self.path = os.path.join(APP_DATA, filename)
        self.lock = threading.Lock()
        try:
            with open(self.path, "r", encoding="utf-8") as f:
                self.data = json.load(f)
        except (OSError, ValueError):
            self.data = {}
        self._dirty = False

    def get(self, key, default=None):
        with self.lock:
            return self.data.get(key, default)

    def set(self, key, value):
        with self.lock:
            self.data[key] = value
            self._dirty = True

    def update(self, key, patch):
        with self.lock:
            cur = self.data.get(key) or {}
            cur.update(patch)
            self.data[key] = cur
            self._dirty = True

    def delete(self, key):
        with self.lock:
            if key in self.data:
                del self.data[key]
                self._dirty = True

    def rename_key(self, old, new):
        with self.lock:
            if old in self.data:
                self.data[new] = self.data.pop(old)
                self._dirty = True

    def save(self, force=False):
        with self.lock:
            if not self._dirty and not force:
                return
            try:
                tmp = self.path + ".tmp"
                with open(tmp, "w", encoding="utf-8") as f:
                    json.dump(self.data, f)
                os.replace(tmp, self.path)
                self._dirty = False
            except OSError as e:
                print(f"[workgrid] save {self.path}: {e}", file=sys.stderr)


MEDIA_META = JsonStore("media-meta.json")   # thumb key -> {duration,w,h,...}
ANNOTATIONS = JsonStore("annotations.json")  # "sid/rel" -> {rating,label,tags}


# ------------------------------------------------------------------ library

class Library:
    """Registered sources + scanned items. Scans run per-source in threads."""

    def __init__(self):
        self.lock = threading.Lock()
        self.sources = []            # [{id, path, name}]
        self.items = {}              # source id -> [item, ...]
        self.scanning = {}           # source id -> bool
        self.version = 0             # bumped on any library change

    @staticmethod
    def source_id(path):
        real = os.path.realpath(path)
        return hashlib.md5(real.lower().encode("utf-8")).hexdigest()[:8]

    def bump(self):
        with self.lock:
            self.version += 1

    def add_source(self, path):
        real = os.path.realpath(path)
        if not os.path.isdir(real):
            return None
        sid = self.source_id(real)
        with self.lock:
            if any(s["id"] == sid for s in self.sources):
                return sid
            self.sources.append({"id": sid, "path": real,
                                 "name": os.path.basename(real) or real})
            self.version += 1
        self.scan_async(sid)
        return sid

    def remove_source(self, sid):
        with self.lock:
            self.sources = [s for s in self.sources if s["id"] != sid]
            self.items.pop(sid, None)
            self.scanning.pop(sid, None)
            self.version += 1
        with _thumb_dir_lock:
            _thumb_dir_cache.pop(sid, None)

    def get_source(self, sid):
        with self.lock:
            for s in self.sources:
                if s["id"] == sid:
                    return dict(s)
        return None

    def scan_async(self, sid=None):
        with self.lock:
            targets = [dict(s) for s in self.sources
                       if sid is None or s["id"] == sid]
        for src in targets:
            threading.Thread(target=self._scan_source, args=(src,),
                             daemon=True).start()

    def _scan_source(self, src):
        sid = src["id"]
        with self.lock:
            self.scanning[sid] = True
        found = []
        root = src["path"]
        try:
            for dirpath, dirnames, filenames in os.walk(root):
                dirnames[:] = [d for d in dirnames
                               if not d.startswith(".")
                               and d.lower() not in SKIP_DIRS]
                for fn in filenames:
                    if fn.startswith("."):
                        continue
                    ext = os.path.splitext(fn)[1].lstrip(".").lower()
                    if ext in IMAGE_EXTS:
                        kind = "image"
                    elif ext in VIDEO_EXTS:
                        kind = "video"
                    else:
                        continue
                    full = os.path.join(dirpath, fn)
                    try:
                        st = os.stat(full)
                    except OSError:
                        continue
                    rel = os.path.relpath(full, root).replace(os.sep, "/")
                    found.append({
                        "source": sid,
                        "name": fn,
                        "rel": rel,
                        "folder": os.path.dirname(rel),
                        "type": kind,
                        "format": ext,
                        "size": st.st_size,
                        "modified": int(st.st_mtime),
                    })
        except OSError as e:
            print(f"[workgrid] scan error for {root}: {e}", file=sys.stderr)
        with self.lock:
            if any(s["id"] == sid for s in self.sources):
                self.items[sid] = found
            self.scanning[sid] = False
            self.version += 1
        THUMBS.enqueue_items(found)

    def all_items(self):
        with self.lock:
            return [it for sid in self.items for it in self.items[sid]]

    def find_item(self, sid, rel):
        with self.lock:
            for it in self.items.get(sid, []):
                if it["rel"] == rel:
                    return dict(it)
        return None

    def snapshot(self):
        with self.lock:
            items = [dict(it) for sid in self.items
                     for it in self.items[sid]]
            sources = [dict(s) for s in self.sources]
            scanning = any(self.scanning.values())
            version = self.version
        # enrich with cached thumb/meta info + sidecar annotations
        for it in items:
            key = thumb_key(it)
            it["thumb"] = find_thumb(it, key) is not None
            meta = MEDIA_META.get(key)
            if meta:
                for k in ("duration", "width", "height"):
                    if meta.get(k) is not None:
                        it[k] = meta[k]
            ann = ANNOTATIONS.get(f'{it["source"]}/{it["rel"]}')
            if ann:
                if ann.get("rating"):
                    it["rating"] = ann["rating"]
                if ann.get("label"):
                    it["label"] = ann["label"]
                if ann.get("tags"):
                    it["tags"] = ann["tags"]
                if ann.get("autotags"):
                    it["autotags"] = ann["autotags"]
        return {
            "sources": sources,
            "items": items,
            "scanning": scanning,
            "version": version,
            "thumbs": THUMBS.progress(),
            "capabilities": {
                "pil": HAVE_PIL, "heif": HAVE_HEIF,
                "ffmpeg": bool(FFMPEG), "trash": HAVE_TRASH,
                "autotag": AUTOTAG.available(),
            },
        }


def persist_sources():
    save_config_patch(sources=[{"path": s["path"]} for s in LIB.sources])


# --------------------------------------------------------------- thumbnails

def thumb_key(item):
    raw = f'{item["source"]}/{item["rel"]}|{item["modified"]}|{item["size"]}'
    return hashlib.md5(raw.encode("utf-8")).hexdigest()


_thumb_dir_cache = {}   # source id -> writable per-source dir, or None
_thumb_dir_lock = threading.Lock()


def source_thumb_dir(sid):
    """Per-source `.workgrid-thumbs` cache dir if the source is writable,
    else None (thumbs then fall back to app-data). Cached per source."""
    with _thumb_dir_lock:
        if sid in _thumb_dir_cache:
            return _thumb_dir_cache[sid]
    src = LIB.get_source(sid)
    if src is None:
        return None  # not cached: source may be registered later
    d = os.path.join(src["path"], ".workgrid-thumbs")
    result = None
    try:
        os.makedirs(d, exist_ok=True)
        probe = os.path.join(d, ".write-probe")
        with open(probe, "w"):
            pass
        os.remove(probe)
        if sys.platform == "win32":
            import ctypes
            ctypes.windll.kernel32.SetFileAttributesW(d, 2)  # +hidden
        result = d
    except OSError:
        result = None  # read-only source -> app-data fallback
    with _thumb_dir_lock:
        _thumb_dir_cache[sid] = result
    return result


def thumb_write_path(item, key):
    """Where a new thumbnail should be written for this item."""
    d = source_thumb_dir(item["source"]) or THUMB_DIR
    return os.path.join(d, key + ".jpg")


def find_thumb(item, key=None):
    """Existing thumbnail path or None. Checks the per-source dir first,
    then the app-data dir (fallback + pre-hybrid legacy cache)."""
    if key is None:
        key = thumb_key(item)
    d = source_thumb_dir(item["source"])
    if d:
        p = os.path.join(d, key + ".jpg")
        if os.path.exists(p):
            return p
    p = os.path.join(THUMB_DIR, key + ".jpg")
    return p if os.path.exists(p) else None


def parse_ffmpeg_info(path):
    """Extract duration/resolution/codec/fps/bitrate by parsing
    `ffmpeg -i` stderr (no bundled ffprobe)."""
    if not FFMPEG:
        return {}
    try:
        p = subprocess.run(
            [FFMPEG, "-hide_banner", "-i", path],
            capture_output=True, text=True, errors="replace", timeout=30,
            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
        err = p.stderr
    except (OSError, subprocess.TimeoutExpired):
        return {}
    info = {}
    m = re.search(r"Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)", err)
    if m:
        info["duration"] = round(int(m.group(1)) * 3600 +
                                 int(m.group(2)) * 60 +
                                 float(m.group(3)), 2)
    m = re.search(r"Duration:.*?bitrate:\s*(\d+)\s*kb/s", err)
    if m:
        info["bitrate"] = int(m.group(1))
    m = re.search(r"Stream.*?Video:\s*(\w+)[^\n]*?(\d{2,5})x(\d{2,5})", err)
    if m:
        info["codec"] = m.group(1)
        info["width"] = int(m.group(2))
        info["height"] = int(m.group(3))
    m = re.search(r"(\d+(?:\.\d+)?)\s*fps", err)
    if m:
        info["fps"] = float(m.group(1))
    return info


class ThumbManager:
    """Background thumbnail generation with progress reporting."""

    WORKERS = 3

    def __init__(self):
        self.lock = threading.Lock()
        self.queue = deque()
        self.queued = set()          # keys in queue or in flight
        self.failed = set()          # keys that failed (don't retry)
        self.done_count = 0
        self.total_count = 0
        self._started = False

    def _ensure_workers(self):
        if self._started:
            return
        self._started = True
        for _ in range(self.WORKERS):
            threading.Thread(target=self._worker, daemon=True).start()

    def enqueue_items(self, items, force=False):
        added = 0
        with self.lock:
            for it in items:
                key = thumb_key(it)
                if key in self.queued:
                    continue
                if not force and (key in self.failed
                                  or find_thumb(it, key) is not None):
                    continue
                if force:
                    self.failed.discard(key)
                self.queue.append((key, dict(it)))
                self.queued.add(key)
                added += 1
            self.total_count += added
        if added:
            self._ensure_workers()
        return added

    def progress(self):
        with self.lock:
            return {"done": self.done_count, "total": self.total_count,
                    "pending": len(self.queued)}

    def _worker(self):
        while True:
            with self.lock:
                job = self.queue.popleft() if self.queue else None
            if job is None:
                MEDIA_META.save()
                time.sleep(0.4)
                continue
            key, item = job
            try:
                ok = self._generate(key, item)
                if not ok:
                    with self.lock:
                        self.failed.add(key)
            except Exception as e:
                print(f'[workgrid] thumb failed {item["rel"]}: {e}',
                      file=sys.stderr)
                with self.lock:
                    self.failed.add(key)
            with self.lock:
                self.queued.discard(key)
                self.done_count += 1
            LIB.bump()

    def _generate(self, key, item):
        src = LIB.get_source(item["source"])
        if src is None:
            return False
        full = os.path.join(src["path"], item["rel"].replace("/", os.sep))
        if not os.path.isfile(full):
            return False
        out = thumb_write_path(item, key)
        if item["type"] == "image":
            return self._image_thumb(full, out, key, item)
        return self._video_thumb(full, out, key)

    def _image_thumb(self, full, out, key, item):
        if not HAVE_PIL or item["format"] == "svg":
            return False  # svg: browser renders the original
        with Image.open(full) as im:
            MEDIA_META.update(key, {"width": im.width, "height": im.height})
            im = ImageOps.exif_transpose(im)
            im.thumbnail((THUMB_SIZE, THUMB_SIZE), Image.LANCZOS)
            if im.mode in ("RGBA", "LA", "P"):
                im = im.convert("RGBA")
                bg = Image.new("RGB", im.size, (26, 28, 31))
                bg.paste(im, mask=im.split()[-1])
                im = bg
            elif im.mode != "RGB":
                im = im.convert("RGB")
            im.save(out, "JPEG", quality=80)
        return True

    def _video_thumb(self, full, out, key):
        if not FFMPEG:
            return False
        info = parse_ffmpeg_info(full)
        if info:
            MEDIA_META.update(key, info)
        seek = "1" if info.get("duration", 0) >= 1.5 else "0"
        cmd = [FFMPEG, "-hide_banner", "-loglevel", "error",
               "-ss", seek, "-i", full, "-frames:v", "1",
               "-vf", f"scale={THUMB_SIZE}:-2", "-q:v", "4", "-y", out]
        try:
            p = subprocess.run(
                cmd, capture_output=True, timeout=60,
                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
        except (OSError, subprocess.TimeoutExpired):
            return False
        return p.returncode == 0 and os.path.exists(out) \
            and os.path.getsize(out) > 0

    def rebuild_all(self):
        items = LIB.all_items()
        with self.lock:
            self.failed.clear()
        for it in items:
            p = find_thumb(it)
            if p:
                try:
                    os.remove(p)
                except OSError:
                    pass
        return self.enqueue_items(items, force=True)


# ------------------------------------------------------------ deep metadata

def _exif_str(v):
    if isinstance(v, bytes):
        return v.decode("utf-8", "replace").strip("\x00 ")
    return str(v)


def image_metadata(full):
    rows = {}
    if not HAVE_PIL:
        return rows
    try:
        with Image.open(full) as im:
            rows["dimensions"] = f"{im.width} × {im.height}"
            try:
                exif = im.getexif()
            except Exception:
                return rows
            if not exif:
                return rows
            named = {EXIF_TAGS.get(t, t): v for t, v in exif.items()}
            # camera fields live in the Exif IFD
            try:
                ifd = exif.get_ifd(0x8769)
                named.update({EXIF_TAGS.get(t, t): v for t, v in ifd.items()})
            except Exception:
                pass
            make = _exif_str(named.get("Make", "")).strip()
            model = _exif_str(named.get("Model", "")).strip()
            if make or model:
                cam = model if model.lower().startswith(make.lower()) \
                    else (make + " " + model).strip()
                rows["camera"] = cam
            if named.get("LensModel"):
                rows["lens"] = _exif_str(named["LensModel"])
            iso = named.get("ISOSpeedRatings") or \
                named.get("PhotographicSensitivity")
            if iso:
                rows["iso"] = f"ISO {iso}"
            if named.get("FNumber"):
                try:
                    rows["aperture"] = f"f/{float(named['FNumber']):g}"
                except (TypeError, ValueError):
                    pass
            if named.get("ExposureTime"):
                try:
                    t = float(named["ExposureTime"])
                    rows["shutter"] = f"1/{round(1 / t)} s" if 0 < t < 1 \
                        else f"{t:g} s"
                except (TypeError, ValueError, ZeroDivisionError):
                    pass
            if named.get("FocalLength"):
                try:
                    rows["focal length"] = \
                        f"{float(named['FocalLength']):g} mm"
                except (TypeError, ValueError):
                    pass
            if named.get("DateTimeOriginal"):
                rows["captured"] = _exif_str(named["DateTimeOriginal"])
            try:
                gps_ifd = exif.get_ifd(0x8825)
                if gps_ifd:
                    gps = {GPSTAGS.get(t, t): v for t, v in gps_ifd.items()}
                    lat, lon = gps.get("GPSLatitude"), gps.get("GPSLongitude")
                    if lat and lon:
                        def dms(v, ref, neg):
                            d = float(v[0]) + float(v[1]) / 60 \
                                + float(v[2]) / 3600
                            return -d if ref in neg else d
                        rows["gps"] = (
                            f'{dms(lat, gps.get("GPSLatitudeRef"), "S"):.5f}, '
                            f'{dms(lon, gps.get("GPSLongitudeRef"), "W"):.5f}')
            except Exception:
                pass
    except Exception as e:
        rows["note"] = f"could not read: {e}"
    return rows


def video_metadata(full, key):
    info = MEDIA_META.get(key) or parse_ffmpeg_info(full)
    rows = {}
    if info.get("duration") is not None:
        d = info["duration"]
        rows["duration"] = f"{int(d // 60)}:{d % 60:04.1f}"
    if info.get("width"):
        rows["resolution"] = f'{info["width"]} × {info["height"]}'
    if info.get("codec"):
        rows["codec"] = info["codec"]
    if info.get("fps"):
        rows["fps"] = f'{info["fps"]:g} fps'
    if info.get("bitrate"):
        rows["bitrate"] = f'{info["bitrate"]} kb/s'
    return rows


# ------------------------------------------------------------------ file ops

ILLEGAL_NAME = re.compile(r'[<>:"/\\|?*\x00-\x1f]')


def valid_name(name):
    name = name.strip()
    if not name or name in (".", "..") or ILLEGAL_NAME.search(name):
        return None
    if name.rstrip(". ") != name:  # windows: no trailing dots/spaces
        return None
    return name


def auto_rename(dest_dir, name):
    """foo.jpg -> foo (2).jpg, foo (3).jpg, ... until free."""
    stem, ext = os.path.splitext(name)
    n = 2
    while True:
        cand = f"{stem} ({n}){ext}"
        if not os.path.exists(os.path.join(dest_dir, cand)):
            return cand
        n += 1


def migrate_item_data(old_sid, old_rel, new_sid, new_rel, new_full):
    """Sidecar annotations + thumbnail cache follow a moved/renamed file."""
    ANNOTATIONS.rename_key(f"{old_sid}/{old_rel}", f"{new_sid}/{new_rel}")
    ANNOTATIONS.save()
    try:
        st = os.stat(new_full)
    except OSError:
        return
    # old cache entries are keyed by the pre-move stat; mtime survives
    # shutil.move, so rebuild both keys from the same mtime/size
    fake_old = {"source": old_sid, "rel": old_rel,
                "modified": int(st.st_mtime), "size": st.st_size}
    fake_new = {"source": new_sid, "rel": new_rel,
                "modified": int(st.st_mtime), "size": st.st_size}
    old_key, new_key = thumb_key(fake_old), thumb_key(fake_new)
    if old_key == new_key:
        return
    old_thumb = find_thumb(fake_old, old_key)
    if old_thumb:
        try:
            # cross-source move may cross drives: shutil.move, not replace
            shutil.move(old_thumb, thumb_write_path(fake_new, new_key))
        except OSError:
            pass
    meta = MEDIA_META.get(old_key)
    if meta is not None:
        MEDIA_META.set(new_key, meta)
        MEDIA_META.delete(old_key)
        MEDIA_META.save()


def drive_supports_recycle(path):
    """Network drives have no Recycle Bin — SHFileOperation would delete
    permanently. Those files go to an app-data trash folder instead."""
    if sys.platform != "win32":
        return True
    import ctypes
    drive = os.path.splitdrive(os.path.realpath(path))[0]
    if not drive:
        return False
    DRIVE_REMOTE = 4
    return ctypes.windll.kernel32.GetDriveTypeW(drive + "\\") != DRIVE_REMOTE


def app_trash(full):
    """Fallback trash: move into app-data/trash/<date>/, never overwrite."""
    day_dir = os.path.join(APP_DATA, "trash", time.strftime("%Y-%m-%d"))
    os.makedirs(day_dir, exist_ok=True)
    name = os.path.basename(full)
    if os.path.exists(os.path.join(day_dir, name)):
        name = auto_rename(day_dir, name)
    shutil.move(full, os.path.join(day_dir, name))


def drop_item_data(sid, rel, item=None):
    ANNOTATIONS.delete(f"{sid}/{rel}")
    ANNOTATIONS.save()
    if item:
        key = thumb_key(item)
        p = find_thumb(item, key)
        if p:
            try:
                os.remove(p)
            except OSError:
                pass
        MEDIA_META.delete(key)


# ------------------------------------------------------- organization utils

LABELS = {"red", "yellow", "green", "blue", "purple"}


def find_duplicates():
    """Byte-identical files: size prefilter, then md5 hash."""
    by_size = {}
    for it in LIB.all_items():
        by_size.setdefault(it["size"], []).append(it)
    groups = []
    for size, items in by_size.items():
        if len(items) < 2 or size == 0:
            continue
        by_hash = {}
        for it in items:
            full = resolve_in_source(it["source"], it["rel"])
            if full is None:
                continue
            h = hashlib.md5()
            try:
                with open(full, "rb") as f:
                    for chunk in iter(lambda: f.read(1024 * 1024), b""):
                        h.update(chunk)
            except OSError:
                continue
            by_hash.setdefault(h.hexdigest(), []).append(it)
        for digest, dupes in by_hash.items():
            if len(dupes) > 1:
                groups.append({"hash": digest, "size": size,
                               "items": [{"source": d["source"],
                                          "rel": d["rel"],
                                          "name": d["name"]}
                                         for d in dupes]})
    groups.sort(key=lambda g: -g["size"])
    return groups


def library_stats():
    items = LIB.all_items()
    by_format, by_month = {}, {}
    total_size = 0
    for it in items:
        f = by_format.setdefault(it["format"],
                                 {"count": 0, "size": 0, "type": it["type"]})
        f["count"] += 1
        f["size"] += it["size"]
        total_size += it["size"]
        month = time.strftime("%Y-%m", time.localtime(it["modified"]))
        by_month[month] = by_month.get(month, 0) + 1
    return {
        "total": len(items),
        "totalSize": total_size,
        "images": sum(1 for it in items if it["type"] == "image"),
        "videos": sum(1 for it in items if it["type"] == "video"),
        "byFormat": by_format,
        "byMonth": dict(sorted(by_month.items())),
    }


# ------------------------------------------------------------- auto-tagging

DEFAULT_VOCAB = [
    "portrait", "landscape", "studio shot", "product shot", "automotive",
    "car", "architecture", "interior", "food", "drink", "bottle", "people",
    "animal", "nature", "forest", "beach", "mountains", "city", "night",
    "aerial view", "close-up", "macro", "black and white", "colorful",
    "minimal", "3d render", "cgi", "illustration", "text or logo",
    "advertising", "packaging", "helicopter", "airplane", "water", "snow",
    "sunset", "abstract",
]


class AutoTagger:
    """Optional local CLIP zero-shot tagging. Pluggable backend:
    open_clip (torch CPU) if installed, else hidden. Results cached by
    file-hash + vocabulary version; runs as a pausable background job."""

    def __init__(self):
        self.lock = threading.Lock()
        self.cache = JsonStore("autotag-cache.json")
        cfg = load_config()
        self.vocab = cfg.get("autotagVocab") or list(DEFAULT_VOCAB)
        self.vocab_version = cfg.get("autotagVocabVersion", 1)
        self.running = False
        self.pause_flag = False
        self.done = 0
        self.total = 0
        self.error = None
        self._model = None       # (model, preprocess, text_features)
        self._backend = None

    def available(self):
        if self._backend is not None:
            return True
        try:
            import open_clip  # noqa: F401
            import torch      # noqa: F401
            self._backend = "open_clip"
            return True
        except ImportError:
            return False

    def status(self):
        with self.lock:
            return {
                "available": self.available(),
                "backend": self._backend,
                "running": self.running,
                "done": self.done,
                "total": self.total,
                "error": self.error,
                "vocab": self.vocab,
            }

    def set_vocab(self, terms):
        with self.lock:
            if terms == self.vocab:
                return
            self.vocab = terms
            self.vocab_version += 1
            self._model = None  # re-embed text next run
        save_config_patch(autotagVocab=terms,
                          autotagVocabVersion=self.vocab_version)

    def pause(self):
        self.pause_flag = True

    def start(self):
        if not self.available():
            return {"error": "no local model backend installed"}
        with self.lock:
            if self.running:
                return {"ok": True, "already": True}
            self.running = True
            self.pause_flag = False
            self.error = None
        threading.Thread(target=self._run, daemon=True).start()
        return {"ok": True}

    # -- backend helpers

    def _load_model(self):
        if self._model is not None:
            return self._model
        # symlinked HF cache breaks under Store-Python AppData virtualization
        os.environ.setdefault("HF_HUB_DISABLE_SYMLINKS", "1")
        import torch
        import open_clip
        model, _, preprocess = open_clip.create_model_and_transforms(
            "ViT-B-32-quickgelu", pretrained="openai",
            cache_dir=os.path.join(APP_DATA, "models"))
        model.eval()
        tokenizer = open_clip.get_tokenizer("ViT-B-32-quickgelu")
        prompts = [f"a photo of {t}" for t in self.vocab]
        with torch.no_grad():
            text = tokenizer(prompts)
            tf = model.encode_text(text)
            tf = tf / tf.norm(dim=-1, keepdim=True)
        self._model = (model, preprocess, tf)
        return self._model

    def _tag_image(self, pil_image):
        import torch
        model, preprocess, tf = self._load_model()
        with torch.no_grad():
            img = preprocess(pil_image).unsqueeze(0)
            feat = model.encode_image(img)
            feat = feat / feat.norm(dim=-1, keepdim=True)
            sims = (100.0 * feat @ tf.T).softmax(dim=-1)[0]
        scored = sorted(zip(self.vocab, sims.tolist()),
                        key=lambda p: -p[1])
        return [[t, round(s, 3)] for t, s in scored[:5] if s >= 0.08]

    @staticmethod
    def _file_hash(full):
        h = hashlib.md5()
        try:
            with open(full, "rb") as f:
                for chunk in iter(lambda: f.read(1024 * 1024), b""):
                    h.update(chunk)
        except OSError:
            return None
        return h.hexdigest()

    def _run(self):
        items = [it for it in LIB.all_items()]
        with self.lock:
            self.total = len(items)
            self.done = 0
        try:
            self._load_model()
        except Exception as e:
            with self.lock:
                self.running = False
                self.error = f"model load failed: {e}"
            print(f"[workgrid] autotag: {self.error}", file=sys.stderr)
            return
        for it in items:
            if self.pause_flag:
                break
            try:
                self._tag_item(it)
            except Exception as e:
                print(f'[workgrid] autotag {it["rel"]}: {e}',
                      file=sys.stderr)
            with self.lock:
                self.done += 1
            LIB.bump()
        self.cache.save()
        ANNOTATIONS.save()
        with self.lock:
            self.running = False

    def _tag_item(self, it):
        ann_key = f'{it["source"]}/{it["rel"]}'
        full = resolve_in_source(it["source"], it["rel"])
        if full is None:
            return
        fhash = self._file_hash(full)
        if fhash is None:
            return
        cache_key = f"{fhash}:{self.vocab_version}"
        tags = self.cache.get(cache_key)
        if tags is None:
            if it["type"] == "video":
                # tag the poster frame (thumbnail)
                tpath = find_thumb(it)
                if tpath is None:
                    return
                src_path = tpath
            else:
                if it["format"] == "svg" or not HAVE_PIL:
                    return
                src_path = full
            with Image.open(src_path) as im:
                im = ImageOps.exif_transpose(im).convert("RGB")
                im.thumbnail((512, 512))
                tags = self._tag_image(im)
            self.cache.set(cache_key, tags)
        ann = ANNOTATIONS.get(ann_key) or {}
        manual = set(ann.get("tags", []))
        ANNOTATIONS.update(ann_key, {
            "autotags": [t for t in tags if t[0] not in manual]})


AUTOTAG = AutoTagger()


# ----------------------------------------------------- moodboards / projects

class Projects:
    """Moodboard projects: an inbox for external material only.
    Each project is a folder with a portable board.json arrangement."""

    def __init__(self):
        self.lock = threading.Lock()
        cfg = load_config()
        self.dir = cfg.get("projectsDir")
        self.projects = cfg.get("projects", [])  # [{id, name, folder}]

    def persist(self):
        save_config_patch(projectsDir=self.dir, projects=self.projects)

    def get(self, pid):
        with self.lock:
            for p in self.projects:
                if p["id"] == pid:
                    return dict(p)
        return None

    def create(self, name, folder=None):
        name = valid_name(name)
        if name is None:
            return None, "invalid project name"
        with self.lock:
            if folder is None:
                if not self.dir:
                    return None, "no projects folder set"
                folder = os.path.join(self.dir, name)
            folder = os.path.realpath(folder)
            try:
                os.makedirs(folder, exist_ok=True)
            except OSError as e:
                return None, str(e)
            pid = hashlib.md5(folder.lower().encode()).hexdigest()[:8]
            if any(p["id"] == pid for p in self.projects):
                return pid, None
            self.projects.append({"id": pid, "name": name,
                                  "folder": folder})
        self.persist()
        return pid, None

    def remove(self, pid):
        with self.lock:
            self.projects = [p for p in self.projects if p["id"] != pid]
        self.persist()

    def resolve_file(self, pid, name):
        """Realpath-validated file path inside the project folder."""
        p = self.get(pid)
        if p is None or "/" in name or "\\" in name or ".." in name:
            return None
        root = os.path.realpath(p["folder"])
        full = os.path.realpath(os.path.join(root, name))
        try:
            if os.path.commonpath([root, full]) != root:
                return None
        except ValueError:
            return None
        return full

    def board(self, pid):
        p = self.get(pid)
        if p is None:
            return None
        board_path = os.path.join(p["folder"], "board.json")
        board = {"items": []}
        try:
            with open(board_path, "r", encoding="utf-8") as f:
                board = json.load(f)
        except (OSError, ValueError):
            pass
        # list media files present in the folder
        files = []
        try:
            for fn in os.listdir(p["folder"]):
                ext = os.path.splitext(fn)[1].lstrip(".").lower()
                if ext in IMAGE_EXTS or ext in VIDEO_EXTS:
                    files.append(fn)
        except OSError:
            pass
        return {"project": p, "board": board, "files": sorted(files)}

    def save_board(self, pid, board):
        p = self.get(pid)
        if p is None:
            return False
        try:
            tmp = os.path.join(p["folder"], "board.json.tmp")
            with open(tmp, "w", encoding="utf-8") as f:
                json.dump(board, f, indent=2)
            os.replace(tmp, os.path.join(p["folder"], "board.json"))
            return True
        except OSError:
            return False


PROJECTS = Projects()


def download_url_to(url, dest_dir):
    """Download a dropped URL into a project folder (user-initiated)."""
    import urllib.request
    if not url.lower().startswith(("http://", "https://")):
        return None, "only http(s) URLs"
    name = os.path.basename(urlparse(url).path) or "download"
    name = valid_name(re.sub(r"[?#].*$", "", name)) or "download"
    req = urllib.request.Request(url, headers={"User-Agent": "workgrid/1.0"})
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            ctype = resp.headers.get("Content-Type", "")
            # add an extension when the URL had none
            if "." not in name:
                ext = {"image/jpeg": ".jpg", "image/png": ".png",
                       "image/gif": ".gif", "image/webp": ".webp",
                       "video/mp4": ".mp4"}.get(ctype.split(";")[0].strip())
                if ext:
                    name += ext
            if os.path.exists(os.path.join(dest_dir, name)):
                name = auto_rename(dest_dir, name)
            size = 0
            with open(os.path.join(dest_dir, name), "wb") as f:
                while True:
                    chunk = resp.read(CHUNK)
                    if not chunk:
                        break
                    size += len(chunk)
                    if size > 500 * 1024 * 1024:
                        raise OSError("download exceeds 500 MB cap")
                    f.write(chunk)
        return name, None
    except Exception as e:
        try:
            os.remove(os.path.join(dest_dir, name))
        except OSError:
            pass
        return None, str(e)


# ------------------------------------------------------------- auto-refresh

def watch_sources():
    """Poll per-source directory mtimes; changed signature -> rescan.
    Runs per-source so a slow drive can't stall the others."""
    signatures = {}
    while True:
        time.sleep(5)
        with LIB.lock:
            sources = [dict(s) for s in LIB.sources]
            busy = dict(LIB.scanning)
        for src in sources:
            sid = src["id"]
            if busy.get(sid):
                continue
            sig = 0
            try:
                for dirpath, dirnames, _ in os.walk(src["path"]):
                    dirnames[:] = [d for d in dirnames
                                   if not d.startswith(".")
                                   and d.lower() not in SKIP_DIRS]
                    try:
                        sig ^= hash((dirpath,
                                     int(os.stat(dirpath).st_mtime)))
                    except OSError:
                        continue
            except OSError:
                continue
            if sid in signatures and signatures[sid] != sig:
                LIB.scan_async(sid)
            signatures[sid] = sig


# ---------------------------------------------------------------- fs helper

def resolve_in_source(sid, rel):
    """Realpath-validated absolute path inside a registered source, or None."""
    if ".." in rel.split("/") or rel.startswith("/") or ":" in rel:
        return None
    src = LIB.get_source(sid)
    if src is None:
        return None
    root = os.path.realpath(src["path"])
    full = os.path.realpath(os.path.join(root, rel.replace("/", os.sep)))
    try:
        if os.path.commonpath([root, full]) != root:
            return None
    except ValueError:
        return None
    return full


def pick_folder_dialog():
    """Native folder picker via tkinter in a subprocess (thread-safe)."""
    code = ("import sys, tkinter as tk\n"
            "from tkinter import filedialog\n"
            "sys.stdout.reconfigure(encoding='utf-8')\n"
            "r = tk.Tk(); r.withdraw(); r.attributes('-topmost', True)\n"
            "p = filedialog.askdirectory(title='workgrid — choose folder')\n"
            "print(p or '')\n")
    try:
        out = subprocess.run([sys.executable, "-c", code],
                             capture_output=True, timeout=300)
        if out.returncode != 0:
            print("[workgrid] folder picker failed: " +
                  out.stderr.decode("utf-8", "replace")[:400],
                  file=sys.stderr)
            return None
        path = out.stdout.decode("utf-8", "replace").strip()
        if not path:
            print("[workgrid] folder picker: cancelled / empty result",
                  file=sys.stderr)
        return path or None
    except Exception as e:
        print(f"[workgrid] folder picker error: {e}", file=sys.stderr)
        return None


# ------------------------------------------------------------------ handler

class Handler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"

    def log_message(self, fmt, *args):
        pass

    def log_error(self, fmt, *args):
        print(f"[workgrid] {self.address_string()} {fmt % args}",
              file=sys.stderr)

    # ---- helpers

    def send_json(self, obj, status=200):
        body = json.dumps(obj).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.send_header("Cache-Control", "no-store")
        self.end_headers()
        self.wfile.write(body)

    def send_error_json(self, status, message):
        self.send_json({"error": message}, status)

    def read_body_json(self):
        try:
            n = int(self.headers.get("Content-Length", 0))
            if n <= 0 or n > 10_000_000:
                return {}
            return json.loads(self.rfile.read(n).decode("utf-8"))
        except (ValueError, OSError):
            return {}

    def query(self):
        return {k: v[0] for k, v in
                parse_qs(urlparse(self.path).query).items()}

    # ---- routing

    def do_GET(self):
        path = urlparse(self.path).path
        if path == "/":
            self.serve_static("index.html")
        elif path.startswith("/static/"):
            self.serve_static(unquote(path[len("/static/"):]))
        elif path == "/api/library":
            self.send_json(LIB.snapshot())
        elif path == "/api/version":
            self.send_json({"version": LIB.version,
                            "thumbs": THUMBS.progress()})
        elif path == "/api/meta":
            self.api_meta()
        elif path == "/api/dupes":
            self.send_json({"groups": find_duplicates()})
        elif path == "/api/stats":
            self.send_json(library_stats())
        elif path == "/api/autotag/status":
            self.send_json(AUTOTAG.status())
        elif path == "/api/projects":
            self.send_json({"projectsDir": PROJECTS.dir,
                            "projects": PROJECTS.projects})
        elif path == "/api/board":
            data = PROJECTS.board(self.query().get("project", ""))
            if data is None:
                self.send_error_json(404, "no such project")
            else:
                self.send_json(data)
        elif path.startswith("/project-media/"):
            self.serve_project_media(path)
        elif path.startswith("/media/"):
            self.serve_media(path, thumb=False)
        elif path.startswith("/thumb/"):
            self.serve_media(path, thumb=True)
        else:
            self.send_error_json(404, "not found")

    def do_POST(self):
        path = urlparse(self.path).path
        if path == "/api/project/upload":
            self.api_project_upload()  # raw file body, not JSON
            return
        # consume the JSON body up front — handlers that skip it would
        # otherwise leave bytes on the keep-alive socket and corrupt the
        # next request ("Unsupported method ('{}POST')")
        self._body = self.read_body_json()
        routes = {
            "/api/rescan": self.api_rescan,
            "/api/sources/add": self.api_sources_add,
            "/api/sources/remove": self.api_sources_remove,
            "/api/sources/pick": self.api_sources_pick,
            "/api/thumbs/rebuild": self.api_thumbs_rebuild,
            "/api/ops/newfolder": self.api_newfolder,
            "/api/ops/move": self.api_move,
            "/api/ops/rename": self.api_rename,
            "/api/ops/batchrename": self.api_batchrename,
            "/api/ops/delete": self.api_delete,
            "/api/ops/reveal": self.api_reveal,
            "/api/ann/set": self.api_ann_set,
            "/api/tags": self.api_tags,
            "/api/autotag/start": self.api_autotag_start,
            "/api/autotag/pause": self.api_autotag_pause,
            "/api/autotag/vocab": self.api_autotag_vocab,
            "/api/autotag/dismiss": self.api_autotag_dismiss,
            "/api/autotag/promote": self.api_autotag_promote,
            "/api/projects/create": self.api_project_create,
            "/api/projects/remove": self.api_project_remove,
            "/api/projects/pickdir": self.api_project_pickdir,
            "/api/board": self.api_board_save,
            "/api/project/urldrop": self.api_project_urldrop,
        }
        fn = routes.get(path)
        if fn:
            fn()
        else:
            self.send_error_json(404, "not found")

    # ---- api handlers

    def api_rescan(self):
        LIB.scan_async()
        self.send_json({"ok": True})

    def api_sources_add(self):
        body = self._body
        folder = body.get("path", "")
        if not folder:
            self.send_error_json(400, "missing path")
            return
        sid = LIB.add_source(folder)
        if sid is None:
            print(f"[workgrid] add source rejected, not a folder: "
                  f"{folder!r}", file=sys.stderr)
            self.send_error_json(400, f"not a folder: {folder}")
            return
        persist_sources()
        print(f"[workgrid] source added: {sid}  {folder}")
        self.send_json({"ok": True, "id": sid})

    def api_sources_remove(self):
        body = self._body
        LIB.remove_source(body.get("id", ""))
        persist_sources()
        self.send_json({"ok": True})

    def api_sources_pick(self):
        self.send_json({"path": pick_folder_dialog()})

    def api_thumbs_rebuild(self):
        n = THUMBS.rebuild_all()
        self.send_json({"ok": True, "queued": n})

    def api_meta(self):
        q = self.query()
        sid, rel = q.get("source", ""), q.get("rel", "")
        item = LIB.find_item(sid, rel)
        full = resolve_in_source(sid, rel)
        if item is None or full is None or not os.path.isfile(full):
            self.send_error_json(404, "not found")
            return
        try:
            st = os.stat(full)
            rows = {"created": int(st.st_ctime)}
        except OSError:
            rows = {}
        if item["type"] == "image":
            rows.update(image_metadata(full))
        else:
            rows.update(video_metadata(full, thumb_key(item)))
        self.send_json({"meta": rows})

    # ---- file operation handlers

    def api_newfolder(self):
        body = self._body
        sid = body.get("source", "")
        parent = body.get("parent", "")
        name = valid_name(body.get("name", ""))
        if name is None:
            self.send_error_json(400, "invalid folder name")
            return
        parent_full = resolve_in_source(sid, parent) if parent \
            else (LIB.get_source(sid) or {}).get("path")
        if parent_full is None or not os.path.isdir(parent_full):
            self.send_error_json(403, "forbidden")
            return
        target = os.path.join(parent_full, name)
        if os.path.exists(target):
            self.send_error_json(409, "folder already exists")
            return
        try:
            os.makedirs(target)
        except OSError as e:
            self.send_error_json(500, str(e))
            return
        LIB.scan_async(sid)
        self.send_json({"ok": True})

    def api_move(self):
        """Move items into dest folder. Two-step collision handling:
        without `resolution`, reports collisions and does nothing;
        with resolution 'skip'/'rename', applies it."""
        body = self._body
        items = body.get("items", [])
        dest = body.get("dest", {})
        resolution = body.get("resolution")  # None | "skip" | "rename"
        dsid = dest.get("source", "")
        dfolder = dest.get("folder", "")
        if dfolder:
            dest_dir = resolve_in_source(dsid, dfolder)
        else:
            src = LIB.get_source(dsid)
            dest_dir = src["path"] if src else None
        if dest_dir is None or not os.path.isdir(dest_dir):
            self.send_error_json(403, "bad destination")
            return

        moves, collisions = [], []
        for ref in items:
            sid, rel = ref.get("source", ""), ref.get("rel", "")
            full = resolve_in_source(sid, rel)
            if full is None or not os.path.isfile(full):
                continue
            name = os.path.basename(rel)
            target = os.path.join(dest_dir, name)
            if os.path.realpath(target) == os.path.realpath(full):
                continue  # already there
            if os.path.exists(target):
                collisions.append(name)
                moves.append((sid, rel, full, name, True))
            else:
                moves.append((sid, rel, full, name, False))

        if collisions and resolution is None:
            self.send_json({"collisions": collisions})
            return

        moved, skipped, errors = 0, 0, []
        touched = {dsid}
        for sid, rel, full, name, collided in moves:
            if collided:
                if resolution == "skip":
                    skipped += 1
                    continue
                name = auto_rename(dest_dir, name)
            target = os.path.join(dest_dir, name)
            try:
                shutil.move(full, target)
            except OSError as e:
                errors.append(f"{rel}: {e}")
                continue
            new_rel = (dfolder + "/" if dfolder else "") + name
            migrate_item_data(sid, rel, dsid, new_rel, target)
            touched.add(sid)
            moved += 1
        for sid in touched:
            LIB.scan_async(sid)
        self.send_json({"ok": True, "moved": moved, "skipped": skipped,
                        "errors": errors})

    def api_rename(self):
        body = self._body
        sid = body.get("source", "")
        rel = body.get("rel", "")
        new_name = valid_name(body.get("name", ""))
        if new_name is None:
            self.send_error_json(400, "invalid name")
            return
        full = resolve_in_source(sid, rel)
        if full is None or not os.path.isfile(full):
            self.send_error_json(404, "not found")
            return
        old_ext = os.path.splitext(rel)[1].lower()
        new_ext = os.path.splitext(new_name)[1].lower()
        if old_ext != new_ext and not body.get("confirmExt"):
            self.send_json({"needsExtConfirm": True,
                            "oldExt": old_ext, "newExt": new_ext})
            return
        target = os.path.join(os.path.dirname(full), new_name)
        if os.path.exists(target):
            self.send_error_json(409, "a file with that name exists")
            return
        try:
            os.rename(full, target)
        except OSError as e:
            self.send_error_json(500, str(e))
            return
        folder = os.path.dirname(rel)
        new_rel = (folder + "/" if folder else "") + new_name
        migrate_item_data(sid, rel, sid, new_rel, target)
        LIB.scan_async(sid)
        self.send_json({"ok": True, "rel": new_rel})

    def api_batchrename(self):
        """Pattern rename over a selection. {n}/{n:03} = counter,
        {name} = original stem, {ext} appended automatically."""
        body = self._body
        items = body.get("items", [])
        pattern = body.get("pattern", "")
        start = int(body.get("start", 1))
        dry = bool(body.get("dry"))
        if not pattern:
            self.send_error_json(400, "missing pattern")
            return

        def expand(pat, n, stem):
            def sub(m):
                if m.group(1) == "name":
                    return stem
                pad = m.group(2)
                return str(n).zfill(int(pad)) if pad else str(n)
            return re.sub(r"\{(n|name)(?::0*(\d+))?\}", sub, pat)

        plan, errors = [], []
        n = start
        for ref in items:
            sid, rel = ref.get("source", ""), ref.get("rel", "")
            full = resolve_in_source(sid, rel)
            if full is None or not os.path.isfile(full):
                continue
            stem, ext = os.path.splitext(os.path.basename(rel))
            new_name = valid_name(expand(pattern, n, stem) + ext)
            if new_name is None:
                errors.append(f"{rel}: invalid result name")
                continue
            plan.append({"source": sid, "rel": rel, "name": new_name})
            n += 1
        if dry:
            self.send_json({"plan": plan, "errors": errors})
            return
        renamed = 0
        touched = set()
        for p in plan:
            full = resolve_in_source(p["source"], p["rel"])
            if full is None:
                continue
            target = os.path.join(os.path.dirname(full), p["name"])
            if os.path.exists(target) and \
                    os.path.realpath(target) != os.path.realpath(full):
                p["name"] = auto_rename(os.path.dirname(full), p["name"])
                target = os.path.join(os.path.dirname(full), p["name"])
            try:
                os.rename(full, target)
            except OSError as e:
                errors.append(f'{p["rel"]}: {e}')
                continue
            folder = os.path.dirname(p["rel"])
            new_rel = (folder + "/" if folder else "") + p["name"]
            migrate_item_data(p["source"], p["rel"], p["source"], new_rel,
                              target)
            touched.add(p["source"])
            renamed += 1
        for sid in touched:
            LIB.scan_async(sid)
        self.send_json({"ok": True, "renamed": renamed, "errors": errors})

    def api_delete(self):
        body = self._body
        items = body.get("items", [])
        deleted, apptrashed, errors = 0, 0, []
        touched = set()
        for ref in items:
            sid, rel = ref.get("source", ""), ref.get("rel", "")
            full = resolve_in_source(sid, rel)
            if full is None or not os.path.isfile(full):
                continue
            try:
                if HAVE_TRASH and drive_supports_recycle(full):
                    send2trash(full)
                    deleted += 1
                else:
                    # no Recycle Bin on this drive (or send2trash missing):
                    # keep the file recoverable in app-data trash
                    app_trash(full)
                    apptrashed += 1
            except Exception as e:
                errors.append(f"{rel}: {e}")
                continue
            drop_item_data(sid, rel, LIB.find_item(sid, rel))
            touched.add(sid)
        for sid in touched:
            LIB.scan_async(sid)
        self.send_json({"ok": True, "deleted": deleted,
                        "apptrashed": apptrashed,
                        "trashDir": os.path.join(APP_DATA, "trash"),
                        "errors": errors})

    def api_reveal(self):
        body = self._body
        full = resolve_in_source(body.get("source", ""),
                                 body.get("rel", ""))
        if full is None or not os.path.exists(full):
            self.send_error_json(404, "not found")
            return
        if sys.platform == "win32":
            subprocess.Popen(["explorer", "/select,", full])
        else:
            subprocess.Popen(["xdg-open", os.path.dirname(full)])
        self.send_json({"ok": True})

    # ---- annotations (ratings / labels / tags — JSON sidecar, files
    #      themselves are never modified)

    def api_ann_set(self):
        body = self._body
        items = body.get("items", [])
        for ref in items:
            key = f'{ref.get("source", "")}/{ref.get("rel", "")}'
            if LIB.find_item(ref.get("source", ""),
                             ref.get("rel", "")) is None:
                continue
            patch = {}
            if "rating" in body:
                r = body["rating"]
                patch["rating"] = r if isinstance(r, int) \
                    and 1 <= r <= 5 else None
            if "label" in body:
                lbl = body["label"]
                patch["label"] = lbl if lbl in LABELS else None
            ANNOTATIONS.update(key, patch)
        ANNOTATIONS.save()
        LIB.bump()
        self.send_json({"ok": True})

    def api_tags(self):
        body = self._body
        add = [t.strip().lower() for t in body.get("add", []) if t.strip()]
        remove = [t.strip().lower() for t in body.get("remove", [])]
        for ref in body.get("items", []):
            sid, rel = ref.get("source", ""), ref.get("rel", "")
            if LIB.find_item(sid, rel) is None:
                continue
            key = f"{sid}/{rel}"
            ann = ANNOTATIONS.get(key) or {}
            tags = set(ann.get("tags", []))
            tags.update(add)
            tags.difference_update(remove)
            ANNOTATIONS.update(key, {"tags": sorted(tags)})
        ANNOTATIONS.save()
        LIB.bump()
        self.send_json({"ok": True})

    # ---- auto-tagging (optional local CLIP backend)

    def api_autotag_start(self):
        res = AUTOTAG.start()
        self.send_json(res)

    def api_autotag_pause(self):
        AUTOTAG.pause()
        self.send_json({"ok": True})

    def api_autotag_vocab(self):
        body = self._body
        terms = [t.strip().lower() for t in body.get("terms", [])
                 if t.strip()]
        if not terms:
            self.send_error_json(400, "empty vocabulary")
            return
        AUTOTAG.set_vocab(terms)
        self.send_json({"ok": True})

    def api_autotag_dismiss(self):
        body = self._body
        key = f'{body.get("source", "")}/{body.get("rel", "")}'
        tag = body.get("tag", "")
        ann = ANNOTATIONS.get(key) or {}
        autotags = [t for t in ann.get("autotags", []) if t[0] != tag]
        ANNOTATIONS.update(key, {"autotags": autotags})
        ANNOTATIONS.save()
        LIB.bump()
        self.send_json({"ok": True})

    def api_autotag_promote(self):
        body = self._body
        key = f'{body.get("source", "")}/{body.get("rel", "")}'
        tag = body.get("tag", "")
        ann = ANNOTATIONS.get(key) or {}
        tags = set(ann.get("tags", []))
        tags.add(tag)
        autotags = [t for t in ann.get("autotags", []) if t[0] != tag]
        ANNOTATIONS.update(key, {"tags": sorted(tags),
                                 "autotags": autotags})
        ANNOTATIONS.save()
        LIB.bump()
        self.send_json({"ok": True})

    # ---- moodboard projects

    def api_project_create(self):
        body = self._body
        if not PROJECTS.dir and not body.get("folder"):
            picked = pick_folder_dialog()
            if not picked:
                self.send_error_json(400, "no projects folder chosen")
                return
            PROJECTS.dir = os.path.realpath(picked)
            PROJECTS.persist()
        pid, err = PROJECTS.create(body.get("name", ""),
                                   body.get("folder"))
        if err:
            self.send_error_json(400, err)
            return
        self.send_json({"ok": True, "id": pid})

    def api_project_remove(self):
        body = self._body
        PROJECTS.remove(body.get("id", ""))
        self.send_json({"ok": True})

    def api_project_pickdir(self):
        picked = pick_folder_dialog()
        if picked:
            PROJECTS.dir = os.path.realpath(picked)
            PROJECTS.persist()
        self.send_json({"projectsDir": PROJECTS.dir})

    def api_board_save(self):
        body = self._body
        ok = PROJECTS.save_board(body.get("project", ""),
                                 body.get("board", {"items": []}))
        self.send_json({"ok": ok})

    def api_project_upload(self):
        q = self.query()
        pid, name = q.get("project", ""), unquote(q.get("name", ""))
        name = valid_name(name or "")
        if name is None:
            self.send_error_json(400, "bad filename")
            return
        p = PROJECTS.get(pid)
        if p is None:
            self.send_error_json(404, "no such project")
            return
        if os.path.exists(os.path.join(p["folder"], name)):
            name = auto_rename(p["folder"], name)
        length = int(self.headers.get("Content-Length", 0))
        if length <= 0 or length > 2 * 1024 * 1024 * 1024:
            self.send_error_json(400, "bad upload size")
            return
        dest = os.path.join(p["folder"], name)
        try:
            with open(dest, "wb") as f:
                remaining = length
                while remaining > 0:
                    chunk = self.rfile.read(min(CHUNK, remaining))
                    if not chunk:
                        break
                    f.write(chunk)
                    remaining -= len(chunk)
        except OSError as e:
            self.send_error_json(500, str(e))
            return
        self.send_json({"ok": True, "name": name})

    def api_project_urldrop(self):
        body = self._body
        p = PROJECTS.get(body.get("project", ""))
        if p is None:
            self.send_error_json(404, "no such project")
            return
        name, err = download_url_to(body.get("url", ""), p["folder"])
        if err:
            self.send_error_json(400, err)
            return
        self.send_json({"ok": True, "name": name})

    def serve_project_media(self, path):
        parts = unquote(path[len("/project-media/"):]).split("/", 1)
        if len(parts) != 2:
            self.send_error_json(403, "forbidden")
            return
        full = PROJECTS.resolve_file(parts[0], parts[1])
        if full is None:
            self.send_error_json(403, "forbidden")
            return
        if not os.path.isfile(full):
            self.send_error_json(404, "not found")
            return
        ext = os.path.splitext(full)[1].lstrip(".").lower()
        ctype = MIME_TYPES.get(ext, "application/octet-stream")
        try:
            size = os.path.getsize(full)
            f = open(full, "rb")
        except OSError:
            self.send_error_json(404, "not found")
            return
        with f:
            self.send_response(200)
            self.send_header("Content-Type", ctype)
            self.send_header("Content-Length", str(size))
            self.end_headers()
            self.stream_range(f, 0, size)

    # ---- static files

    def serve_static(self, rel):
        if ".." in rel.split("/"):
            self.send_error_json(403, "forbidden")
            return
        full = os.path.realpath(os.path.join(STATIC_DIR,
                                             rel.replace("/", os.sep)))
        try:
            if os.path.commonpath([os.path.realpath(STATIC_DIR),
                                   full]) != os.path.realpath(STATIC_DIR):
                self.send_error_json(403, "forbidden")
                return
        except ValueError:
            self.send_error_json(403, "forbidden")
            return
        if not os.path.isfile(full):
            self.send_error_json(404, "not found")
            return
        ext = os.path.splitext(full)[1].lstrip(".").lower()
        ctype = MIME_TYPES.get(ext, "application/octet-stream")
        try:
            with open(full, "rb") as f:
                body = f.read()
        except OSError:
            self.send_error_json(404, "not found")
            return
        self.send_response(200)
        self.send_header("Content-Type", ctype)
        self.send_header("Content-Length", str(len(body)))
        cache = "max-age=86400" if ext == "woff2" else "no-store"
        self.send_header("Cache-Control", cache)
        self.end_headers()
        self.wfile.write(body)

    # ---- media / thumb streaming (Range support, realpath-confined)

    def serve_media(self, path, thumb):
        prefix = "/thumb/" if thumb else "/media/"
        parts = unquote(path[len(prefix):]).split("/", 1)
        if len(parts) != 2 or not parts[0] or not parts[1]:
            self.send_error_json(403, "forbidden")
            return
        sid, rel = parts
        if ".." in sid:
            self.send_error_json(403, "forbidden")
            return
        full = resolve_in_source(sid, rel)
        if full is None:
            self.send_error_json(403, "forbidden")
            return
        if not os.path.isfile(full):
            self.send_error_json(404, "not found")
            return

        if thumb:
            item = LIB.find_item(sid, rel)
            if item is None:
                self.send_error_json(404, "not found")
                return
            tpath = find_thumb(item)
            if tpath is None:
                THUMBS.enqueue_items([item])
                self.send_error_json(404, "thumb pending")
                return
            full = tpath
            ctype = "image/jpeg"
        else:
            ext = os.path.splitext(full)[1].lstrip(".").lower()
            ctype = MIME_TYPES.get(ext, "application/octet-stream")

        try:
            size = os.path.getsize(full)
            f = open(full, "rb")
        except OSError:
            self.send_error_json(404, "not found")
            return

        with f:
            rng = self.headers.get("Range")
            if rng:
                m = re.match(r"bytes=(\d*)-(\d*)$", rng.strip())
                if not m or (not m.group(1) and not m.group(2)):
                    self.send_range_error(size)
                    return
                if m.group(1):
                    start = int(m.group(1))
                    end = int(m.group(2)) if m.group(2) else size - 1
                else:
                    start = max(0, size - int(m.group(2)))
                    end = size - 1
                end = min(end, size - 1)
                if start > end or start >= size:
                    self.send_range_error(size)
                    return
                length = end - start + 1
                self.send_response(206)
                self.send_header("Content-Type", ctype)
                self.send_header("Content-Range",
                                 f"bytes {start}-{end}/{size}")
                self.send_header("Content-Length", str(length))
                self.send_header("Accept-Ranges", "bytes")
                self.end_headers()
                self.stream_range(f, start, length)
            else:
                self.send_response(200)
                self.send_header("Content-Type", ctype)
                self.send_header("Content-Length", str(size))
                self.send_header("Accept-Ranges", "bytes")
                self.end_headers()
                self.stream_range(f, 0, size)

    def send_range_error(self, size):
        self.send_response(416)
        self.send_header("Content-Range", f"bytes */{size}")
        self.send_header("Content-Length", "0")
        self.end_headers()

    def stream_range(self, f, start, length):
        try:
            f.seek(start)
            remaining = length
            while remaining > 0:
                chunk = f.read(min(CHUNK, remaining))
                if not chunk:
                    break
                self.wfile.write(chunk)
                remaining -= len(chunk)
        except (ConnectionAbortedError, ConnectionResetError,
                BrokenPipeError):
            pass  # client closed mid-stream (normal for video seeks)


LIB = Library()
THUMBS = ThumbManager()


# --------------------------------------------------------------------- main

def main():
    ap = argparse.ArgumentParser(description="workgrid media library")
    ap.add_argument("folders", nargs="*", help="source folders")
    ap.add_argument("--port", type=int, default=8765)
    ap.add_argument("--no-browser", action="store_true")
    args = ap.parse_args()

    if args.folders:
        for folder in args.folders:
            if LIB.add_source(folder) is None:
                print(f"[workgrid] not a folder, skipped: {folder}",
                      file=sys.stderr)
    else:
        for s in load_config().get("sources", []):
            LIB.add_source(s.get("path", ""))
        if not LIB.sources:
            picked = pick_folder_dialog()
            LIB.add_source(picked if picked else os.getcwd())

    if not LIB.sources:
        print("[workgrid] no valid source folders", file=sys.stderr)
        sys.exit(1)

    threading.Thread(target=watch_sources, daemon=True).start()

    server = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)
    server.daemon_threads = True
    url = f"http://127.0.0.1:{args.port}/"
    print(f"[workgrid] serving {len(LIB.sources)} source(s) at {url}")
    for s in LIB.sources:
        print(f"[workgrid]   {s['id']}  {s['path']}")
    if not args.no_browser:
        threading.Timer(0.4, lambda: webbrowser.open(url)).start()
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        MEDIA_META.save()
        print("\n[workgrid] stopped")


if __name__ == "__main__":
    main()