screengraft 0.13.1 → 0.17.0

package/README.md

@@ -2,9 +2,7 @@
 
 **Put a UI screenshot 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.13.1",
+  "version": "0.17.0",
   "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.",
   "keywords": [
     "mockup",

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/ui.py

@@ -322,12 +322,24 @@ class Handler(BaseHTTPRequestHandler):
             if u.path == "/api/detect":
                 photo, _ = _read_image(SESSION.state["photo"])
                 gray = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
-                res = D.detect(gray, None)
+                # `color` gives detect() the saturation detector — devices are
+                # neutral, furniture is not, and grayscale throws that away.
+                res = D.detect(gray, None, color=photo)
                 if res is None:
                     return self._json({"found": False,
                                        "message": "Neither detector could find a screen here "
                                                   "(nothing separable by tone, no screen-shaped "
                                                   "boundary). Place the four corners by hand."})
+                # An abstention is a miss, and must reach the page as one. On
+                # 7 Sep 2026 a quad on a table was shown as a checkable guess
+                # with two corners off the canvas, which cannot be dragged back
+                # — worse than no guess at all. detect() keeps the
+                # quad for inspection; the page gets the default rectangle.
+                if res.get("abstained"):
+                    return self._json({"found": False,
+                                       "message": res["abstain_reason"],
+                                       "abstained": True,
+                                       "inspect": res["corners"]})
                 res.pop("_corners_np", None)
                 res["found"] = True
                 # How much the page should trust this. Both detectors agreeing is

package/ui/index.html

@@ -714,6 +714,7 @@
         <span class="cvbar-actions">
           <span class="stepper"><button class="sm" data-jump="0">TL</button><button class="sm" data-jump="1">TR</button><button class="sm" data-jump="2">BR</button><button class="sm" data-jump="3">BL</button></span>
           <button class="sm" id="redetect">Re-detect</button>
+          <button class="sm" id="resetquad" title="Put the four edges back to a rectangle in the middle of the photo. Use this if a corner has ended up off the picture where you cannot grab it.">Reset</button>
         </span>
       </div>
     </section>
@@ -1336,16 +1337,37 @@ async function detect(){
     if (r.corner_radius && r.corner_radius.confident){ setFrac(r.corner_radius.frac_of_width, 'measured from the photo'); }
     else { applyPreset(); $('#radSt').textContent = 'Radius not measurable here — using the device preset.'; }
   } else {
-    const w = img.naturalWidth, h = img.naturalHeight;
-    st.corners = [[w*.3,h*.2],[w*.7,h*.2],[w*.7,h*.8],[w*.3,h*.8]];
-    s.className='status warn'; s.textContent = 'No screen found — place the edges by hand';
+    st.corners = defaultQuad();
+    s.className='status warn';
+    s.textContent = r.abstained ? 'Detector abstained — place the edges by hand'
+                                : 'No screen found — place the edges by hand';
+    // The full reason is long and belongs on hover, not in a 40-character chip.
+    s.title = r.message || '';
     if (!st.type) setType('phone'); applyPreset();
   }
   pick = {kind:'edge', i:0};
   draw(); drawStrip();
   autoPreview();   // if the compare pane is open, fill it straight away
 }
+// One definition of "a sane starting position", used by the abstention path and
+// by Reset. Deliberately a plain centred rectangle: it claims nothing about
+// where the screen is, and every handle is on the picture where it can be
+// grabbed — which is the property the detector's off-canvas quad lacked.
+function defaultQuad(){
+  const w = img.naturalWidth, h = img.naturalHeight;
+  return [[w*.3,h*.2],[w*.7,h*.2],[w*.7,h*.8],[w*.3,h*.8]];
+}
 $('#redetect').onclick = detect;
+$('#resetquad').onclick = () => {
+  if (!img.naturalWidth) return;
+  st.corners = defaultQuad();
+  const s = $('#detSt'); s.className='status warn';
+  s.textContent = 'Edges reset — place them on the screen';
+  s.title = '';
+  pick = {kind:'edge', i:0};
+  setCanvasZoom(scale);
+  draw(); drawStrip(); autoPreview();
+};
 
 function draw(){
   ctx.clearRect(0,0,cv.width,cv.height);