screengraft 0.55.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Put a UI screenshot or screen recording onto a photographed device screen with the perspective exactly right \u2014 a homography you confirm by hand, not a generative guess.",
   "keywords": [
     "mockup",

package/scripts/launch.sh

@@ -73,13 +73,15 @@ if [ ! -s "$LOG" ]; then
   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
+BASE=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['base'])" "$LOG" 2>/dev/null || true)
+if [ -z "$URL" ] || [ -z "$BASE" ]; 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
+# /api/ping is the one route that needs no token: it answers liveness only.
+if ! curl -sf -o /dev/null "${BASE}api/ping"; then
   echo "error: server not responding at $URL after launch. Log: $LOG" >&2
   cat "$LOG" >&2
   exit 1

package/scripts/ui.py

@@ -31,6 +31,7 @@ import atexit
 import json
 import mimetypes
 import os
+import secrets
 import signal
 import socket
 import subprocess
@@ -65,6 +66,13 @@ UI_HTML = os.path.join(ROOT, "ui", "index.html")
 # to find the session, and checks the pid so a pointer left by a crashed UI is
 # treated as no UI at all rather than one that never answers.
 CURRENT = os.path.join(HOME, ".screengraft", "current.json")
+# The session token. Minted once per launch in main(); the page gets it in its
+# URL (`/?t=<token>`) and echoes it on every request. Without it the server
+# binds 127.0.0.1 but authenticates nothing: a page the person happens to have
+# open in the same browser can sweep localhost ports and fire blind POSTs --
+# not readable back (same-origin), but delivered, and one of them enqueues a
+# job that an agent then acts on. See _authorised() for the two checks.
+TOKEN = None
 
 
 def _write_json_atomic(path, obj):
@@ -819,6 +827,40 @@ class Handler(BaseHTTPRequestHandler):
         pass
 
     # ---- helpers ----
+    def _authorised(self, q) -> bool:
+        """Two checks, both cheap, closing two different doors.
+
+        1. `Sec-Fetch-Site`: a browser stamps every request with where it came
+           from. `same-origin` is our own page, `none` is the address bar or a
+           bookmark. Anything else -- `cross-site`, `same-site` -- is another
+           page on another origin driving this server, and is refused whether
+           or not it somehow holds the token (the URL can end up in a
+           screenshot). curl and urllib send no such header and pass this
+           check; that is what the token is for.
+        2. The token, as the `X-Screengraft-Token` header (the page's fetches)
+           or the `t` query parameter (the page itself, <img>/<video> sources,
+           which cannot set headers). Constant-time compare, as a habit.
+        """
+        site = self.headers.get("Sec-Fetch-Site")
+        if site and site not in ("same-origin", "none"):
+            return False
+        tok = self.headers.get("X-Screengraft-Token") or (q.get("t") or [""])[0]
+        return bool(tok) and bool(TOKEN) and secrets.compare_digest(tok, TOKEN)
+
+    def _refuse(self, u):
+        if u.path == "/":
+            body = (b"<!doctype html><meta charset=utf-8><title>screengraft</title>"
+                    b"<p style='font:14px system-ui;margin:2em'>This page needs the link the "
+                    b"launcher printed &mdash; it carries a one-session token. "
+                    b"Relaunch with <code>scripts/launch.sh</code> and open the URL it prints.")
+            self.send_response(403)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+            return
+        self._json({"error": "missing or wrong session token"}, 403)
+
     def _json(self, obj, code=200):
         body = json.dumps(obj).encode()
         self.send_response(code)
@@ -893,6 +935,13 @@ class Handler(BaseHTTPRequestHandler):
     def do_GET(self):
         u = urllib.parse.urlparse(self.path)
         q = urllib.parse.parse_qs(u.query)
+        # The one open route: liveness. Says nothing but that a screengraft is
+        # here and which version -- launch.sh and the skill probe it before
+        # telling anyone the UI is ready, with no token in hand.
+        if u.path == "/api/ping":
+            return self._json({"ok": True, "version": VERSION})
+        if not self._authorised(q):
+            return self._refuse(u)
         try:
             if u.path == "/":
                 return self._file(UI_HTML, "text/html; charset=utf-8")
@@ -950,6 +999,14 @@ class Handler(BaseHTTPRequestHandler):
     # ---- POST ----
     def do_POST(self):
         u = urllib.parse.urlparse(self.path)
+        if not self._authorised(urllib.parse.parse_qs(u.query)):
+            # Read the body off the wire first (bounded): refusing while the
+            # client is still sending turns a clean 403 into a broken pipe on
+            # its side, which reads as "the server died", not "you were refused".
+            n = min(int(self.headers.get("Content-Length") or 0), 64 << 20)
+            while n > 0:
+                n -= len(self.rfile.read(min(n, 1 << 20)) or b"\0")
+            return self._refuse(u)
         try:
             if u.path == "/api/upload":
                 # raw bytes + X-Filename + X-Role (photo|screenshot); no multipart, no cgi module.
@@ -1473,7 +1530,7 @@ def _publish_current(payload):
 
 
 def main():
-    global SESSION, OUT_DIR, VERSION, BUILD
+    global SESSION, OUT_DIR, VERSION, BUILD, TOKEN
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--port", type=int, default=0, help="0 = pick a free port")
     ap.add_argument("--no-open", action="store_true", help="Don't open the browser")
@@ -1498,7 +1555,11 @@ def main():
     sdir = args.session or os.path.join(HOME, ".screengraft", "sessions", time.strftime("%Y%m%d-%H%M%S"))
     SESSION = Session(sdir)
     port = args.port or free_port()
-    url = f"http://127.0.0.1:{port}/"
+    TOKEN = secrets.token_urlsafe(18)
+    base = f"http://127.0.0.1:{port}/"
+    # `url` is what a person opens; `base` + the token header is what a tool
+    # uses. Kept apart so nobody has to strip a query string off a URL.
+    url = f"{base}?t={TOKEN}"
     srv = ThreadingHTTPServer(("127.0.0.1", port), Handler)
     freed = _prune_sessions(sdir)
     # The live session's own copies go when this process does. Registered before
@@ -1506,11 +1567,11 @@ def main():
     # scripts/stop.sh sends SIGTERM for exactly this reason. A kill -9 cannot be
     # caught, which is what the launch-time sweep above is for.
     atexit.register(lambda: _sweep_session(sdir))
-    _publish_current({"session": sdir, "url": url, "pid": os.getpid(),
-                      "out_dir": OUT_DIR, "started": time.time()})
-    print(json.dumps({"url": url, "session": sdir, "job": SESSION.job_path,
-                      "result": SESSION.result_path, "out_dir": OUT_DIR,
-                      "reclaimed_mb": round(freed / 1e6, 1)}), flush=True)
+    _publish_current({"session": sdir, "url": url, "base": base, "token": TOKEN,
+                      "pid": os.getpid(), "out_dir": OUT_DIR, "started": time.time()})
+    print(json.dumps({"url": url, "base": base, "token": TOKEN, "session": sdir,
+                      "job": SESSION.job_path, "result": SESSION.result_path,
+                      "out_dir": OUT_DIR, "reclaimed_mb": round(freed / 1e6, 1)}), flush=True)
     if not args.no_open:
         opener = "open" if sys.platform == "darwin" else "xdg-open"
         threading.Timer(0.3, lambda: subprocess.Popen([opener, url])).start()

package/skills/inject-screenshot/SKILL.md

@@ -5,7 +5,7 @@ description: Injects a UI screenshot OR a screen recording onto a photographed d
 
 # Inject a screenshot onto a photographed device
 
-**What ships (v0.55):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
+**What ships (v0.56):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
 
 The geometry is exact (`warp.py`); the detection is advisory (`detect.py`) and the human corrects it. **When a detection is wrong and you want to know why**, ask for the candidate list: `POST /api/detect {"trace": true}` writes `<session>/candidates.json`, or run `python3 scripts/detect.py --photo P --out-corners /tmp/c.json --trace /tmp/t.json` (add `--click X,Y`). Every candidate quad is in there with its score and whether it was accepted, rejected, never reached, or filtered out by the click — which is what separates "the screen was never proposed" from "it was proposed and something else won".
 
@@ -60,9 +60,9 @@ scripts/launch.sh --out-dir "<the user's current project folder>/mockups"
 
 A Terminal.app window was the previous fix for the same problem. It worked but left a dead "[Process completed]" window behind after every session, and closing those from AppleScript proved unreliable — Terminal reports stale ttys for dead windows and leaves zero-tab husks that `close` reports success on. The daemon removes the window entirely, so there is nothing to clean up.
 
-It prints one JSON line — `url`, `session`, `job`, `result`, `out_dir` — and opens the browser tab itself. If it exits non-zero, read the error and the log path it names before telling the user anything is ready.
+It prints one JSON line — `url`, `base`, `token`, `session`, `job`, `result`, `out_dir` — and opens the browser tab itself. `url` carries a one-session token (`/?t=…`); the server refuses any request without it, so always hand the user `url`, never `base`. If it exits non-zero, read the error and the log path it names before telling the user anything is ready.
 
-**Verify liveness again right before telling the user to interact with it** — `curl -sf <url>api/state` — especially if any time has passed since launch. If that fails, the server died; say so, relaunch, and have the user redo their last action rather than assuming it's still there.
+**Verify liveness again right before telling the user to interact with it** — `curl -sf <base>api/ping` (the one route that needs no token) — especially if any time has passed since launch. If that fails, the server died; say so, relaunch, and have the user redo their last action rather than assuming it's still there.
 
 **Then explain the job in chat.** The page deliberately carries no onboarding — the explanation belongs here, where the user already is. Say this, in your own words but keeping all of it:
 

package/ui/index.html

@@ -1444,11 +1444,18 @@ function toast(kind, html, opts = {}) {
   return item;
 }
 
+// The session token rides in the page's own URL (`/?t=...`, minted per launch)
+// and goes back on every request: as a header from fetch, as a query
+// parameter on <img>/<video> sources, which cannot set headers. The server
+// refuses anything without it, and anything cross-site with it.
+const TOKEN = new URLSearchParams(location.search).get('t') || '';
+const authFetch = (p, init = {}) =>
+  fetch(p, {...init, headers: {...(init.headers || {}), 'X-Screengraft-Token': TOKEN}});
 const api = async (p, body, raw) => {
-  const r = await fetch(p, body===undefined ? {} : {method:'POST', headers: raw ? raw.headers : {'Content-Type':'application/json'}, body: raw ? raw.body : JSON.stringify(body)});
+  const r = await authFetch(p, body===undefined ? {} : {method:'POST', headers: raw ? raw.headers : {'Content-Type':'application/json'}, body: raw ? raw.body : JSON.stringify(body)});
   const j = await r.json(); if (!r.ok) throw new Error(j.error || r.statusText); return j;
 };
-const fileURL = p => '/file?path=' + encodeURIComponent(p);
+const fileURL = p => '/file?t=' + encodeURIComponent(TOKEN) + '&path=' + encodeURIComponent(p);
 // A source's URL carries the file's mtime, so new bytes at an old path are
 // fetched rather than served from the browser's cache (see _adopt in ui.py).
 const srcURL = (p, v) => fileURL(p) + (v ? '&v=' + v : '');
@@ -3291,7 +3298,7 @@ async function playClip(){
     // that FINISHED left the button on "Rendering…" for ever, with no toast and
     // Send to Claude never enabled. It looks exactly like a hung encode, which
     // is why it was reported as "no progress" rather than as a broken poll.
-    let d; try { d = await (await fetch('/api/render_status')).json(); }
+    let d; try { d = await (await authFetch('/api/render_status')).json(); }
     catch(e){ return; }
     if (d.state === 'running'){
       // The wait is real — tens of seconds on a long clip — so it counts frames
@@ -3481,7 +3488,7 @@ async function renderVideo(){
     // that FINISHED left the button on "Rendering…" for ever, with no toast and
     // Send to Claude never enabled. It looks exactly like a hung encode, which
     // is why it was reported as "no progress" rather than as a broken poll.
-    let d; try { d = await (await fetch('/api/render_status')).json(); }
+    let d; try { d = await (await authFetch('/api/render_status')).json(); }
     catch(e){ return; }
     if (d.state === 'running'){
       // The button IS the progress bar now. A spinner cannot be told apart