screengraft 0.13.1

package/scripts/grade.py

@@ -0,0 +1,180 @@
+"""screengraft — M2: the realism pass. Grade, don't regenerate.
+
+An injected screenshot is a perfect, evenly-lit rectangle dropped into a
+photograph that is neither. Even with the geometry exact, it reads as pasted
+because three things do not match: its white balance and exposure belong to
+whatever rendered it, its surface has no grain while the photo has a noise
+floor, and a real screen under real light carries reflections that a clean
+screenshot does not.
+
+Three independent passes, each measurable and each defaulting to a strength a
+designer can dial back:
+
+  1. white balance + exposure -> the light in the room
+  2. grain                    -> the photo's own noise floor
+  3. specular lift            -> the device's REAL reflections, from a
+                                 screen-off reference shot of the same photo
+
+The one rule inherited from the build brief: this pass NEVER touches geometry
+and NEVER generates pixels. Everything here is a per-channel statistic measured
+off the photo itself, so a run is deterministic and reproducible.
+
+Why Reinhard-in-Lab rather than a full histogram match: a histogram match
+against the surrounding bezel would drag the screenshot's own contrast toward
+the bezel's, which is wrong — the screen is a light source, not a surface, and
+it is *supposed* to have its own range. Matching only the mean and spread of
+the two chroma channels, plus a bounded exposure shift, moves the cast without
+flattening the content.
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+# The grade is deliberately weak by default. A screen is emissive: it should
+# pick up the room's cast, not become the room's colour.
+DEFAULT_STRENGTH = 0.35   # the UI default; the slider spans 0.10-1.00
+
+
+def surround_ring(mask: np.ndarray, inner_px: int = 6, outer_px: int = 48) -> np.ndarray:
+    """The band of photo just OUTSIDE the screen — the light the screen sits in.
+
+    Sampling the whole photo would average in a wall three metres away under a
+    different light. The bezel and the few centimetres around it are what a
+    viewer compares the screen against, so that is what the grade matches.
+    `inner_px` steps off the edge first, because those pixels are the
+    antialiased blend of screen and bezel and would poison the statistic with
+    the screenshot's own colour.
+    """
+    solid = (mask > 127).astype(np.uint8)
+    k_in = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (inner_px * 2 + 1,) * 2)
+    k_out = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (outer_px * 2 + 1,) * 2)
+    grown = cv2.dilate(solid, k_out)
+    skirt = cv2.dilate(solid, k_in)
+    return ((grown > 0) & (skirt == 0)).astype(np.uint8)
+
+
+def _stats(lab: np.ndarray, sel: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    px = lab[sel.astype(bool)]
+    if px.size == 0:
+        return np.zeros(3, np.float64), np.ones(3, np.float64)
+    return px.mean(axis=0), px.std(axis=0) + 1e-6
+
+
+def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
+                strength: float = DEFAULT_STRENGTH) -> np.ndarray:
+    """Move the injected screen's cast and exposure toward the surrounding light.
+
+    Chroma (a,b) is matched on mean AND spread — a cast is exactly a chroma mean
+    offset, and a room with weak colour should not receive a saturated screen.
+    Luminance is matched on MEAN ONLY, and bounded: a screen is emissive and is
+    allowed to be brighter than its surroundings, so rescaling its L spread to
+    the bezel's would crush the UI's own contrast. That asymmetry is the whole
+    design of this function.
+    """
+    if strength <= 0:
+        return warped
+    ring = surround_ring(mask)
+    if int(ring.sum()) < 500:          # too little context to measure honestly
+        return warped
+
+    lab_photo = cv2.cvtColor(photo, cv2.COLOR_BGR2LAB).astype(np.float64)
+    lab_warp = cv2.cvtColor(warped, cv2.COLOR_BGR2LAB).astype(np.float64)
+    inside = (mask > 200).astype(np.uint8)
+    if int(inside.sum()) < 500:
+        return warped
+
+    m_out, s_out = _stats(lab_photo, ring)
+    m_in, s_in = _stats(lab_warp, inside)
+
+    out = lab_warp.copy()
+    # a,b: full Reinhard transfer, scaled by strength.
+    for c in (1, 2):
+        moved = (lab_warp[:, :, c] - m_in[c]) * float(s_out[c] / s_in[c]) + m_out[c]
+        out[:, :, c] = lab_warp[:, :, c] + (moved - lab_warp[:, :, c]) * strength
+    # L: mean shift only, and capped at +-12 L* so a dark room cannot switch
+    # the screen off. 12 is about a stop; beyond that it stops reading as the
+    # same screenshot.
+    dL = float(np.clip(m_out[0] - m_in[0], -12.0, 12.0)) * strength
+    out[:, :, 0] = lab_warp[:, :, 0] + dL
+
+    out[:, :, 0] = np.clip(out[:, :, 0], 0, 255)
+    out[:, :, 1:] = np.clip(out[:, :, 1:], 0, 255)
+    return cv2.cvtColor(out.astype(np.uint8), cv2.COLOR_LAB2BGR)
+
+
+def measure_grain(photo: np.ndarray, ring: np.ndarray) -> float:
+    """The photo's noise floor, in grey levels, measured where the screen isn't.
+
+    High-pass with a 3x3 median (cheap, edge-preserving) and take the MEDIAN
+    absolute deviation of the residual rather than its standard deviation: a
+    bezel edge or a highlight inside the ring is a huge outlier, and a mean-based
+    estimate would read the edge as noise and dump visible grain on the screen.
+    0.6745 converts MAD to a sigma for a normal distribution.
+    """
+    g = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
+    resid = g.astype(np.float32) - cv2.medianBlur(g, 3).astype(np.float32)
+    px = resid[ring.astype(bool)]
+    if px.size < 500:
+        return 0.0
+    return float(np.median(np.abs(px - np.median(px))) / 0.6745)
+
+
+def add_grain(img: np.ndarray, mask: np.ndarray, sigma: float, seed: int = 0) -> np.ndarray:
+    """Lay the measured noise floor over the injected screen only.
+
+    Seeded, so a re-run is byte-identical — determinism is a stated verification
+    rule for this tool, and unseeded noise would break it silently. Monochrome
+    rather than per-channel: sensor noise after demosaicing is strongly
+    correlated across channels, and independent RGB noise reads as colour
+    speckle, which is worse than no grain at all.
+    """
+    if sigma <= 0.05:
+        return img
+    sigma = float(min(sigma, 6.0))          # beyond this it stops being grain
+    rng = np.random.default_rng(seed)
+    noise = rng.normal(0.0, sigma, img.shape[:2]).astype(np.float32)
+    a = (mask.astype(np.float32) / 255.0)[:, :, None]
+    return np.clip(img.astype(np.float32) + noise[:, :, None] * a, 0, 255).astype(np.uint8)
+
+
+def specular_lift(composite: np.ndarray, screen_off: np.ndarray, mask: np.ndarray,
+                  strength: float = 0.75) -> np.ndarray:
+    """Re-composite the device's REAL reflections over the injected screen.
+
+    Needs a second photograph of the same scene with the screen off. A dark
+    screen is nearly a mirror, so that frame contains the true specular
+    highlights — window, lamp, the photographer — in exactly the right places
+    with the right shape. Lifting them beats any attempt to invent them, which
+    is the single thing every AI mockup tool gets visibly wrong.
+
+    The highlight layer is what the off-screen has ABOVE its own dark floor, so
+    the floor is subtracted first; screen-space SCREEN blend, because
+    reflections add light and never subtract it.
+    """
+    if screen_off is None or strength <= 0:
+        return composite
+    if screen_off.shape[:2] != composite.shape[:2]:
+        raise ValueError("screen-off reference must be the same size as the photo — "
+                         "it has to be the same shot, tripod-locked, not a re-frame")
+    sel = mask > 0
+    if not sel.any():
+        return composite
+
+    off_l = cv2.cvtColor(screen_off, cv2.COLOR_BGR2GRAY).astype(np.float32)
+    floor = float(np.percentile(off_l[sel], 20))     # the glass at its darkest
+    hi = np.clip(off_l - floor, 0, None)
+    peak = float(np.percentile(hi[sel], 99.5))
+    if peak < 2.0:                                    # nothing specular to lift
+        return composite
+    hi = np.clip(hi / peak, 0, 1) * (mask.astype(np.float32) / 255.0) * float(strength)
+
+    base = composite.astype(np.float32) / 255.0
+    lifted = 1.0 - (1.0 - base) * (1.0 - hi[:, :, None])   # screen blend
+    out = np.clip(lifted * 255.0, 0, 255).astype(np.uint8)
+    # A screen blend cannot darken, but the /255 -> *255 round trip quantises:
+    # measured 41% of pixels coming back exactly ONE level below the input where
+    # the highlight contributes nothing. Clamping to the input enforces the
+    # property the maths already has, instead of dimming the whole composite by
+    # a level for no reason.
+    return np.maximum(out, composite)

package/scripts/launch.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env zsh
+# screengraft — start ui.py as a detached daemon.
+#
+# HISTORY, because this has been wrong twice.
+#   1. `nohup ui.py & disown` from the agent's shell (3 Sep 2026): the
+#      server died silently between turns, twice, losing whatever the designer
+#      had already entered. nohup blocks SIGHUP but not the session teardown
+#      some launchers use.
+#   2. A Terminal.app window via osascript: survives, but leaves a dead
+#      "[Process completed]" window behind after every single session. The author
+#      ended up with a row of them (4 Sep 2026). Closing them again from
+#      AppleScript proved unreliable — Terminal reports stale ttys for dead
+#      windows and can leave zero-tab window husks that `close` reports
+#      success on without removing.
+#
+# So: `--daemon` double-forks and calls setsid, putting the server in its own
+# session with no controlling terminal. It outlives the launching shell for
+# the same reason a Terminal window did, and there is no window to clean up.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PORT=0
+OUT_DIR=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out-dir) OUT_DIR="${2:-}"; shift 2 ;;
+    --out-dir=*) OUT_DIR="${1#*=}"; shift ;;
+    --port) PORT="${2:-0}"; shift 2 ;;
+    --port=*) PORT="${1#*=}"; shift ;;
+    ''|*[!0-9]*) echo "error: unknown argument: $1" >&2; exit 2 ;;
+    *) PORT="$1"; shift ;;
+  esac
+done
+
+PYEXE="$HOME/.screengraft/venv/bin/python"
+[ -x "$PYEXE" ] || PYEXE="python3"
+LOG="$(mktemp -t screengraft-ui.XXXXXX).log"
+
+if [ -n "$OUT_DIR" ]; then
+  "$PYEXE" "$ROOT/scripts/ui.py" --port "$PORT" --no-open --daemon --log "$LOG" --out-dir "$OUT_DIR"
+else
+  "$PYEXE" "$ROOT/scripts/ui.py" --port "$PORT" --no-open --daemon --log "$LOG"
+fi
+
+# The daemon writes its startup JSON to the log; wait for it, then confirm the
+# server actually answers before telling anyone it is ready.
+for i in $(seq 1 40); do
+  [ -s "$LOG" ] && break
+  sleep 0.25
+done
+if [ ! -s "$LOG" ]; then
+  echo "error: no output from ui.py after 10s; log: $LOG" >&2
+  exit 1
+fi
+URL=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['url'])" "$LOG" 2>/dev/null || true)
+if [ -z "$URL" ]; then
+  echo "error: couldn't parse url from $LOG:" >&2
+  cat "$LOG" >&2
+  exit 1
+fi
+sleep 1
+if ! curl -sf -o /dev/null "${URL}api/state"; then
+  echo "error: server not responding at $URL after launch. Log: $LOG" >&2
+  cat "$LOG" >&2
+  exit 1
+fi
+cat "$LOG"
+echo "log: $LOG"
+open "$URL" >/dev/null 2>&1 || true

package/scripts/preflight.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+screengraft — preflight. Run this first, every time.
+
+Reports what the plugin needs and whether it's there, as JSON, so the skill
+can tell the user plainly what's missing before promising anything.
+
+  python3 scripts/preflight.py            -> JSON report, exit 0 if ready, 1 if not
+  python3 scripts/preflight.py --install  -> create ~/.screengraft/venv and install
+                                             requirements.txt into it (only run this
+                                             after the user has said yes)
+
+OpenCV is a HARD requirement: it is the engine. Without it nothing runs — not
+"results will be worse", nothing. Say exactly that. Optional extras (SAM 2,
+later) are the tier where "works, but worse without" applies.
+
+The venv lives outside the plugin folder (~/.screengraft/venv) so it survives
+plugin updates and never touches the user's system Python.
+"""
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REQ = os.path.join(HERE, "requirements.txt")
+VENV = os.path.expanduser("~/.screengraft/venv")
+VENV_PY = os.path.join(VENV, "bin", "python")
+
+REQUIRED = [
+    ("cv2", "opencv-python-headless", "The engine: homography, warp, detection. Nothing runs without it."),
+    ("numpy", "numpy", "Array math for the compositing step."),
+]
+
+
+def probe(pyexe: str):
+    """Ask a given python which required modules import."""
+    code = (
+        "import json,importlib\n"
+        "out={}\n"
+        "for m in %r:\n"
+        "    try:\n"
+        "        mod=importlib.import_module(m); out[m]=getattr(mod,'__version__','ok')\n"
+        "    except Exception as e:\n"
+        "        out[m]=None\n"
+        "print(json.dumps(out))"
+    ) % [m for m, _, _ in REQUIRED]
+    try:
+        r = subprocess.run([pyexe, "-c", code], capture_output=True, text=True, timeout=60)
+        return json.loads(r.stdout) if r.returncode == 0 and r.stdout.strip() else {m: None for m, _, _ in REQUIRED}
+    except Exception:
+        return {m: None for m, _, _ in REQUIRED}
+
+
+def report():
+    py_candidates = []
+    if os.path.exists(VENV_PY):
+        py_candidates.append(("venv", VENV_PY))
+    py_candidates.append(("system", sys.executable))
+
+    chosen = None
+    probes = {}
+    for label, exe in py_candidates:
+        found = probe(exe)
+        probes[label] = {"python": exe, "modules": found}
+        if all(found.get(m) for m, _, _ in REQUIRED) and chosen is None:
+            chosen = (label, exe)
+
+    missing = [] if chosen else [
+        {"module": m, "pip": pkg, "why": why}
+        for m, pkg, why in REQUIRED
+        if not probes[py_candidates[0][0]]["modules"].get(m)
+    ]
+    return {
+        "ready": chosen is not None,
+        "python": chosen[1] if chosen else None,
+        "python_source": chosen[0] if chosen else None,
+        "platform": platform.platform(),
+        "venv": VENV,
+        "venv_exists": os.path.exists(VENV_PY),
+        "probes": probes,
+        "missing": missing,
+        "hard_requirement": "OpenCV is the engine. Without it screengraft cannot run at all — this is not a degraded mode, it is no mode.",
+        "install_command": f"{sys.executable} {os.path.abspath(__file__)} --install",
+        "install_does": f"Creates a virtualenv at {VENV} (nothing touches system Python) and pip-installs "
+                        f"{', '.join(pkg for _, pkg, _ in REQUIRED)} into it (~60 MB download).",
+        "optional": [
+            {"name": "SAM 2 (M4)", "status": "not yet used by the plugin",
+             "why": "Better screen detection on photos where tone-based detection fails. Optional; results are worse without it, not absent."}
+        ],
+        "tools": {"open_browser": shutil.which("open") or shutil.which("xdg-open")},
+    }
+
+
+def install():
+    os.makedirs(os.path.dirname(VENV), exist_ok=True)
+    if not os.path.exists(VENV_PY):
+        subprocess.check_call([sys.executable, "-m", "venv", VENV])
+    subprocess.check_call([VENV_PY, "-m", "pip", "install", "-q", "--upgrade", "pip"])
+    subprocess.check_call([VENV_PY, "-m", "pip", "install", "-q", "-r", REQ])
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--install", action="store_true", help="Create the venv and install requirements (ask the user first)")
+    args = ap.parse_args()
+    if args.install:
+        install()
+    rep = report()
+    print(json.dumps(rep, indent=1))
+    sys.exit(0 if rep["ready"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/requirements.txt

@@ -0,0 +1,2 @@
+opencv-python-headless>=4.9
+numpy>=1.26

package/scripts/scan.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+screengraft — recent images a designer is likely to want.
+
+Scans ~/Desktop and ~/Downloads (the two places people actually save to) for
+image files modified in the last N days, newest first, and prints JSON. The
+UI shows these as pick-one thumbnails so nobody has to type a path.
+
+  python3 scripts/scan.py [--days 14] [--limit 40] [--thumbs DIR]
+
+HEIC (iPhone photos) is converted to JPEG for the thumbnail via `sips` on
+macOS; OpenCV can't read HEIC. Run every time the skill starts — new photos
+appear between sessions.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+
+EXTS = {".png", ".jpg", ".jpeg", ".webp", ".heic", ".heif", ".tif", ".tiff"}
+FOLDERS = ["~/Desktop", "~/Downloads"]
+
+
+def scan(days: int, limit: int):
+    cutoff = time.time() - days * 86400
+    items = []
+    for f in FOLDERS:
+        d = os.path.expanduser(f)
+        if not os.path.isdir(d):
+            continue
+        try:
+            names = os.listdir(d)
+        except PermissionError:
+            continue
+        for n in names:
+            if n.startswith("."):
+                continue
+            p = os.path.join(d, n)
+            ext = os.path.splitext(n)[1].lower()
+            if ext not in EXTS or not os.path.isfile(p):
+                continue
+            st = os.stat(p)
+            if st.st_mtime < cutoff:
+                continue
+            items.append({"path": p, "name": n, "folder": f, "mtime": st.st_mtime, "bytes": st.st_size, "ext": ext})
+    items.sort(key=lambda x: -x["mtime"])
+    return items[:limit]
+
+
+def thumb(item, out_dir: str, size: int = 320):
+    """Write a small JPEG thumbnail; returns its path or None."""
+    os.makedirs(out_dir, exist_ok=True)
+    base = os.path.splitext(item["name"])[0]
+    out = os.path.join(out_dir, f"{abs(hash(item['path']))}_{base[:40]}.jpg")
+    if os.path.exists(out):
+        return out
+    if sys.platform == "darwin":
+        # sips handles HEIC and everything else natively; no OpenCV needed here.
+        r = subprocess.run(["sips", "-s", "format", "jpeg", "-Z", str(size), item["path"], "--out", out],
+                           capture_output=True, text=True)
+        return out if r.returncode == 0 and os.path.exists(out) else None
+    try:
+        import cv2
+        im = cv2.imread(item["path"])
+        if im is None:
+            return None
+        h, w = im.shape[:2]
+        s = size / max(h, w)
+        im = cv2.resize(im, (max(1, int(w * s)), max(1, int(h * s))), interpolation=cv2.INTER_AREA)
+        cv2.imwrite(out, im, [cv2.IMWRITE_JPEG_QUALITY, 80])
+        return out
+    except Exception:
+        return None
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--days", type=int, default=14)
+    ap.add_argument("--limit", type=int, default=40)
+    ap.add_argument("--thumbs", help="Directory to write thumbnails into (optional)")
+    args = ap.parse_args()
+    items = scan(args.days, args.limit)
+    if args.thumbs:
+        for it in items:
+            it["thumb"] = thumb(it, args.thumbs)
+    print(json.dumps({"folders": FOLDERS, "days": args.days, "count": len(items), "items": items}, indent=1))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/stop.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env zsh
+# Stop the screengraft UI.
+#
+# SIGTERM, not SIGKILL: ui.py catches it and runs its atexit, which clears the
+# session pointer the MCP server reads. A hard kill leaves a stale pointer and
+# the agent then blocks a full timeout against a session nobody is in.
+set -euo pipefail
+if ! pgrep -f 'scripts/ui.py' >/dev/null 2>&1; then
+  echo "no screengraft UI running"
+  exit 0
+fi
+pkill -TERM -f 'scripts/ui.py' || true
+for i in $(seq 1 20); do
+  pgrep -f 'scripts/ui.py' >/dev/null 2>&1 || break
+  sleep 0.25
+done
+if pgrep -f 'scripts/ui.py' >/dev/null 2>&1; then
+  echo "warning: still running after 5s, forcing" >&2
+  pkill -KILL -f 'scripts/ui.py' || true
+fi
+echo "screengraft UI stopped"