screengraft 0.66.0 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.66.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
@@ -1077,6 +1101,35 @@ class Handler(BaseHTTPRequestHandler):
                 except RenderBusy as exc:
                     return self._json({"error": str(exc)}, 409)
 
+            if u.path == "/api/reveal":
+                # Show a saved file in the desktop's file manager. The PAGE
+                # cannot do this -- a browser will not open a Finder window
+                # from an http origin -- and this server is the half of
+                # screengraft that runs on the user's machine, so it is the
+                # only thing that can.
+                #
+                # _safe_local_path is the whole security story and it already
+                # guards /file: it expands ~, resolves symlinks, refuses any
+                # path outside HOME, and requires a file that exists. The
+                # command is an argument LIST handed to the OS, never a string
+                # through a shell, so a path cannot become an argument or a
+                # second command however it is spelled.
+                try:
+                    p = _safe_local_path(b.get("path") or "")
+                except (PermissionError, FileNotFoundError, TypeError) as exc:
+                    return self._json({"error": str(exc)}, 400)
+                if sys.platform == "darwin":
+                    cmd = ["open", "-R", p]            # reveals AND selects it
+                elif os.name == "nt":
+                    cmd = ["explorer", "/select,", p]  # exits 1 even on success
+                else:
+                    cmd = ["xdg-open", os.path.dirname(p)]
+                try:
+                    subprocess.run(cmd, capture_output=True, timeout=10, check=False)
+                except (OSError, subprocess.SubprocessError) as exc:
+                    return self._json({"error": f"could not open the folder: {exc}"}, 500)
+                return self._json({"ok": True})
+
             if u.path == "/api/figma":
                 return self._json(SESSION.enqueue({
                     "type": "figma_export", "url": b["url"],
@@ -1274,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
@@ -1315,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")
@@ -1346,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)
@@ -1368,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"],
@@ -1402,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.
@@ -1422,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"),
@@ -1465,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.66):** 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".