screengraft 0.54.8 → 0.56.0

package/README.md

@@ -138,8 +138,10 @@ outside the screen mask. It never touches the pixels you designed.
    warp never area-averages, so warping a 1206×2622 screenshot into a 226×454
    quad without it turns body text into noise.
 3. **Realism pass** *(optional)* — white balance and exposure toward the
-   surrounding light, grain matched to the photo's own noise floor, real
-   speculars lifted from a screen-off reference.
+   surrounding light, grain measured from the photo's own noise floor and
+   laid on the screen at 0.7× of it (a lit screen sits in the highlights, where
+   8-bit noise is lower than on the body around it), real speculars lifted
+   from a screen-off reference.
 4. **Video**, when the source is a clip — everything a fixed photo and a fixed
    quad make constant is computed once, and only the frame changes. Three
    consequences worth naming, because each is a way video normally goes wrong:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.54.8",
+  "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/dof.py

@@ -281,7 +281,7 @@ def measure(photo: np.ndarray, corners) -> dict:
         out.update({"angle": 0.0, "strength": 0.0, "flat": True})
         return out
     Amat = np.column_stack([mids[:, 0], mids[:, 1], np.ones(len(mids))])
-    (a, b, c), *_ = np.linalg.lstsq(Amat, sig, rcond=None)
+    (a, b, _c), *_ = np.linalg.lstsq(Amat, sig, rcond=None)
     angle = math.degrees(math.atan2(b, a)) % 360.0
     strength = float(np.clip((sig.max() - lo) / max(sigma_max(q, 1.0), 1e-6), 0.0, 1.0))
     out.update({"angle": round(angle, 1), "strength": round(strength, 3), "flat": False})

package/scripts/grade.py

@@ -131,6 +131,15 @@ def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
 
 
 GRAIN_GATE = 20.0        # grey levels: above this a residual is an edge, not grain
+# How much of the SURROUND's noise floor a lit screen should carry. The sigma is
+# measured on the ring around the screen -- bezel and body, usually the darkest
+# thing near it -- but the injected screen is usually the brightest thing in
+# the frame, and after the sRGB curve a highlight carries less noise in grey
+# levels than a shadow does. Measured on the 38-photo corpus (13 Sep 2026):
+# the 192-255 band's floor is a median 0.67x the 0-63 band's. A designer's
+# eye on a full-resolution save said the same thing first: "a bit smaller".
+# 1.0 is the pre-v0.55 behaviour and is what an old sidecar replays with.
+SCREEN_GRAIN_GAIN = 0.7
 _MEDIAN_HP_GAIN = 0.909  # a 3x3 median high-pass absorbs this much of iid noise
                          # (measured, 5 seeds x sigma 1-5, spread < 0.3%)
 

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
@@ -50,6 +51,7 @@ import detect as D  # noqa: E402
 import fitfile as FF  # noqa: E402
 import fits as FIT  # noqa: E402
 import dof as DOF   # noqa: E402
+import grade as _grade  # noqa: E402
 import scan as S  # noqa: E402
 import warp as W  # noqa: E402
 
@@ -64,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):
@@ -578,7 +587,8 @@ PREVIEW_SECONDS = 6.0
 
 def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame,
                    blend="replace", reflection=None, result=None, kind="render",
-                   start_frame=0, max_frames=None, *, smoothing=0.0, dof=None):
+                   start_frame=0, max_frames=None, *, smoothing=0.0, dof=None,
+                   grain_gain=1.0):
     """Encode the clip, and only if that SUCCEEDS publish what it produced.
 
     `result` is the sidecar this render would write. It is handed to the worker
@@ -598,7 +608,7 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
     try:
         info = W.compose_video(photo, video_path, corners, dest,
                                corner_radius=radius_px, corner_smoothing=smoothing,
-                               grade=gr, grain=grain,
+                               grade=gr, grain=grain, grain_gain=grain_gain,
                                preset=preset, fit_frame=fit_frame, progress=progress,
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
@@ -666,6 +676,22 @@ def _blend_args(b):
     return "emissive", float(max(0.0, min(1.0, float(r))))
 
 
+def _grain_gain(b) -> float:
+    """How much of the surround's noise floor the screen carries.
+
+    The page does not set this; fresh renders get grade.SCREEN_GRAIN_GAIN. It
+    is read from the body so a sidecar replayed through the API keeps its own
+    value -- a sidecar from before the gain existed carries none and passes
+    1.0 explicitly at the replay site, never here.
+    """
+    try:
+        g = float(b.get("grain_gain")) if b.get("grain_gain") is not None \
+            else _grade.SCREEN_GRAIN_GAIN
+    except (TypeError, ValueError):
+        g = _grade.SCREEN_GRAIN_GAIN
+    return float(min(max(g, 0.0), 2.0))
+
+
 def _dof_args(b):
     """Depth-of-field kwargs from the page, as a dict compose() takes directly.
 
@@ -801,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)
@@ -875,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")
@@ -932,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.
@@ -1194,7 +1269,8 @@ class Handler(BaseHTTPRequestHandler):
                                            blend, reflection, None, "preview",
                                            fit_frame, max_frames),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof": _dof_args(b)}).start()
+                                             "dof": _dof_args(b),
+                                             "grain_gain": _grain_gain(b)}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1247,7 +1323,7 @@ class Handler(BaseHTTPRequestHandler):
                 result = {"output": dest, "photo": ppath, "screenshot": spath,
                           "corners": corners, "radius_frac": frac, "radius_px": radius_px,
                           "device": b.get("device"), "corner_smoothing": _smoothing(b),
-                          "grade": gr, "grain": grain,
+                          "grade": gr, "grain": grain, "grain_gain": _grain_gain(b),
                           "video": True, "preset": preset, "fit_frame": fit_frame,
                           "blend": blend, "reflection": reflection,
                           "dof_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
@@ -1280,7 +1356,8 @@ class Handler(BaseHTTPRequestHandler):
                                            gr, grain, preset, fit_frame,
                                            blend, reflection, result),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof": dof}).start()
+                                             "dof": dof,
+                                             "grain_gain": result["grain_gain"]}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1304,9 +1381,11 @@ class Handler(BaseHTTPRequestHandler):
                 blend, reflection = _blend_args(b)
                 smoothing = _smoothing(b)
                 dof = _dof_args(b)
+                grain_gain = _grain_gain(b)
                 out = W.compose(photo, shot, corners, radius_px,
                                 corner_smoothing=smoothing,
                                 grade=gr, grain=bool(b.get("grain", gr > 0)),
+                                grain_gain=grain_gain,
                                 blend=blend, reflection=reflection, **dof)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
@@ -1342,6 +1421,7 @@ class Handler(BaseHTTPRequestHandler):
                           "radius_frac": frac, "radius_px": radius_px, "device": b.get("device"),
                           "corner_smoothing": smoothing,
                           "grade": gr, "grain": bool(b.get("grain", gr > 0)),
+                          "grain_gain": grain_gain,
                           "blend": blend, "reflection": reflection,
                           "dof_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
                           "dof_start": dof["dof_start"], "dof_end": dof["dof_end"],
@@ -1450,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")
@@ -1475,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
@@ -1483,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/scripts/warp.py

@@ -270,7 +270,8 @@ class Plan:
                  blend: str = "replace", reflection: float = DEFAULT_REFLECTION,
                  corner_smoothing: float = 0.0,
                  dof_angle: float = 0.0, dof_strength: float = 0.0, dof_start: float = 0.0,
-                 dof_end: float = 1.0, dof_space: str = "photo", dof_end2=None):
+                 dof_end: float = 1.0, dof_space: str = "photo", dof_end2=None,
+                 grain_gain: float = 1.0):
         dst_quad = np.array(corners, dtype=np.float32)
         if shoelace_area(dst_quad) < 1.0:
             raise ValueError("degenerate quad (near-zero area) — check corner order TL,TR,BR,BL")
@@ -310,8 +311,12 @@ class Plan:
                                 self.corner_smoothing)
         self.warped_mask = _warp_mask_antialiased(src_mask, self.H, pw, ph, dst_quad)
         self.mask3 = cv2.merge([self.warped_mask] * 3).astype(np.float32) / 255.0
+        # The floor is the surround's; the screen carries `grain_gain` of it
+        # (see grade.SCREEN_GRAIN_GAIN). Defaults to 1.0 so a sidecar written
+        # before the gain existed reproduces its save byte for byte.
+        self.grain_gain = float(max(grain_gain, 0.0))
         self.grain_sigma = (_grade.measure_grain(photo, _grade.surround_ring(self.warped_mask))
-                            if grain else 0.0)
+                            * self.grain_gain if grain else 0.0)
         self.grade_params = None
         # Integer bbox of the quad, clamped to the canvas and padded by a pixel
         # so the antialiased edge is never clipped.
@@ -444,7 +449,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
             reflection: float = DEFAULT_REFLECTION,
             dof_angle: float = 0.0, dof_strength: float = 0.0,
             dof_start: float = 0.0, dof_end: float = 1.0,
-            dof_space: str = "photo", dof_end2=None) -> np.ndarray:
+            dof_space: str = "photo", dof_end2=None,
+            grain_gain: float = 1.0) -> np.ndarray:
     """Warp `screenshot` into the quad `corners` (TL,TR,BR,BL, photo pixels) on `photo`.
 
     Single resampling pass at the photo's resolution; deterministic. This is the
@@ -459,7 +465,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
-                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2)
+                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
+                grain_gain=grain_gain)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -549,7 +556,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   start_frame: int = 0, max_frames: int = None,
                   dof_angle: float = 0.0, dof_strength: float = 0.0,
                   dof_start: float = 0.0, dof_end: float = 1.0,
-                  dof_space: str = "photo", dof_end2=None) -> dict:
+                  dof_space: str = "photo", dof_end2=None,
+                  grain_gain: float = 1.0) -> dict:
     """Inject a VIDEO into a still photo. The photo does not move, so there is
     exactly one homography and the whole of Plan is computed once.
 
@@ -578,7 +586,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
-                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2)
+                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
+                grain_gain=grain_gain)
     plan.bind_grade(first, grade)
 
     ph, pw = photo.shape[:2]

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.54):** 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