screengraft 0.67.0 → 0.68.0

package/package.json

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

@@ -1037,6 +1037,112 @@ def has_rounded_corners(result) -> bool:
     return spread <= MAX_RADIUS_SPREAD
 
 
+# ---------------------------------------------------------------------------
+# Working resolution.
+#
+# Detection ran at whatever resolution the photograph happened to be, and the
+# cost is quadratic: a 4000x4000 photo measured **11.24s** on 20 Sep 2026,
+# against 0.15s for the browser to fetch and decode the same file. Eleven
+# seconds of a designer's attention, every time they pick a big photo.
+#
+# The cap is **2400px on the short side, measured here** -- not the JS port's
+# 1600. That difference is the whole story of this change, so it is written
+# down rather than assumed.
+#
+# figma/src/engine/detect.js caps at 1600 and benches 27/27/0 there, so 1600
+# was the obvious number to copy. Swept over the 9 photographs in the corpus
+# whose short side exceeds the cap, comparing each capped answer against the
+# same photograph's full-resolution answer:
+#
+#     cap    total s   worst quad shift   worst radius shift
+#     full      41.2          --                 --
+#     1600       7.9        3.57%              19.3%
+#     2000      12.6        3.43%              18.6%
+#     2400      15.1        3.58%               5.0%
+#     3000      24.2        0.02%               0.4%
+#
+# 1600 moves the MEASURED CORNER RADIUS by 19% on both 4000x4000 photographs,
+# and the radius is not a starting position a person corrects -- it is the
+# number that shapes the corner mask on the saved composite. 2400 takes that to
+# 0.2% on those two while keeping 4K detection at ~1.7s against 13.3s.
+#
+# The residual 3.58% at 2400 is ONE photograph, iPhone-10_17-pro, which shifts
+# by ~3.5% at every cap below its own size -- it is scale-sensitive rather than
+# cap-sensitive, so there is no cap that fixes it short of not downscaling. It
+# stays inside the bench's 5%-of-screen-width band, and the quad is a starting
+# position the fit pane exists to correct.
+#
+# Why not the JS port's 1600, then? Because the two are not measuring the same
+# thing: that bench scores quads against human labels, and a 19% radius error
+# does not show up in a quad score at all. Worth re-checking the JS side.
+#
+# What this does NOT touch: the composite. Everything downstream -- the warp,
+# the grade, the corner mask, the saved file -- still works from the full
+# resolution photograph. This is a cap on the SEARCH, not on the output, which
+# is the whole point: on request, 21 Sep 2026 -- downscale for detection, show
+# full resolution in the preview.
+#
+# The pipeline runs entirely in working coordinates so that every internal
+# threshold, area ratio and diagonal stays self-consistent; only the geometry
+# that leaves detect() is scaled back. Radii come back too -- `photo_px` and
+# `per_corner_px` are pixel counts and must mean full-resolution pixels to
+# their caller -- while `frac_of_width` is a ratio and is already correct at
+# any scale, which is the reason the UI prefers it.
+#
+# INTER_AREA, not the default: downscaling with bilinear aliases, and an
+# aliased edge is precisely what an edge detector is looking at.
+# Overridable so the A/B above can be re-run without editing this file:
+#     SCREENGRAFT_DETECT_MAX=0    detect at full resolution (the old behaviour)
+#     SCREENGRAFT_DETECT_MAX=1600 the JS port's cap
+# Unset is the shipped 2400.
+WORK_MAX_SHORT = int(os.environ.get("SCREENGRAFT_DETECT_MAX", "2400") or 0) or None
+
+
+def work_scale(shape) -> float:
+    """Factor to multiply the photograph by before searching it. 1.0 = as-is."""
+    h, w = shape[:2]
+    short = min(int(h), int(w))
+    # A 10% deadband, so a photograph a little over the cap is left alone. A
+    # 1603px short side would otherwise be resampled to 1600 -- a 0.2% saving,
+    # paid for with a resize and a different set of pixels under the detector,
+    # which is the worst trade available: all of the risk of a change and none
+    # of the benefit.
+    if not WORK_MAX_SHORT or short <= WORK_MAX_SHORT * 1.1:
+        return 1.0
+    return float(WORK_MAX_SHORT) / float(short)
+
+
+def _shrink(img, s):
+    if img is None or s >= 1.0:
+        return img
+    return cv2.resize(img, None, fx=s, fy=s, interpolation=cv2.INTER_AREA)
+
+
+def _scale_quad(quad, k):
+    return [[round(float(x) * k, 1), round(float(y) * k, 1)] for x, y in quad]
+
+
+def _rescale_result(r, k):
+    """Put a result found in working coordinates back into photograph pixels."""
+    if r is None or k == 1.0:
+        return r
+    r["corners"] = _scale_quad(r["corners"], k)
+    if r.get("_corners_np") is not None:
+        r["_corners_np"] = np.asarray(r["_corners_np"], dtype=float) * k
+    cr = r.get("corner_radius")
+    if cr:
+        # frac_of_width is deliberately NOT touched: it is r/width, and both
+        # scaled by the same factor, so it survived the downscale unchanged.
+        if cr.get("photo_px") is not None:
+            cr["photo_px"] = round(float(cr["photo_px"]) * k, 1)
+        if cr.get("per_corner_px"):
+            cr["per_corner_px"] = [round(float(v) * k, 1) for v in cr["per_corner_px"]]
+    for o in (r.get("other") or []):
+        if o.get("corners"):
+            o["corners"] = _scale_quad(o["corners"], k)
+    return r
+
+
 def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None,
            trace=None):
     """Run both detectors; arbitrate on how the two quads nest.
@@ -1067,23 +1173,45 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None,
     # channel generated. It is an OBSERVER: nothing downstream reads it,
     # and the answer is identical with and without -- which is asserted, because
     # an instrument that perturbs what it measures is worse than none.
+    # Search a capped copy; see WORK_MAX_SHORT above. Everything below this
+    # point -- including the click, the shape handed to arbitrate(), and every
+    # trace row -- is in WORKING coordinates, and the single conversion back
+    # happens on the way out.
+    s = work_scale(gray.shape)
+    g = _shrink(gray, s)
+    col = _shrink(color, s) if color is not None else None
+    clk = [click[0] * s, click[1] * s] if (click is not None and s < 1.0) else click
+
     results = []
     if method in ("auto", "tone"):
-        r = detect_tone(gray, tone, click=click, trace=trace)
+        r = detect_tone(g, tone, click=clk, trace=trace)
         if r:
             results.append(r)
     if method in ("auto", "edge") and tone is None:
-        r = detect_edges(gray, click=click, trace=trace)
+        r = detect_edges(g, click=clk, trace=trace)
         if r:
             results.append(r)
-    if method in ("auto", "saturation") and tone is None and color is not None:
-        r = detect_saturation(color, click=click, trace=trace)
+    if method in ("auto", "saturation") and tone is None and col is not None:
+        r = detect_saturation(col, click=clk, trace=trace)
         if r:
             results.append(r)
 
+    k = 1.0 / s if s < 1.0 else 1.0
+    if trace is not None and k != 1.0:
+        # The trace is an observer and nothing downstream reads it, but a
+        # debugging artefact in a coordinate space the photograph does not use
+        # is a trap for whoever opens it next.
+        for row in trace:
+            if row.get("quad"):
+                row["quad"] = _scale_quad(row["quad"], k)
+
     if not results:
         return None
-    return arbitrate(results, gray.shape[:2], click)
+    out = arbitrate(results, g.shape[:2], clk)
+    if out is not None:
+        out["work_scale"] = round(s, 4)
+        _rescale_result(out, k)
+    return out
 
 
 def arbitrate(results, shape, click=None):

package/scripts/grade.py

@@ -62,7 +62,8 @@ def _stats(lab: np.ndarray, sel: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
 
 
 def light_params(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
-                 strength: float = DEFAULT_STRENGTH):
+                 strength: float = DEFAULT_STRENGTH,
+                 light: float = None, colour: float = None):
     """Measure the correction ONCE, so it can be applied to many frames.
 
     Split out of match_light for video. The correction depends on the
@@ -74,7 +75,30 @@ def light_params(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
     Returns None when there is too little context to measure honestly, which
     the caller must treat as "leave the frame alone".
     """
-    if strength <= 0:
+    # LIGHT and COLOUR are the same measurement, weighted separately.
+    #
+    # Split on request, 21 Sep 2026, from a real finding: with realism on, a
+    # brand orange visibly shifted toward coral and a pure-black status bar
+    # lifted to slate. Both are CORRECT -- nothing on a real phone renders #000
+    # -- but one control was doing two jobs, and the audience for this tool
+    # cares about exact hex. What moved the orange is the chroma match, not the
+    # exposure shift, so the useful cut is exactly the one this function
+    # already makes internally:
+    #
+    #   light  -> L only: a bounded mean shift. Sits the screen in the scene's
+    #             exposure and leaves hue alone.
+    #   colour -> a,b only: mean AND spread. The white-balance and saturation
+    #             match, and the one that moved the orange.
+    #
+    # Nothing about the arithmetic changed; only who scales which half.
+    #
+    # THE COMPATIBILITY CONTRACT: `strength` alone still works and still means
+    # what it meant. When light/colour are not given they ARE strength, so an
+    # old sidecar -- which carries `grade` and knows nothing of this split --
+    # replays through identical multiplications. test_sidecar.py pins it.
+    wL = float(strength if light is None else light)
+    wC = float(strength if colour is None else colour)
+    if wL <= 0 and wC <= 0:
         return None
     ring = surround_ring(mask)
     if int(ring.sum()) < 500:
@@ -88,10 +112,13 @@ def light_params(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
     m_in, s_in = _stats(lab_warp, inside)
     return {
         "m_in": m_in, "s_in": s_in, "m_out": m_out, "s_out": s_out,
-        "strength": float(strength),
+        # Kept under its old name and still the chroma weight, so apply_light()
+        # on a params dict from anywhere behaves as it always did.
+        "strength": wC,
+        "light": wL, "colour": wC,
         # Same clamp as match_light: a screen is emissive and may be brighter
         # than the room, so L moves by a bounded mean shift only.
-        "dL": float(np.clip(m_out[0] - m_in[0], -12.0, 12.0)) * float(strength),
+        "dL": float(np.clip(m_out[0] - m_in[0], -12.0, 12.0)) * wL,
     }
 
 
@@ -102,7 +129,9 @@ def apply_light(warped: np.ndarray, params) -> np.ndarray:
     lab_warp = cv2.cvtColor(warped, cv2.COLOR_BGR2LAB).astype(np.float64)
     m_in, s_in = params["m_in"], params["s_in"]
     m_out, s_out = params["m_out"], params["s_out"]
-    strength = params["strength"]
+    # The chroma weight. `colour` when the params came from the split path,
+    # `strength` for any dict built before it existed.
+    strength = float(params.get("colour", params["strength"]))
     out = lab_warp.copy()
     for c in (1, 2):
         moved = (lab_warp[:, :, c] - m_in[c]) * float(s_out[c] / s_in[c]) + m_out[c]
@@ -114,7 +143,8 @@ def apply_light(warped: np.ndarray, params) -> np.ndarray:
 
 
 def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
-                strength: float = DEFAULT_STRENGTH) -> np.ndarray:
+                strength: float = DEFAULT_STRENGTH,
+                light: float = None, colour: float = None) -> 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
@@ -127,7 +157,8 @@ def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
     # One implementation, two entry points: measuring and applying are the same
     # arithmetic whether it runs on a still or on frame 900 of a clip. Keeping a
     # second copy here is how the two paths would drift.
-    return apply_light(warped, light_params(photo, warped, mask, strength))
+    return apply_light(warped, light_params(photo, warped, mask, strength,
+                                            light=light, colour=colour))
 
 
 GRAIN_GATE = 20.0        # grey levels: above this a residual is an edge, not grain

package/scripts/ui.py

@@ -587,10 +587,32 @@ PREVIEW_WIDTH = 720
 PREVIEW_SECONDS = 6.0
 
 
+def _grade_args(b):
+    """The realism weights: one legacy value, and the two halves that split it.
+
+    `grade` stays the single master, and it is what every sidecar written
+    before 21 Sep 2026 carries. `grade_light` and `grade_colour` weight the two
+    halves separately when the page sends them; ABSENT means "same as grade",
+    which is precisely what makes an old sidecar replay byte for byte rather
+    than merely closely (grade.light_params does the same defaulting, and
+    test_grade.py pins the identity at four strengths).
+
+    The page sends all three: `grade` as max(light, colour), so every
+    downstream default keyed on `grade > 0` -- grain, chiefly -- still means
+    "is the realism pass doing anything at all".
+    """
+    gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+    gl = b.get("grade_light")
+    gc = b.get("grade_colour")
+    return (gr,
+            None if gl is None else float(gl),
+            None if gc is None else float(gc))
+
+
 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,
-                   grain_gain=1.0):
+                   grain_gain=1.0, grade_light=None, grade_colour=None):
     """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
@@ -610,7 +632,9 @@ 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, grain_gain=grain_gain,
+                               grade=gr, grade_light=grade_light,
+                               grade_colour=grade_colour,
+                               grain=grain, grain_gain=grain_gain,
                                preset=preset, fit_frame=fit_frame, progress=progress,
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
@@ -1303,7 +1327,7 @@ class Handler(BaseHTTPRequestHandler):
                                 else _fit_frame())
                 first = W.read_frame_at(spath, fit_frame)
                 radius_px = frac * first.shape[1]
-                gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                gr, gl, gc = _grade_args(b)
                 grain = bool(b.get("grain", gr > 0))
                 blend, reflection = _blend_args(b)
                 # Downscale the PHOTO and scale the quad with it, rather than
@@ -1344,7 +1368,9 @@ class Handler(BaseHTTPRequestHandler):
                                            fit_frame, max_frames),
                                      kwargs={"smoothing": _smoothing(b),
                                              "dof": _dof_args(b),
-                                             "grain_gain": _grain_gain(b)}).start()
+                                             "grain_gain": _grain_gain(b),
+                                             "grade_light": gl,
+                                             "grade_colour": gc}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1375,7 +1401,7 @@ class Handler(BaseHTTPRequestHandler):
                                 else _fit_frame())
                 first = W.read_frame_at(spath, fit_frame)
                 radius_px = frac * first.shape[1]
-                gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                gr, gl, gc = _grade_args(b)
                 grain = bool(b.get("grain", gr > 0))
                 blend, reflection = _blend_args(b)
                 dof = _dof_args(b)
@@ -1397,7 +1423,8 @@ 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, "grain_gain": _grain_gain(b),
+                          "grade": gr, "grade_light": gl, "grade_colour": gc,
+                          "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"],
@@ -1431,7 +1458,9 @@ class Handler(BaseHTTPRequestHandler):
                                            blend, reflection, result),
                                      kwargs={"smoothing": _smoothing(b),
                                              "dof": dof,
-                                             "grain_gain": result["grain_gain"]}).start()
+                                             "grain_gain": result["grain_gain"],
+                                             "grade_light": result["grade_light"],
+                                             "grade_colour": result["grade_colour"]}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1451,14 +1480,15 @@ class Handler(BaseHTTPRequestHandler):
                 # composite is the right output when the screenshot's own colour
                 # is the point (a brand review), and the grade is the right one
                 # when the photograph is (a portfolio shot).
-                gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                gr, gl, gc = _grade_args(b)
                 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)),
+                                grade=gr, grade_light=gl, grade_colour=gc,
+                                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"),
@@ -1494,7 +1524,8 @@ 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,
-                          "grade": gr, "grain": bool(b.get("grain", gr > 0)),
+                          "grade": gr, "grade_light": gl, "grade_colour": gc,
+                          "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"],

package/scripts/warp.py

@@ -366,10 +366,19 @@ class Plan:
                                    flags=cv2.INTER_LANCZOS4,
                                    borderMode=cv2.BORDER_REPLICATE)
 
-    def bind_grade(self, frame: np.ndarray, strength: float) -> None:
-        """Measure the light correction once, from the frame the user fitted on."""
+    def bind_grade(self, frame: np.ndarray, strength: float,
+                   light: float = None, colour: float = None) -> None:
+        """Measure the light correction once, from the frame the user fitted on.
+
+        `light` and `colour` weight the two halves separately (see
+        grade.light_params). Left unset they both fall back to `strength`,
+        which is what every sidecar written before the split carries.
+        """
+        wL = strength if light is None else light
+        wC = strength if colour is None else colour
         self.grade_params = _grade.light_params(
-            self.photo, self._prep(frame), self.warped_mask, strength) if strength > 0 else None
+            self.photo, self._prep(frame), self.warped_mask, strength,
+            light=light, colour=colour) if (wL > 0 or wC > 0) else None
 
     def _blend(self, photo_win, warped_win):
         """Emitted light over reflected light, or a plain replace.
@@ -444,7 +453,8 @@ class Plan:
 
 def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: float = 0.0,
             corner_smoothing: float = 0.0,
-            grade: float = 0.0, grain: bool = False, screen_off: np.ndarray = None,
+            grade: float = 0.0, grade_light: float = None, grade_colour: float = None,
+            grain: bool = False, screen_off: np.ndarray = None,
             specular: float = 0.75, blend: str = "replace",
             reflection: float = DEFAULT_REFLECTION,
             dof_angle: float = 0.0, dof_strength: float = 0.0,
@@ -467,7 +477,7 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
                 dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
                 grain_gain=grain_gain)
-    plan.bind_grade(screenshot, grade)
+    plan.bind_grade(screenshot, grade, light=grade_light, colour=grade_colour)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
 
@@ -549,7 +559,8 @@ def read_frame_at(path: str, index: int = 0):
 
 def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   corner_radius: float = 0.0, corner_smoothing: float = 0.0,
-                  grade: float = 0.0, grain: bool = False,
+                  grade: float = 0.0, grade_light: float = None,
+                  grade_colour: float = None, grain: bool = False,
                   preset: str = "web", fit_frame: int = 0, audio: bool = True,
                   frames_dir: str = None, progress=None, blend: str = "replace",
                   reflection: float = DEFAULT_REFLECTION,
@@ -588,9 +599,19 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
                 dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
                 grain_gain=grain_gain)
-    plan.bind_grade(first, grade)
+    plan.bind_grade(first, grade, light=grade_light, colour=grade_colour)
 
     ph, pw = photo.shape[:2]
+    # H.264/yuv420p (and ProRes 422) subsample chroma 2x horizontally, and
+    # 4:2:0 vertically too, so an odd width or height is refused -- and ffmpeg
+    # refuses by dying mid-stream, which reaches us as "[Errno 32] Broken pipe"
+    # on the first frame write. The preview route evened its own proxy size
+    # (ui.py) but a full render runs at the PHOTO's size, so any photograph
+    # with an odd dimension failed to render at all (1424x879, 25 Sep 2026).
+    # Pad by replicating the last row/column: one duplicated edge pixel is
+    # invisible, whereas cropping would drop a row of the photograph.
+    pad_b, pad_r = ph % 2, pw % 2
+    ph, pw = ph + pad_b, pw + pad_r
     cmd = [ffmpeg_exe(), "-y", "-loglevel", "error",
            "-f", "rawvideo", "-pix_fmt", "bgr24", "-s", f"{pw}x{ph}",
            "-r", f"{fps}", "-i", "-"]
@@ -632,7 +653,14 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
             if frames_dir:
                 cv2.imwrite(os.path.join(frames_dir, f"{count:06d}.png"), out,
                             [cv2.IMWRITE_PNG_COMPRESSION, 1])
-            proc.stdin.write(out.tobytes())
+            if pad_b or pad_r:
+                out = cv2.copyMakeBorder(out, 0, pad_b, 0, pad_r, cv2.BORDER_REPLICATE)
+            try:
+                proc.stdin.write(out.tobytes())
+            except BrokenPipeError:
+                # ffmpeg has exited; its stderr, read below, says why. Raising
+                # the bare pipe error here would hide the one useful sentence.
+                break
             count += 1
             if progress and count % 10 == 0:
                 progress(count, total_hint)

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.67):** 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** (the images you have used before, 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.68):** 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** (the images you have used before, 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 matches the source to the photo's light, with **Light** (exposure only, hue untouched) and **Colour** (white balance and saturation) set separately, **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".
 

package/ui/index.html

@@ -1527,6 +1527,14 @@
   /* The Keys legend. max-content on the first column sizes it to the widest
      cap, so every description starts on the same x and the caps form a single
      column the eye can run down. */
+  /* Realism's two rows. label | slider | value, so the two read as a pair of
+     the same control rather than two stacked blocks -- and it is shorter than
+     the single stacked slider it replaces, on a rail that has no room. */
+  .gr-row{display:grid;grid-template-columns:max-content 1fr max-content;
+          align-items:center;gap:var(--s2)}
+  .gr-row .gr-lbl{color:var(--mute)}
+  .gr-row output{color:var(--ink);font-variant-numeric:tabular-nums;min-width:34px;
+                 text-align:right;font-size:12px}
   dl.keys{display:grid;grid-template-columns:max-content 1fr;gap:6px 10px;
           margin:8px 0 0;align-items:baseline}
   dl.keys dt{color:var(--faint);font-size:12px;white-space:nowrap}
@@ -1702,16 +1710,30 @@
         <div class="sect-top">
           <div class="sect-left">
             <h4>Realism</h4>
-            <button class="info" type="button" aria-label="About realism"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path fill="currentColor" d="M8.36 1.01C12.06 1.2 15 4.26 15 8l-.01.36C14.8 12.06 11.74 15 8 15l-.36-.01C4.06 14.81 1.19 11.94 1.01 8.36L1 8c0-3.87 3.13-7 7-7l.36.01ZM8 2C4.69 2 2 4.69 2 8c0 3.31 2.69 6 6 6 3.31 0 6-2.69 6-6 0-3.31-2.69-6-6-6Zm.5 8l.5 0v1L7 11v-1h.5V7H7V6h1.5v4ZM7.9 4c.33 0 .6.27.6.6a.6.6 0 1 1-1.21 0c0-.33.28-.6.61-.6Z"/></svg><span class="tip" role="tooltip">Matches the screen's white balance and grain to the light around it, so it stops reading as pasted. Off keeps the screenshot's colour exactly — right when the UI's own colour is what you're reviewing. Grain is judged here at the preview's scale: the save carries about twice as much, which is what you get if you view the file at 100%.</span></button>
+            <button class="info" type="button" aria-label="About realism"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path fill="currentColor" d="M8.36 1.01C12.06 1.2 15 4.26 15 8l-.01.36C14.8 12.06 11.74 15 8 15l-.36-.01C4.06 14.81 1.19 11.94 1.01 8.36L1 8c0-3.87 3.13-7 7-7l.36.01ZM8 2C4.69 2 2 4.69 2 8c0 3.31 2.69 6 6 6 3.31 0 6-2.69 6-6 0-3.31-2.69-6-6-6Zm.5 8l.5 0v1L7 11v-1h.5V7H7V6h1.5v4ZM7.9 4c.33 0 .6.27.6.6a.6.6 0 1 1-1.21 0c0-.33.28-.6.61-.6Z"/></svg><span class="tip" role="tooltip">Sits the screen in the light around it, so it stops reading as pasted. <b>Light</b> matches the scene's exposure and leaves hue alone. <b>Colour</b> matches its white balance — this is the one that warms a brand colour, so set it to 0 when an exact hex is the point and keep Light. Off does both. Grain is judged here at the preview's scale: the save carries about twice as much, which is what you get if you view the file at 100%.</span></button>
           </div>
           <button class="switch" id="gradeBtn" role="switch" aria-checked="true" aria-label="Realism">
             <span class="sw-track"><span class="sw-handle"></span><span class="sw-grip"></span></span>
           </button>
         </div>
         <div class="sect-body"><div class="sect-body-in">
-          <div style="display:grid;gap:var(--s2);justify-items:end">
-            <span class="sm" id="gradeVal" style="font-variant-numeric:tabular-nums"></span>
-            <input type="range" id="gradeAmt" min="0.1" max="1" step="0.05" value="0.35" aria-label="Realism strength">
+          <!-- Two halves of one measurement, not two features. See
+               grade.light_params: Light is a bounded L shift, Colour is the
+               chroma match. Colour starts at 0 in neither -- both inherit
+               whatever single strength was remembered before the split. -->
+          <div style="display:grid;gap:var(--s3)">
+            <div class="gr-row">
+              <span class="sm gr-lbl">Light</span>
+              <input type="range" id="gradeLight" min="0" max="1" step="0.05" value="0.35"
+                     aria-label="Light — match the scene's exposure">
+              <output for="gradeLight" id="gradeLightVal"></output>
+            </div>
+            <div class="gr-row">
+              <span class="sm gr-lbl">Colour</span>
+              <input type="range" id="gradeColour" min="0" max="1" step="0.05" value="0.35"
+                     aria-label="Colour — match the scene's white balance">
+              <output for="gradeColour" id="gradeColourVal"></output>
+            </div>
           </div>
           </div></div>
       </div>
@@ -2306,15 +2328,26 @@ async function loadFitFile(file){
 }
 // Capture phase, so the per-role drop zones never see a fit file and try to
 // decode it as an image.
-addEventListener('dragover', e => {
-  if ([...(e.dataTransfer?.items || [])].some(i => i.kind === 'file')) e.preventDefault();
-}, true);
+// Is a file being dragged? Ask `types`, not `items`: Safari leaves `items`
+// empty during dragover, so an items-only test never cancelled the drag there,
+// the drop event never fired, and Safari navigated away to the dropped .json --
+// taking the whole workbench with it.
+function draggingFiles(e){
+  const dt = e.dataTransfer; if (!dt) return false;
+  if ([...(dt.types || [])].includes('Files')) return true;
+  return [...(dt.items || [])].some(i => i.kind === 'file');
+}
+addEventListener('dragover', e => { if (draggingFiles(e)) e.preventDefault(); }, true);
 addEventListener('drop', e => {
   const f = e.dataTransfer && e.dataTransfer.files && e.dataTransfer.files[0];
   if (!f || !/\.json$/i.test(f.name)) return;      // not ours: let the zones have it
   e.preventDefault(); e.stopPropagation();
   loadFitFile(f);
 }, true);
+// A file dropped where nothing takes it must not become a navigation: the page
+// is the session, and leaving it loses the fit. Bubble phase, so the zones and
+// the fit loader above have already had their turn.
+addEventListener('drop', e => { if (draggingFiles(e)) e.preventDefault(); });
 
 /* ===== pickers (popovers over the canvas) ===== */
 // "Used 3 h ago", "used yesterday" -- when a source was last chosen.
@@ -2511,7 +2544,7 @@ for (const [n, role] of [[1,'photo'],[2,'screenshot']]){
   // onto "Choose a photo" and it lands in that role without opening the
   // popover. Same upload path as the popover's drop zone.
   const chip = $('#chip'+n);
-  chip.ondragover = e => { if ([...(e.dataTransfer?.items || [])].some(i => i.kind === 'file')) { e.preventDefault(); chip.classList.add('over'); } };
+  chip.ondragover = e => { if (draggingFiles(e)) { e.preventDefault(); chip.classList.add('over'); } };
   // Leaving with a drag only un-lights the chip if its popover is not the
   // reason it is lit.
   const popOpen = () => $('#pop'+n).classList.contains('on');
@@ -3531,27 +3564,55 @@ function setSectionOpen(sect, on){
    colour exactly, which is what you want when the UI's colour is the thing under
    review. Strength is a slider because the right amount is a judgement about the
    photograph, not a constant. */
-let gradeOn  = recall('grade','1') === '1';
-let gradeAmt = parseFloat(recall('gradeAmt','0.35')) || 0.35;
-function gradeValue(){ return gradeOn ? gradeAmt : 0; }
+let gradeOn = recall('grade','1') === '1';
+/* One strength became two on 21 Sep 2026, and the reason is a real report: with
+   realism on, a brand orange visibly moved toward coral and a pure-black status
+   bar lifted to slate. Both are CORRECT -- nothing on a real phone renders #000
+   -- but one control was doing two jobs and the people using this check hex
+   values. The cut follows what grade.light_params already computes separately:
+
+     Light  -> a bounded mean shift on L. Sits the screen in the scene's
+               exposure and leaves hue alone (measured: d(a,b) 0.002).
+     Colour -> the chroma match, mean and spread. The half that warmed the
+               orange (measured: 12.98 against 0.00 with it off).
+
+   Anyone who had a strength saved keeps it: both halves inherit it, so the
+   first render after this ships is the one they had. */
+const _oldAmt = parseFloat(recall('gradeAmt','0.35')) || 0.35;
+let gLight  = parseFloat(recall('gradeLight',  String(_oldAmt)));
+let gColour = parseFloat(recall('gradeColour', String(_oldAmt)));
+if (!(gLight  >= 0)) gLight  = _oldAmt;
+if (!(gColour >= 0)) gColour = _oldAmt;
+/* The master value. Everything server-side that asks "is the realism pass doing
+   anything at all" -- grain, chiefly -- is keyed on `grade`, so it is the
+   larger of the two rather than either one. */
+function gradeValue(){ return gradeOn ? Math.max(gLight, gColour) : 0; }
+function gradeLightValue(){ return gradeOn ? gLight : 0; }
+function gradeColourValue(){ return gradeOn ? gColour : 0; }
 function paintGrade(){
-  setSwitch($('#gradeBtn'), gradeOn);          // hides the slider when off
-  $('#gradeVal').textContent = Math.round(gradeAmt * 100) + '%';
-  const sl = $('#gradeAmt');
-  sl.value = gradeAmt;
-  sl.style.setProperty('--p', (gradeAmt - 0.1) / 0.9);
+  setSwitch($('#gradeBtn'), gradeOn);          // hides the sliders when off
+  for (const [id, v] of [['gradeLight', gLight], ['gradeColour', gColour]]){
+    const sl = $('#' + id);
+    sl.value = v;
+    sl.style.setProperty('--p', v);            // span is 0-1 now, so no rescale
+    $('#' + id + 'Val').textContent = Math.round(v * 100) + '%';
+  }
 }
-function setGrade(on, amt){
+function setGrade(on){
   gradeOn = on;
-  if (amt !== undefined) gradeAmt = amt;
-  remember('grade', on ? '1' : '0'); remember('gradeAmt', String(gradeAmt));
+  remember('grade', on ? '1' : '0');
+  remember('gradeLight', String(gLight));
+  remember('gradeColour', String(gColour));
   paintGrade();
 }
 $('#gradeBtn').onclick = () => { setGrade(!gradeOn); autoPreview(); };
 // Repaint live while dragging, re-render only on release: a full compose per
 // input event would queue renders faster than they finish.
-$('#gradeAmt').oninput  = e => { gradeAmt = parseFloat(e.target.value); paintGrade(); };
-$('#gradeAmt').onchange = e => { setGrade(true, parseFloat(e.target.value)); autoPreview(); };
+for (const [id, set] of [['gradeLight',  v => gLight  = v],
+                         ['gradeColour', v => gColour = v]]){
+  $('#' + id).oninput  = e => { set(parseFloat(e.target.value)); paintGrade(); };
+  $('#' + id).onchange = e => { set(parseFloat(e.target.value)); setGrade(true); autoPreview(); };
+}
 
 /* Emissive screen. A display emits light AND reflects the room; `replace` models
    only the first, which is why a true-black UI lands as a hole. Off by default so
@@ -4334,6 +4395,8 @@ async function playClip(){
   try{
     await api('/api/preview_video', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen',
                                      device: st.type, grade: gradeValue(),
+                                     grade_light: gradeLightValue(),
+                                     grade_colour: gradeColourValue(),
                                      reflection: emisValue(), fit_frame: +$('#vframe').value});
   }catch(e){
     building = false;
@@ -4391,7 +4454,7 @@ async function renderPreview(){
   const say = t => { if (!building && $('#liveWrap').hidden) s.textContent = t; };
   say('Rendering…');
   try{
-    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen', device: st.type, grade: gradeValue(), reflection: emisValue()});
+    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen', device: st.type, grade: gradeValue(), grade_light: gradeLightValue(), grade_colour: gradeColourValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => {
       outNat = im.naturalWidth;
@@ -4524,7 +4587,9 @@ async function renderVideo(){
   setRenderProgress(0);
   try{
     await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen', device: st.type,
-                              grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
+                              grade: gradeValue(), grade_light: gradeLightValue(),
+                              grade_colour: gradeColourValue(),
+                              reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){
     setRenderProgress(null);
     toast('err','Could not start the render: '+e.message);
@@ -4569,7 +4634,7 @@ $('#save').onclick = async () => {
   if (st.video) return renderVideo();
   const b = $('#save'); b.textContent = 'Saving…'; b.disabled = true;
   try{
-    const r = await api('/api/save', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen', device: st.type, grade: gradeValue(), reflection: emisValue()});
+    const r = await api('/api/save', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_end2: dofEnd2V(), dof_space: 'screen', device: st.type, grade: gradeValue(), grade_light: gradeLightValue(), grade_colour: gradeColourValue(), reflection: emisValue()});
     b.textContent = saveLabel();
     // The real destination, not a hardcoded one: --out-dir means saves usually
     // land in the project folder now, and telling the user "~/Desktop" when
@@ -4658,7 +4723,10 @@ $('#imp').onclick = async () => {
   }
   setLoupeMode(loupeMode);
   setStripHC(stripHC);
-  setGrade(gradeOn, gradeAmt);
+  // One argument since the Light/Colour split: the two amounts are module
+  // state, already recalled above. Passing the old `gradeAmt` here threw a
+  // ReferenceError that killed the rest of boot.
+  setGrade(gradeOn);
   setEmis(emisOn, emisAmt);
   setDof(dofOn, dofAng, dofStr);
   setRadiusOn(radiusOn);