screengraft 0.13.1 → 0.20.4

package/README.md

@@ -1,10 +1,8 @@
 # screengraft
 
-**Put a UI screenshot onto a photographed screen so the perspective is exactly right.**
+**Put a UI screenshot — or a screen recording — onto a photographed screen so the perspective is exactly right.**
 
-![A Figma screen composited onto a photographed iPhone](docs/hero.png)
-
-![The fitting workbench: photo with the screen quad on the left, live composite on the right, and a magnified strip across the edge below](docs/social-preview.png)
+![The fitting workbench: photo with the screen quad on the left, live composite on the right, and a magnified strip across the edge below](docs/workbench.png)
 
 Every device mockup is a compromise. Templates give you three angles and someone
 else's lighting. Generative tools give you a screen that looks *like* your design
@@ -15,6 +13,9 @@ transform between them. The screenshot lands on the glass because the geometry
 says it must, not because a model thought it looked about right. Same inputs,
 same output, every time.
 
+Point it at a **video** instead and the same fit renders every frame: record a
+prototype, then put the recording inside a real photograph.
+
 ---
 
 ## What it does
@@ -28,6 +29,10 @@ same output, every time.
 - **Realism pass** *(optional)* — matches the screen's white balance and grain to
   the light in the room, and can lift the device's real reflections from a
   screen-off frame of the same shot.
+- **Video, not just stills.** The screen source can be an `mp4`/`mov`/`webm`.
+  You match the edges on one frame and every frame gets that same geometry — the
+  photograph is still, so there is nothing to track and nothing to drift. Output
+  is H.264 at CRF 16 or ProRes 422 HQ.
 - **You confirm every fit.** Detection is advisory and says so; you drag the four
   edges onto the glass with a magnified loupe. A silent misdetection producing a
   confident, wrong result is the one failure this tool refuses to have.
@@ -38,6 +43,10 @@ same output, every time.
 without it. The installer provisions an isolated venv at `~/.screengraft/venv`
 and never touches your system Python.
 
+Video rendering also uses **ffmpeg**, which arrives as a wheel (`imageio-ffmpeg`)
+into that same venv — nothing is installed system-wide. It is optional: without
+it, stills work exactly as before.
+
 ## Install as a Claude Code / Cowork plugin
 
 ```
@@ -106,15 +115,31 @@ outside the screen mask. It never touches the pixels you designed.
 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.
+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:
+   the light match is measured **once** from the frame you fitted on, so the
+   screen cannot pulse as your UI scrolls from dark to light; the grain stays
+   frozen, because the photograph's own noise does not move; and the screen's
+   antialiased **edge is pixel-identical in every frame**, so there is no edge
+   crawl. Frame 0 of a render is byte-identical to the still composite — the
+   test suite asserts it, because that is what stops the two paths drifting.
 
 ## Roadmap
 
-Done: manual warp, advisory detectors, the fitting workbench, the realism pass.
+Done: manual warp, advisory detectors, the fitting workbench, the realism pass,
+video into a still photo.
+
+Open: **camera-motion tracking** — the photograph itself must currently be a
+still, so a clip of a moving phone is out of scope; **SAM 2 auto-detect** (built
+and measured in a separate repo; it segments the phone body rather than the
+glass, so it is not shipped); **occluder matte**, so a finger in front of the
+screen stays in front.
 
-Open: video tracking (M3), SAM 2 auto-detect (M4 — built and measured in a
-separate repo; it currently segments the phone body rather than the glass, so it
-is not shipped), occluder matte (M5), so a finger in front of the screen stays in
-front.
+Known limits worth stating plainly: detection abstains rather than guessing when
+the background is itself neutral (a pale tiled floor, a plain wall) — you place
+the edges by hand there. And a prototype recording has no motion blur, so a very
+fast scroll will strobe; that is a property of the source, not of the composite.
 
 ## Contributing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "screengraft",
-  "version": "0.13.1",
-  "description": "Put a UI screenshot onto a photographed device screen with the perspective exactly right \u2014 a homography you confirm by hand, not a generative guess.",
+  "version": "0.20.4",
+  "description": "Put a UI screenshot or screen recording onto a photographed device screen with the perspective exactly right — a homography you confirm by hand, not a generative guess.",
   "keywords": [
     "mockup",
     "device-frame",
@@ -9,6 +9,9 @@
     "perspective",
     "compositing",
     "screenshot",
+    "prototype",
+    "screen-recording",
+    "video",
     "design",
     "portfolio",
     "figma"

package/scripts/detect.py

@@ -54,6 +54,62 @@ MIN_AREA_FRAC = 0.01
 MAX_AREA_FRAC = 0.60
 MIN_FILL = 0.60      # the source blob must fill this much of the final quad
 MIN_SIDE_RATIO = 0.08  # reject slivers: shortest side vs longest, after perspective
+# Size stops being a virtue past this fraction of the frame. score_contour used
+# to reward area linearly, so on a real photo (7 Sep 2026) the sunlit TABLE at
+# 34% of the frame beat the phone screen at 9% by 3.6x on that term alone, and
+# won outright. A screen is never the biggest thing in a photograph of a room;
+# it is only ever big enough. Past this plateau extra area buys nothing, so
+# candidates separate on fill and band width instead — which is what actually
+# distinguishes glass from furniture.
+AREA_PLATEAU = 0.15
+# How many connected components each tone band offers up. See blobs_for_band:
+# taking only the largest is what made a real photo undetectable, because the
+# phone was the second-largest dark region in its band. Six is measured, not
+# guessed — the winning component on that photo is rank 2, and nothing useful
+# was found past rank 4 on any fixture; the extra two are headroom.
+COMPONENTS_PER_BAND = 6
+# Saturation percentile below which a region counts as "neutral". Devices are
+# grey, black and white; furniture, skin, fabric and foliage are not. Measured
+# 7 Sep 2026 on a photo where tone banding failed completely: the screen sits at
+# saturation 1.9, the sunlit table it was being confused with at 78.6. Taking
+# the image's own 25th percentile adapts to the photograph instead of fixing a
+# level — a studio shot on white and a warm interior need different numbers.
+# Swept, not fixed — the same reasoning the tone sweep is built on. A single
+# percentile breaks whenever the neutral thing is smaller than the percentile
+# (a phone occupying 15% of a colourful frame pulls p25 up into the colour and
+# the mask swallows the picture). Trying several and letting the scoring decide
+# costs one pass each and removes the guess.
+NEUTRAL_PERCENTILES = (5, 10, 15, 25, 35)
+NEUTRAL_FLOOR = 20          # never threshold below this: an all-grey photo
+# A screen has rounded corners. A patch of table cut out by a threshold has
+# perfectly sharp ones, and measure_corner_radius returns 0.0px for it — which
+# turns out to be the cleanest way to tell a real screen from a lookalike, and
+# it is a SHAPE property, not photometry (three photometric arbiters have been
+# measured and rejected here; see the note above score_edge_contour).
+MIN_ROUNDING_PX = 2.0
+# measure_corner_radius makes FOUR independent estimates of one number. If they
+# disagree by more than this, the outline is not a rounded rectangle with a
+# consistent radius and the median is meaningless — so "it has rounded corners"
+# is not evidence and must not be treated as any. Measured 7 Sep 2026 across
+# nine real mockup photos: the seven correct detections spread 31-173%, the two
+# confidently-wrong ones 247% and 464%.
+#
+# **This is the weakest number in the file.** 173 against 247 is a 1.4x margin
+# on nine samples, where every other threshold here was set with a 4x margin or
+# better. If a correct detection is ever rejected as "shape is not consistent",
+# this is the line to raise, and it should be re-measured on a bigger set before
+# it is trusted further.
+MAX_RADIUS_SPREAD = 2.0
+# A quad with a corner outside the frame is not a screen this tool can fit, and
+# its handles cannot be grabbed — the user is left with a wrong quad and no way
+# back (same photo: two corners at y=-50 and y=1837 on a 1792-tall image).
+# Rejected at validate_quad, the one choke point every result passes through.
+OOB_MARGIN = 2.0
+# Gross disagreement between the two detectors, as a fraction of the image
+# diagonal. Measured 7 Sep 2026: the reference photo, where detection genuinely
+# works, sits at 0.033; the photo where both detectors missed the screen
+# entirely sits at 0.555 — seventeen times worse. 0.15 is well clear of both.
+ABSTAIN_GAP = 0.15
 # A screen fills MOST of the body it sits in; content drawn on a screen is a
 # small part of it. That one ratio separates "step inward to the screen" from
 # "don't step into a panel", and it arbitrates between the two detectors too.
@@ -65,8 +121,24 @@ def _odd(n: int) -> int:
     return n if n % 2 else n + 1
 
 
-def blob_for_band(gray: np.ndarray, lo: int, hi: int, close_k: int, open_k: int):
-    """Mask -> morphology -> largest connected component. Returns its contour."""
+def blobs_for_band(gray: np.ndarray, lo: int, hi: int, close_k: int, open_k: int,
+                   keep: int = COMPONENTS_PER_BAND):
+    """Mask -> morphology -> the `keep` largest connected components.
+
+    Returns a list of contours, biggest first.
+
+    This used to return only the single largest component, and that one line
+    was why a real photo could not be detected at all. On an iPhone lying on a
+    sunlit table (7 Sep 2026) the phone was the SECOND-largest dark region in
+    its band — the table's shadow was bigger — so the screen was discarded
+    before scoring ever saw it. No amount of re-scoring can rank a candidate
+    that was never generated: measured, the best quad the old sweep could
+    produce sat 693px from the true screen; keeping the runners-up brings that
+    to 136px, which is a startable position.
+
+    "Largest" is a guess about the answer dressed up as an optimisation. The
+    scoring function is what decides; this function's job is only to offer.
+    """
     mask = cv2.inRange(gray, lo, hi)
     mask = cv2.morphologyEx(
         mask, cv2.MORPH_CLOSE,
@@ -81,8 +153,19 @@ def blob_for_band(gray: np.ndarray, lo: int, hi: int, close_k: int, open_k: int)
     # leaves fitLine with nothing to fit.
     contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
     if not contours:
-        return None
-    return max(contours, key=cv2.contourArea)
+        return []
+    return sorted(contours, key=cv2.contourArea, reverse=True)[:keep]
+
+
+def size_term(area: float, img_area: float) -> float:
+    """Area reward that saturates at AREA_PLATEAU.
+
+    Below the plateau, bigger is better — it separates a real region from
+    speckle. At or above it, the term is 1.0 and stops discriminating, because
+    beyond a plausible screen size "bigger" stops being evidence of screen-ness
+    and starts being evidence of furniture.
+    """
+    return min(area / img_area, AREA_PLATEAU) / AREA_PLATEAU
 
 
 def score_contour(contour, img_area: float):
@@ -99,7 +182,7 @@ def score_contour(contour, img_area: float):
     # Fill ratio: a real screen fills its own quad almost completely. A shadow
     # or a wall patch is ragged and fills far less.
     fill = min(area / quad_area, 1.0)
-    return (fill ** 3) * (area / img_area), quad
+    return (fill ** 3) * size_term(area, img_area), quad
 
 
 # Two "edge support" arbiters — score each candidate quad by how much of its
@@ -140,7 +223,7 @@ def score_edge_contour(contour, img_area: float):
     if quad_area < MIN_AREA_FRAC * img_area or quad_area > MAX_AREA_FRAC * img_area:
         return 0.0, None
     fill = min(float(cv2.contourArea(contour)) / max(quad_area, 1e-6), 1.0)
-    return fill * (quad_area / img_area), quad
+    return fill * size_term(quad_area, img_area), quad
 
 
 def approx_quad(contour):
@@ -365,7 +448,7 @@ def measure_corner_radius(contour, corners: np.ndarray):
 # segmented contour, so it isn't picking between competing nearby edges.
 
 
-def validate_quad(corners: np.ndarray, contour, img_area: float):
+def validate_quad(corners: np.ndarray, contour, img_area: float, img_shape=None):
     """Is this *final* quad plausibly a screen? Returns (ok, reason).
 
     The area gate in score_contour() runs against the CONTOUR, before
@@ -375,6 +458,15 @@ def validate_quad(corners: np.ndarray, contour, img_area: float):
     confident detection (3 Sep 2026, an earlier finding). Everything returned to a caller
     goes through here.
     """
+    if img_shape is not None:
+        h, w = float(img_shape[0]), float(img_shape[1])
+        for (x, y), label in zip(corners, ["TL", "TR", "BR", "BL"], strict=True):
+            if not (-OOB_MARGIN <= x <= w + OOB_MARGIN
+                    and -OOB_MARGIN <= y <= h + OOB_MARGIN):
+                return False, ("%s lands outside the photo at (%.0f, %.0f) on a "
+                               "%.0fx%.0f image — a screen this tool can fit is "
+                               "inside the frame, and an off-canvas handle can't "
+                               "be dragged back" % (label, x, y, w, h))
     area = float(cv2.contourArea(corners.astype(np.float32)))
     frac = area / img_area
     if frac < MIN_AREA_FRAC:
@@ -398,7 +490,7 @@ def validate_quad(corners: np.ndarray, contour, img_area: float):
     return True, ""
 
 
-def _finalize(candidates, img_area: float, refine: bool = True):
+def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None):
     """Best candidate that survives refinement AND validation.
 
     Walks candidates best-score-first rather than trusting the top one: a
@@ -422,7 +514,7 @@ def _finalize(candidates, img_area: float, refine: bool = True):
         else:
             refined, did_refine = quad, False
         corners = order_quad(refined)
-        ok, why = validate_quad(corners, contour, img_area)
+        ok, why = validate_quad(corners, contour, img_area, img_shape)
         if ok:
             return {
                 "corners": [[round(float(x), 1), round(float(y), 1)] for x, y in corners],
@@ -456,11 +548,10 @@ def detect_tone(gray: np.ndarray, tone=None):
 
     candidates = []
     for lo, hi in bands:
-        contour = blob_for_band(gray, lo, hi, close_k, open_k)
-        if contour is None:
-            continue
-        score, quad = score_contour(contour, img_area)
-        if score > 0 and quad is not None:
+        for contour in blobs_for_band(gray, lo, hi, close_k, open_k):
+            score, quad = score_contour(contour, img_area)
+            if score <= 0 or quad is None:
+                continue
             # Prefer a narrow band. A screen is tonally uniform; a band wide
             # enough to also swallow the phone's shadowed body scores well on
             # area but produces edges that follow the body, not the glass.
@@ -469,7 +560,7 @@ def detect_tone(gray: np.ndarray, tone=None):
             score *= (16.0 / (hi - lo + 1)) ** 0.25
             candidates.append((score, order_quad(quad), contour, (lo, hi)))
 
-    res = _finalize(candidates, img_area)
+    res = _finalize(candidates, img_area, img_shape=gray.shape[:2])
     if res is None:
         return None
     band = res.pop("_tag")
@@ -517,7 +608,7 @@ def detect_edges(gray: np.ndarray):
             if score > 0 and quad is not None:
                 candidates.append((score, order_quad(quad), c, (lo, hi)))
 
-    res = _finalize(candidates, img_area, refine=False)
+    res = _finalize(candidates, img_area, refine=False, img_shape=gray.shape[:2])
     if res is None:
         return None
     thr = res.pop("_tag")
@@ -526,7 +617,71 @@ def detect_edges(gray: np.ndarray):
     return res
 
 
-def detect(gray: np.ndarray, tone=None, method="auto"):
+def detect_saturation(bgr: np.ndarray):
+    """Neutral-region segmentation — the third detector, and the only one that
+    looks at colour.
+
+    tone and edge both run on grayscale, which throws away the single most
+    useful cue a photograph of a device offers: **devices are neutral.** A
+    phone is grey, black or white; the table, sofa, hand or plant it is lying
+    on almost never is. On the 7 Sep 2026 photo the screen measured saturation
+    1.9 against the sunlit table's 78.6, and this detector lands 29px from the
+    true quad where tone lands 1030px away.
+
+    The threshold is the image's own 25th saturation percentile rather than a
+    fixed level, so a studio shot on white and a warm interior both work.
+    """
+    hsv = cv2.cvtColor(bgr, cv2.COLOR_BGR2HSV)
+    sat = hsv[:, :, 1]
+    h, w = sat.shape[:2]
+    img_area = float(h * w)
+    short = min(h, w)
+    close_k = _odd(CLOSE_FRAC * short)
+    open_k = _odd(OPEN_FRAC * short)
+
+    thresholds = {int(max(NEUTRAL_FLOOR, np.percentile(sat, p)))
+                  for p in NEUTRAL_PERCENTILES}
+    otsu, _ = cv2.threshold(sat, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    thresholds.add(int(max(NEUTRAL_FLOOR, otsu)))
+    candidates = []
+    for thr in sorted(thresholds):
+        for contour in blobs_for_band(sat, 0, thr, close_k, open_k):
+            score, quad = score_contour(contour, img_area)
+            if score > 0 and quad is not None:
+                # Prefer a tighter neutral threshold, for the same reason the
+                # tone sweep prefers a narrow band: a loose one swallows the
+                # device body and the wall behind it along with the screen.
+                candidates.append((score * (32.0 / max(thr, 1)) ** 0.25,
+                                   order_quad(quad), contour, thr))
+
+    res = _finalize(candidates, img_area, img_shape=sat.shape[:2])
+    if res is None:
+        return None
+    res.pop("_tag")
+    res["method"] = "saturation"
+    res["neutral_threshold"] = thr
+    return res
+
+
+def has_rounded_corners(result) -> bool:
+    """Did this quad's own outline actually curve at the corners?
+
+    A device screen is a rounded rectangle. A patch of table cut out of a
+    threshold mask is a polygon with sharp corners, and measure_corner_radius
+    reports 0.0px for it. That single number separated the right answer from
+    three wrong ones on the photo this was built for, and unlike edge strength
+    or ring contrast it is a property of the shape rather than of the light.
+    """
+    cr = result["corner_radius"]
+    if float(cr["photo_px"]) <= MIN_ROUNDING_PX:
+        return False
+    per = [float(v) for v in cr["per_corner_px"]]
+    r = float(cr["photo_px"])
+    spread = (max(per) - min(per)) / max(r, 1e-6)
+    return spread <= MAX_RADIUS_SPREAD
+
+
+def detect(gray: np.ndarray, tone=None, method="auto", color=None):
     """Run both detectors; arbitrate on how the two quads nest.
 
     The two fail on opposite things. Tone banding needs a tonally uniform
@@ -559,13 +714,40 @@ def detect(gray: np.ndarray, tone=None, method="auto"):
         r = detect_edges(gray)
         if r:
             results.append(r)
+    if method in ("auto", "saturation") and tone is None and color is not None:
+        r = detect_saturation(color)
+        if r:
+            results.append(r)
 
     if not results:
         return None
 
+    # tone and saturation are the same algorithm on different channels, so they
+    # are compared to each other before anything else, on whether the region
+    # each found actually has rounded corners. A patch of table cut out of a
+    # threshold mask measures 0.0px; a screen measures a real radius. On the
+    # 7 Sep photo that is the whole ball game — tone 0.0px against saturation's
+    # 62.4px, so the channel that found the phone is the one that goes forward.
+    #
+    # **Only these two.** The edge detector is deliberately exempt: its contour
+    # is a Canny ring tracing both sides of a boundary, not a filled region's
+    # silhouette, so measure_corner_radius reports an artifact for it — 0.0px
+    # even when its quad is the correct one to 1.4px (measured on the
+    # gradient-screen fixture, where an earlier version of this filter threw
+    # away the right answer). _finalize already skips corner refinement on that
+    # path for the same reason.
+    region = [r for r in results if r["method"] in ("tone", "saturation")]
+    if len(region) == 2:
+        rounded = [r for r in region if has_rounded_corners(r)]
+        if len(rounded) == 1:
+            loser = next(r for r in region if r is not rounded[0])
+            results = [r for r in results if r is not loser]
+
     t = next((r for r in results if r["method"] == "tone"), None)
     e = next((r for r in results if r["method"] == "edge"), None)
-    why = ""
+    sat = next((r for r in results if r["method"] == "saturation"), None)
+    why = "it was the only detector left after the rounded-corner filter" \
+        if len(results) == 1 else "it is the detector that refines corners"
     if t and e:
         tq, eq = t["_corners_np"], e["_corners_np"]
         ta = float(cv2.contourArea(tq.astype(np.float32)))
@@ -581,28 +763,46 @@ def detect(gray: np.ndarray, tone=None, method="auto"):
                             "its area — a screen inside a device body" % (ratio * 100))
         else:
             best, why = t, "the two quads aren't nested; the tone detector refines corners"
+    elif t is None and sat is not None:
+        # tone was dropped for having sharp corners, or never fired. The
+        # surviving region detector refines corners; edge does not.
+        best, why = sat, ("the saturation detector found a region with rounded "
+                          "corners where tone did not")
     else:
-        best = t or e
-
-    if len(results) == 2:
-        a, b = (r["_corners_np"] for r in results)
+        best = t or e or sat
+    if best is None:
+        best = results[0]
+
+    if len(results) > 1:
+        # Agreement is measured against the CLOSEST other detector, not against
+        # "the other one" — there are three now, and a third opinion that lands
+        # somewhere else entirely should not erase the fact that two of them
+        # landed together. Corroboration by any one independent method is the
+        # evidence worth reporting.
         diag = float(np.hypot(*gray.shape[:2]))
-        spread = float(np.max(np.linalg.norm(a - b, axis=1))) / diag
+        others = [r for r in results if r is not best]
+        gaps = [(float(np.max(np.linalg.norm(best["_corners_np"]
+                                             - r["_corners_np"], axis=1))) / diag, r)
+                for r in others]
+        spread, nearest = min(gaps, key=lambda g: g[0])
         agree = bool(spread < 0.02)
         best["agreement"] = {
             "both_found": True,
             "max_corner_gap_frac_of_diagonal": round(spread, 4),
             "agree": agree,
-            "note": ("Both detectors independently landed on the same quad — "
-                     "that is real evidence, not one algorithm's opinion."
+            "agrees_with": nearest["method"] if agree else None,
+            "note": ("The %s and %s detectors independently landed on the same "
+                     "quad — that is real evidence, not one algorithm's opinion."
+                     % (best["method"], nearest["method"])
                      if agree else
-                     "The two detectors disagree by %.0f%% of the image diagonal. "
-                     "Showing the %s one because %s — but check all four corners."
-                     % (spread * 100, best["method"], why)),
+                     "No two detectors agree; the closest other (%s) is %.0f%% of "
+                     "the image diagonal away. Showing the %s one because %s — "
+                     "but check all four corners."
+                     % (nearest["method"], spread * 100, best["method"], why)),
         }
         best["agreement"]["chosen_because"] = why
-        other = next(r for r in results if r is not best)
-        best["other"] = {"method": other["method"], "corners": other["corners"]}
+        best["other"] = [{"method": r["method"], "corners": r["corners"]}
+                         for r in others]
     else:
         best["agreement"] = {
             "both_found": False,
@@ -610,6 +810,57 @@ def detect(gray: np.ndarray, tone=None, method="auto"):
             "note": ("Only the %s detector found anything — a first guess to "
                      "correct, not a measurement." % best["method"]),
         }
+
+    # Abstention. detect.py has always PROMISED to fail honestly rather than
+    # emit a confident wrong quad, but nothing enforced it: on 7 Sep 2026 a real
+    # photo produced a quad on the table, with `agree` false, the two detectors
+    # 55% of the diagonal apart, the radius spread at 104%, and two corners off
+    # the image — every indicator of failure present, and a result returned
+    # anyway, exit 0. The evidence was already being computed; it just wasn't
+    # gating. Two conditions, either of which means "we do not know":
+    ag = best["agreement"]
+    # Disagreement only counts against a CREDIBLE peer. Measured 7 Sep 2026 on
+    # eight real mockup photos: where saturation correctly found a phone that
+    # tone and edge had both missed, the winner was of course miles from the two
+    # that failed — and this gate then threw the right answer away as
+    # "disagreement". A detector that found a sharp-cornered patch of floor does
+    # not get a vote on whether the rounded thing is a screen. So the gap is
+    # re-measured against peers that also found something screen-shaped; when
+    # there are none, being alone is not evidence of being wrong.
+    peers = [r for r in results if r is not best and has_rounded_corners(r)]
+    if peers:
+        diag = float(np.hypot(*gray.shape[:2]))
+        peer_gap = min(float(np.max(np.linalg.norm(best["_corners_np"]
+                                                   - r["_corners_np"], axis=1))) / diag
+                       for r in peers)
+    else:
+        peer_gap = None
+    gross = bool(peer_gap is not None and peer_gap > ABSTAIN_GAP)
+    if peer_gap is not None:
+        ag["credible_peer_gap"] = round(peer_gap, 4)
+    # A measurable corner radius counts as evidence in its own right: it says
+    # the thing found is shaped like a screen, which is what abstention exists
+    # to doubt. Without this a good saturation result on a hard photo would be
+    # thrown away for want of a second opinion.
+    uncorroborated = bool(not ag.get("agree")
+                          and not best["corner_radius"]["confident"]
+                          and not has_rounded_corners(best))
+    if gross or uncorroborated:
+        why = []
+        if gross:
+            why.append("two detectors that each found something screen-shaped are "
+                       "%.0f%% of the image diagonal apart" % (peer_gap * 100))
+        if uncorroborated:
+            why.append("nothing corroborates the quad (the detectors don't agree "
+                       "and the corner radius isn't measurable)")
+        best["abstained"] = True
+        best["abstain_reason"] = (
+            "Detection abstained: " + " and ".join(why) + ". The quad below is "
+            "kept for inspection but is not offered as a starting position — "
+            "place the four edges by hand."
+        )
+    else:
+        best["abstained"] = False
     return best
 
 
@@ -655,6 +906,8 @@ def main() -> None:
     if args.out_zooms:
         written["zooms"] = write_zooms(photo, corners, args.out_zooms)
 
+    if result.get("abstained"):
+        print(result["abstain_reason"], file=sys.stderr)
     print(json.dumps({
         **result,
         "photo_size": [photo.shape[1], photo.shape[0]],
@@ -672,6 +925,12 @@ def main() -> None:
                 "this script, so an unconfirmed guess cannot reach a composite.",
     }, indent=1))
 
+    # The docstring's promise, finally enforced: an uncorroborated guess exits
+    # non-zero. The JSON is still printed above so a caller can inspect what was
+    # rejected and why.
+    if result.get("abstained"):
+        sys.exit(2)
+
 
 if __name__ == "__main__":
     main()

package/scripts/grade.py

@@ -61,48 +61,75 @@ def _stats(lab: np.ndarray, sel: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
     return px.mean(axis=0), px.std(axis=0) + 1e-6
 
 
-def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
-                strength: float = DEFAULT_STRENGTH) -> np.ndarray:
-    """Move the injected screen's cast and exposure toward the surrounding light.
-
-    Chroma (a,b) is matched on mean AND spread — a cast is exactly a chroma mean
-    offset, and a room with weak colour should not receive a saturated screen.
-    Luminance is matched on MEAN ONLY, and bounded: a screen is emissive and is
-    allowed to be brighter than its surroundings, so rescaling its L spread to
-    the bezel's would crush the UI's own contrast. That asymmetry is the whole
-    design of this function.
+def light_params(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
+                 strength: float = DEFAULT_STRENGTH):
+    """Measure the correction ONCE, so it can be applied to many frames.
+
+    Split out of match_light for video. The correction depends on the
+    screen's own content through `m_in`/`s_in`, so measuring it per frame makes
+    it drift as the UI scrolls from a dark screen to a light one — the injected
+    screen would visibly pulse. Deriving the parameters from one frame and
+    applying the identical transform to all of them is the whole fix.
+
+    Returns None when there is too little context to measure honestly, which
+    the caller must treat as "leave the frame alone".
     """
     if strength <= 0:
-        return warped
+        return None
     ring = surround_ring(mask)
-    if int(ring.sum()) < 500:          # too little context to measure honestly
-        return warped
-
-    lab_photo = cv2.cvtColor(photo, cv2.COLOR_BGR2LAB).astype(np.float64)
-    lab_warp = cv2.cvtColor(warped, cv2.COLOR_BGR2LAB).astype(np.float64)
+    if int(ring.sum()) < 500:
+        return None
     inside = (mask > 200).astype(np.uint8)
     if int(inside.sum()) < 500:
-        return warped
-
+        return None
+    lab_photo = cv2.cvtColor(photo, cv2.COLOR_BGR2LAB).astype(np.float64)
+    lab_warp = cv2.cvtColor(warped, cv2.COLOR_BGR2LAB).astype(np.float64)
     m_out, s_out = _stats(lab_photo, ring)
     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),
+        # 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),
+    }
+
+
+def apply_light(warped: np.ndarray, params) -> np.ndarray:
+    """Apply parameters from light_params() to one frame."""
+    if params is None:
+        return warped
+    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"]
     out = lab_warp.copy()
-    # a,b: full Reinhard transfer, scaled by strength.
     for c in (1, 2):
         moved = (lab_warp[:, :, c] - m_in[c]) * float(s_out[c] / s_in[c]) + m_out[c]
         out[:, :, c] = lab_warp[:, :, c] + (moved - lab_warp[:, :, c]) * strength
-    # L: mean shift only, and capped at +-12 L* so a dark room cannot switch
-    # the screen off. 12 is about a stop; beyond that it stops reading as the
-    # same screenshot.
-    dL = float(np.clip(m_out[0] - m_in[0], -12.0, 12.0)) * strength
-    out[:, :, 0] = lab_warp[:, :, 0] + dL
-
+    out[:, :, 0] = lab_warp[:, :, 0] + params["dL"]
     out[:, :, 0] = np.clip(out[:, :, 0], 0, 255)
     out[:, :, 1:] = np.clip(out[:, :, 1:], 0, 255)
     return cv2.cvtColor(out.astype(np.uint8), cv2.COLOR_LAB2BGR)
 
 
+def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
+                strength: float = DEFAULT_STRENGTH) -> np.ndarray:
+    """Move the injected screen's cast and exposure toward the surrounding light.
+
+    Chroma (a,b) is matched on mean AND spread — a cast is exactly a chroma mean
+    offset, and a room with weak colour should not receive a saturated screen.
+    Luminance is matched on MEAN ONLY, and bounded: a screen is emissive and is
+    allowed to be brighter than its surroundings, so rescaling its L spread to
+    the bezel's would crush the UI's own contrast. That asymmetry is the whole
+    design of this function.
+    """
+    # 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))
+
+
 def measure_grain(photo: np.ndarray, ring: np.ndarray) -> float:
     """The photo's noise floor, in grey levels, measured where the screen isn't.