screengraft 0.25.1 → 0.37.0

package/README.md

@@ -38,6 +38,22 @@ prototype, then put the recording inside a real photograph.
   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.
+- **Watch it before you render it.** Press Play and the clip runs on the photo
+  immediately — the browser warps it onto the same four corners, with the same
+  corner radius, and approximates the emissive blend. Nothing to wait for, and
+  it follows the quad while you drag. **Render preview** composites a few
+  seconds through the real pipeline for when the grade, the grain and the true
+  blend are what you need to judge.
+- **It remembers a photograph.** Fit a photo once and save, and the next run on
+  that photograph starts from those exact corners instead of a detection —
+  including a second screenshot into the same shot, which is the common case.
+  The photo is recognised by its pixels, not its name, so a rename or a
+  drag-drop from a different folder still match.
+- **And the fit is a file you can keep.** Every save writes `<mockup>.fit.json`
+  beside the output. Drag it back onto the page and the corners come back — on
+  another machine, from a colleague, or onto the same scene exported again,
+  which the pixel key cannot recognise. It says which photograph it was made
+  for, and stretches nothing without telling you.
 - **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.
@@ -138,15 +154,44 @@ you, and nothing below ever touches it.
 
 **Working files** live in `~/.screengraft/sessions/<timestamp>/` — one directory
 per run. A source you pick by path is never copied: screengraft reads it where it
-is. A source you drag in or browse to has to be copied, because a browser hands
-over bytes and will not say where they came from — and that copy, along with the
-preview and thumbnails, is **deleted when the run ends**. Anything left behind by
-a crash is swept the next time you launch.
-
-What survives is the `result.json` sidecar: a few hundred bytes recording the
-corners, radius, grade and blend of that fit, referencing your original files by
-path. It reproduces a composite exactly, and it is the first thing a bug report
-should include. Keep the recipe, not the ingredients.
+is, and screengraft never deletes a file of yours. A source you drag in or browse
+to has to be copied, because a browser hands over bytes and will not say where
+they came from.
+
+What happens to that copy depends on whether the run produced anything:
+
+- **A run that saved a mockup keeps its source.** The `result.json` sidecar names
+  it, and a recipe naming a file that no longer exists is not a recipe.
+- **A run that produced nothing keeps nothing.** That is the common case and
+  where the disk goes — previews, thumbnails, poster frames and abandoned
+  uploads are all swept when the run ends, or at the next launch after a crash.
+
+What survives either way is the `result.json` sidecar: a few hundred bytes
+recording the corners, radius, grade and blend of that fit. It reproduces a
+composite exactly, and it is the first thing a bug report should include.
+
+**A detection trace**, when you ask for one, is written to
+`<session>/candidates.json`: every candidate quad the detectors generated, with
+its score and whether it was accepted, rejected, never reached, or filtered out
+by your click. Ask for it with `POST /api/detect {"trace": true}`, or from the
+CLI with `scripts/detect.py --trace FILE`. Nothing produces it unless asked, and
+it is the right thing to attach to a bug report about detection.
+
+**The fit file** is written beside every mockup as `<name>.fit.json` — four
+corners, the corner radius, the device, and which photograph it was made for. It
+is yours: keep it with the project, send it to someone, drop it back on the page
+to reuse the fit. Geometry only; the grade and blend of a *composite* live in
+`result.json`.
+
+**Remembered fits** live in `~/.screengraft/fits.json`, outside any session so a
+sweep cannot take them. Each entry is the four corners, the radius fraction and
+the device, keyed by a hash of the photograph's decoded pixels — no image data,
+no absolute paths, a couple of hundred bytes each, and the oldest are dropped
+past 500. Delete the file to forget every fit; nothing else depends on it.
+
+Sidecars written by v0.23.0–v0.25.1 may name a dragged-in source that release
+deleted. Those cannot be repaired — the bytes are gone — but screengraft now
+marks them `"source_retained": false` rather than leaving them looking valid.
 
 
 ## Roadmap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.25.1",
+  "version": "0.37.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

@@ -54,6 +54,22 @@ 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
+# How unequal two OPPOSITE sides of the quad may be. A screen is a rectangle, and
+# the image of a rectangle under perspective foreshortens one end relative to the
+# other -- but not without limit at the angles anyone photographs a device from.
+#
+# Measured 10 Sep 2026 against seven hand-placed labels (the first real ground
+# truth this project has had): every true screen sits at 1.01-1.05, the two
+# usable detections at 1.04 and 1.11, and a quad returned CONFIDENTLY with one
+# corner collapsed ~800px into the middle of the screen sits at 2.26. Worst
+# correct 1.11 against best wrong 2.26 is a 2.0x margin.
+#
+# Set LOOSE at 1.9, not near the data. All seven are phones at modest angles;
+# a laptop or a monitor shot from the side genuinely foreshortens more, and this
+# check can only ever ADD refusals -- the cost of being wrong here is an honest
+# abstention and a manual fit, never a bad composite. Re-derive it on a wider
+# set of angles and device classes before tightening.
+MAX_OPPOSITE_RATIO = 1.9
 # 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
@@ -246,7 +262,26 @@ def order_quad(pts: np.ndarray) -> np.ndarray:
     return np.roll(pts, -start, axis=0)
 
 
-def refine_corners(contour, quad: np.ndarray):
+# The Canny path traces a RING -- both sides of one boundary -- and catches
+# content edges drawn inside the screen along with it. Fitting a line to all of
+# that lands it between the glass edge and whatever is drawn near it, which is
+# the 78px failure that banned refinement from this path at v0.13.0.
+#
+# The fix is to pick a rail rather than to ban the fit. Of the points assigned
+# to one edge, keep those within `RAIL_BAND_K` close-kernels of the outermost;
+# the ring's two rails are a kernel apart by construction, and content edges are
+# far deeper. Measured 11 Sep 2026 on the top-scoring edge candidate of five
+# hand-labelled photographs, worst per-edge median residual over the quad's
+# diagonal: 0.0673 fitting everything, 0.0052 after rail selection -- and the
+# quad that refinement had pushed from 12% to 40% lands at 0.4%.
+#
+# 2 is the ring's own thickness rounded up, not a fitted number: one kernel
+# separates the rails, the second is slack for the Canny width itself. A region
+# silhouette has one rail, so this keeps every point and changes nothing.
+RAIL_BAND_K = 2.0
+
+
+def refine_corners(contour, quad: np.ndarray, rail_band: float = 0.0):
     """
     Re-derive corners by intersecting fitted edge lines.
 
@@ -269,7 +304,10 @@ def refine_corners(contour, quad: np.ndarray):
         return quad, False
 
     # Distance from every point to every edge; nearest edge wins the point.
-    dists, projections = [], []
+    # `outward` is the same distance signed so that positive means away from the
+    # quad's own centre, which is what lets the outermost rail be picked below.
+    centre = quad.mean(axis=0)
+    dists, projections, outward = [], [], []
     for i in range(4):
         a, b = quad[i], quad[(i + 1) % 4]
         ab = b - a
@@ -278,17 +316,29 @@ def refine_corners(contour, quad: np.ndarray):
             return quad, False
         u = ab / length
         rel = pts - a
-        dists.append(np.abs(u[0] * rel[:, 1] - u[1] * rel[:, 0]))
+        cross = u[0] * rel[:, 1] - u[1] * rel[:, 0]
+        rc = centre - a
+        sign = -np.sign(u[0] * rc[1] - u[1] * rc[0])
+        dists.append(np.abs(cross))
         projections.append((rel @ ab) / (length ** 2))
+        outward.append(sign * cross)
     nearest = np.argmin(np.vstack(dists), axis=0)
 
     margin = (1.0 - EDGE_MIDDLE) / 2.0
     lines = []
     for i in range(4):
         t = projections[i]
-        sel = pts[(nearest == i) & (t > margin) & (t < 1.0 - margin)]
+        chosen = (nearest == i) & (t > margin) & (t < 1.0 - margin)
+        sel = pts[chosen]
         if len(sel) < 10:
             return quad, False
+        if rail_band > 0:
+            # 95th percentile rather than the maximum: one stray point further
+            # out than the rail would otherwise drag the window off it.
+            far = outward[i][chosen]
+            keep = far >= (float(np.percentile(far, 95)) - rail_band)
+            if int(keep.sum()) >= 10:
+                sel = sel[keep]
         vx, vy, x0, y0 = cv2.fitLine(
             sel.astype(np.float32), cv2.DIST_HUBER, 0, 0.01, 0.01
         ).ravel()
@@ -481,6 +531,20 @@ def validate_quad(corners: np.ndarray, contour, img_area: float, img_shape=None)
     if min(sides) < MIN_SIDE_RATIO * max(sides):
         return False, ("final quad is a sliver (shortest side %.0f%% of the longest) "
                        % (100 * min(sides) / max(sides)))
+    # A collapsed corner passes every check above: the quad stays convex, no side
+    # is a sliver, the area is in range and the blob still fills it. What gives it
+    # away is that one PAIR of opposite sides is wildly unequal while the other is
+    # not -- which is what a rectangle cannot do, at any angle a device is
+    # photographed from. Found on a real photograph where three corners sat on the
+    # glass and the fourth was in the middle of the screen, returned with no
+    # abstention: the one failure this tool says it does not have.
+    opposite = max(max(sides[0], sides[2]) / max(min(sides[0], sides[2]), 1e-6),
+                   max(sides[1], sides[3]) / max(min(sides[1], sides[3]), 1e-6))
+    if opposite > MAX_OPPOSITE_RATIO:
+        return False, ("opposite sides of the final quad differ by %.1fx (ceiling "
+                       "%.1fx) — a rectangle in perspective does not do that, so a "
+                       "corner has been pulled off the screen"
+                       % (opposite, MAX_OPPOSITE_RATIO))
     if contour is not None:
         fill = float(cv2.contourArea(contour)) / max(area, 1e-6)
         if fill < MIN_FILL:
@@ -504,8 +568,24 @@ def contains(quad, point) -> bool:
                                 (float(point[0]), float(point[1])), False) >= 0
 
 
+def _tag_json(tag):
+    """Whatever a detector used to label a candidate: a tone band, a threshold."""
+    if isinstance(tag, (tuple, list)):
+        return [int(t) for t in tag]
+    return int(tag) if isinstance(tag, (int, float, np.integer, np.floating)) else tag
+
+
+def _trace_row(method, score, quad, tag, verdict, why=""):
+    return {"method": method,
+            "score": round(float(score), 5),
+            "tag": _tag_json(tag),
+            "quad": [[round(float(x), 1), round(float(y), 1)] for x, y in quad],
+            "verdict": verdict,
+            "why": why}
+
+
 def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None,
-              click=None):
+              click=None, trace=None, method=None, rail_band: float = 0.0):
     """Best candidate that survives refinement AND validation.
 
     Walks candidates best-score-first rather than trusting the top one: a
@@ -513,14 +593,29 @@ def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None,
     miss, not a result, and the next candidate deserves a look before the
     detector gives up.
 
-    `refine` is off for the Canny path. refine_corners() assumes the contour
-    is a filled region's silhouette, where each side has one long straight
-    run to fit. A Canny contour is a ring tracing both sides of an edge, with
-    content edges caught inside it, so the per-edge line fits pick up the
-    wrong points: measured on the gradient-screen mockup it pushed one corner
-    78px off an otherwise correct quad . The polygon approximation of a
-    Canny boundary is already on the edge, so there is nothing to recover.
+    `refine` used to be off for the Canny path, and `rail_band` is why it no
+    longer is. refine_corners() assumes the contour is a filled region's
+    silhouette, where each side has one long straight run to fit; a Canny
+    contour is a ring tracing both sides of an edge, with content edges caught
+    inside it, so the per-edge line fits picked up the wrong points -- measured
+    on the gradient-screen mockup at v0.13.0, 78px off an otherwise correct
+    quad.
+
+    The claim that came with that ban -- "the polygon approximation of a Canny
+    boundary is already on the edge, so there is nothing to recover" -- was
+    wrong, and it cost this project the largest single bucket of detection
+    error for eighteen releases. approxPolyDP puts its vertices ON the rounded
+    corner arcs, inside the true corners, and on real photographs that is
+    **9-11% of the screen's own width** lost from every side.
+
+    `rail_band` fixes the fit instead of banning it: of the points assigned to
+    one edge, only those within a couple of close-kernels of the outermost are
+    fitted, which is the ring's own outer rail and excludes content edges by
+    construction. Measured over the top-scoring edge candidate on five
+    hand-labelled photographs: 12% -> 0.4%, 11% -> 0.5%, 8% -> 3.4%, 9% -> 6.8%.
+    A region silhouette has one rail, so passing 0 there changes nothing.
     """
+    generated = candidates
     if click is not None:
         # Before ranking, not after: the point of the click is to shrink the
         # field to the things the user actually pointed at, and let the existing
@@ -528,15 +623,59 @@ def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None,
         # re-confirm whichever candidate already won.
         candidates = [c for c in candidates if contains(c[1], click)]
     rejected = []
+    # The instrument. Every diagnosis this project has made about
+    # detection began by printing this list by hand, and TWICE it changed what
+    # the fix was: the 7 Sep rescoring that was the obvious answer and was
+    # wrong, because the true screen was never generated at all (693px away);
+    # and the click feature, where the correct quad turned out to be the top-scoring
+    # candidate containing the click, which deleted most of the planned work.
+    #
+    # What it exists to separate is RECALL from RANKING -- was the screen never
+    # proposed, or proposed and beaten? Those have opposite fixes and this
+    # project has never had the number. Off unless asked for, and it must not
+    # change the answer: it observes the same lists the walk below uses.
+    walked = {}
     for cand in sorted(candidates, key=lambda c: c[0], reverse=True):
-        score, quad, contour, tag = pick_innermost(candidates, cand)
+        # NOT necessarily `cand`: pick_innermost steps inward from it while a
+        # comparably screen-like quad nests inside, so the quad that gets
+        # validated -- and returned -- can belong to a different candidate.
+        picked = pick_innermost(candidates, cand)
+        score, quad, contour, tag = picked
         if refine:
-            refined, did_refine = refine_corners(contour, quad)
+            refined, did_refine = refine_corners(contour, quad, rail_band)
         else:
             refined, did_refine = quad, False
         corners = order_quad(refined)
         ok, why = validate_quad(corners, contour, img_area, img_shape)
+        if trace is not None:
+            # "accepted" by its own CHANNEL, which is not the same as winning:
+            # each of tone, edge and saturation accepts one, and detect() then
+            # arbitrates between them. The file's top-level `chosen` says which
+            # channel actually won, so a trace with three accepted rows and one
+            # chosen method is right, not a contradiction.
+            #
+            # And the walked candidate is not always the one whose quad came
+            # back. Measured on five real photographs: pick_innermost stepped
+            # inward on one of them, so a trace that credited `cand` would show
+            # the accepted row holding a quad that never became the answer,
+            # while the quad that DID sat in an `unreached` row. An instrument
+            # that misattributes the win is worse than no instrument -- a recall
+            # analysis reading it would draw the opposite conclusion.
+            if not ok:
+                walked[id(cand)] = ("rejected", why)
+            elif picked is cand:
+                walked[id(cand)] = ("accepted", "")
+            else:
+                walked[id(cand)] = ("accepted", "this candidate won the walk, but the "
+                                                "quad returned came from the nested "
+                                                "candidate marked supplied_the_answer")
+                walked[id(picked)] = ("supplied_the_answer",
+                                      "nested inside the accepted candidate; "
+                                      "pick_innermost stepped inward to it")
         if ok:
+            if trace is not None:
+                trace.extend(_walk_rows(generated, candidates, walked, method, click,
+                                        refine, rail_band))
             return {
                 "corners": [[round(float(x), 1), round(float(y), 1)] for x, y in corners],
                 "score": round(float(score), 5),
@@ -547,10 +686,58 @@ def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None,
                 "rejected": rejected,
             }
         rejected.append({"score": round(float(score), 5), "tag": tag, "why": why})
+    if trace is not None:
+        trace.extend(_walk_rows(generated, candidates, walked, method, click, refine,
+                                rail_band))
     return None
 
 
-def detect_tone(gray: np.ndarray, tone=None, click=None):
+def _walk_rows(generated, survived, walked, method, click, refine=True,
+               rail_band: float = 0.0):
+    """One row per candidate the detector GENERATED, with what became of it.
+
+    Four verdicts, and the distinction between the last two is the whole point:
+    `filtered_by_click` and `unreached` both mean "never judged", but one is the
+    user narrowing the field and the other is a higher-scoring candidate winning
+    first. A recall analysis needs to see quads in all four states, so nothing
+    is dropped from this list -- it is written to a file, not to a page.
+
+    Each row carries the REFINED quad, not the polygon approximation the
+    candidate was built from. The walk refines before it validates, so a row
+    holding the raw quad describes a proposal the detector never actually
+    considered -- and the two differ by the whole rounded-corner inset, which on
+    real photographs is 9-11% of the screen's own width. That defect cost a day
+    on 11 Sep 2026: the recall column said the best proposal was 9% off
+    when refining it put it at 0.4%, so a corner-accuracy change looked like it
+    had bought nothing. An instrument that understates what a candidate is worth
+    is as wrong as one that misattributes the win, which this function already
+    goes to some trouble to avoid.
+    """
+    # Identity, not equality: two candidates can hold equal numbers and be
+    # different proposals. `survived` is a filtered view of `generated`, so the
+    # objects are shared and `is` holds -- but only while nobody rebuilds the
+    # list, which is why `click is None` is checked explicitly below rather than
+    # inferred from the sets matching. A future `[transform(c) for c in ...]`
+    # would otherwise relabel every row `filtered_by_click` in silence.
+    kept = {id(c) for c in survived}
+    rows = []
+    for cand in generated:
+        score, quad, contour, tag = cand
+        if refine:
+            quad = order_quad(refine_corners(contour, quad, rail_band)[0])
+        if click is not None and id(cand) not in kept:
+            verdict, why = "filtered_by_click", "the click was not inside this quad"
+        else:
+            verdict, why = walked.get(id(cand), ("unreached",
+                                                 "a higher-scoring candidate was accepted first"))
+        rows.append(_trace_row(method, score, quad, tag, verdict, why))
+    if click is not None:
+        for r in rows:
+            r["contains_click"] = r["verdict"] != "filtered_by_click"
+    return rows
+
+
+def detect_tone(gray: np.ndarray, tone=None, click=None, trace=None):
     """Tone-band segmentation. Assumes the screen sits in a narrow tone band."""
     h, w = gray.shape[:2]
     img_area = float(h * w)
@@ -581,7 +768,8 @@ def detect_tone(gray: np.ndarray, tone=None, click=None):
             score *= (16.0 / (hi - lo + 1)) ** 0.25
             candidates.append((score, order_quad(quad), contour, (lo, hi)))
 
-    res = _finalize(candidates, img_area, img_shape=gray.shape[:2], click=click)
+    res = _finalize(candidates, img_area, img_shape=gray.shape[:2], click=click,
+                    trace=trace, method="tone")
     if res is None:
         return None
     band = res.pop("_tag")
@@ -590,7 +778,7 @@ def detect_tone(gray: np.ndarray, tone=None, click=None):
     return res
 
 
-def detect_edges(gray: np.ndarray, click=None):
+def detect_edges(gray: np.ndarray, click=None, trace=None):
     """Canny-and-quad detection — the document-scanner path.
 
     Tone banding assumes a near-uniform screen, which breaks the moment the
@@ -629,7 +817,9 @@ def detect_edges(gray: np.ndarray, click=None):
             if score > 0 and quad is not None:
                 candidates.append((score, order_quad(quad), c, (lo, hi)))
 
-    res = _finalize(candidates, img_area, refine=False, img_shape=gray.shape[:2], click=click)
+    res = _finalize(candidates, img_area, img_shape=gray.shape[:2],
+                    rail_band=RAIL_BAND_K * _odd(0.004 * short),
+                    click=click, trace=trace, method="edge")
     if res is None:
         return None
     thr = res.pop("_tag")
@@ -638,7 +828,7 @@ def detect_edges(gray: np.ndarray, click=None):
     return res
 
 
-def detect_saturation(bgr: np.ndarray, click=None):
+def detect_saturation(bgr: np.ndarray, click=None, trace=None):
     """Neutral-region segmentation — the third detector, and the only one that
     looks at colour.
 
@@ -675,7 +865,8 @@ def detect_saturation(bgr: np.ndarray, click=None):
                 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], click=click)
+    res = _finalize(candidates, img_area, img_shape=sat.shape[:2], click=click,
+                    trace=trace, method="saturation")
     if res is None:
         return None
     res.pop("_tag")
@@ -702,7 +893,8 @@ def has_rounded_corners(result) -> bool:
     return spread <= MAX_RADIUS_SPREAD
 
 
-def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
+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.
 
     The two fail on opposite things. Tone banding needs a tonally uniform
@@ -721,22 +913,27 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
     which — 0.79 on the fixture (screen in body: take the inner, tone), 0.41
     on a gradient screen (slab on screen: take the outer, edge). When they
     don't nest at all, neither is a subregion of the other and tone wins,
-    since its assumptions being met is itself evidence and it refines corners.
+    since its assumptions being met is itself evidence: a screen that lands
+    inside one narrow tone band is a screen.
 
     Disagreement is reported, never silently resolved — the human confirms
     the corners either way.
     """
+    # `trace`, when given, is a list this fills with one row per candidate every
+    # 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.
     results = []
     if method in ("auto", "tone"):
-        r = detect_tone(gray, tone, click=click)
+        r = detect_tone(gray, tone, click=click, trace=trace)
         if r:
             results.append(r)
     if method in ("auto", "edge") and tone is None:
-        r = detect_edges(gray, click=click)
+        r = detect_edges(gray, click=click, 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)
+        r = detect_saturation(color, click=click, trace=trace)
         if r:
             results.append(r)
 
@@ -755,8 +952,9 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
     # 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.
+    # away the right answer). Corner REFINEMENT is no longer skipped there --
+    # rail selection made the line fits safe on a ring, see refine_corners() --
+    # but measuring a RADIUS from a ring is a separate claim and still is.
     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)]
@@ -768,7 +966,7 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
     e = next((r for r in results if r["method"] == "edge"), None)
     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 len(results) == 1 else "its tone band assumption held, which is itself evidence"
     if t and e:
         tq, eq = t["_corners_np"], e["_corners_np"]
         ta = float(cv2.contourArea(tq.astype(np.float32)))
@@ -783,10 +981,11 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
             best, why = t, ("the tone quad sits inside the edge quad at %.0f%% of "
                             "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"
+            best, why = t, ("the two quads aren't nested; tone's band assumption "
+                            "holding is itself evidence that it found a screen")
     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.
+        # surviving region detector measured a real corner radius; edge cannot.
         best, why = sat, ("the saturation detector found a region with rounded "
                           "corners where tone did not")
     else:
@@ -892,6 +1091,34 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
     return best
 
 
+def write_trace(path, photo_path, shape, click, result, rows):
+    """The candidate list as a file, which is the form a benchmark can read.
+
+    Deliberately not folded into the sidecar: `result.json` is the recipe for
+    reproducing a composite and is contract-tested against compose()'s
+    signature, so hanging diagnostics off it would couple two things that
+    change for different reasons. This is a separate artefact of a separate
+    run.
+    """
+    by_verdict = {}
+    for r in rows:
+        by_verdict[r["verdict"]] = by_verdict.get(r["verdict"], 0) + 1
+    with open(path, "w") as f:
+        json.dump({
+            "photo": photo_path,
+            "size": [int(shape[1]), int(shape[0])],
+            "click": list(click) if click else None,
+            "chosen": None if result is None else {
+                "method": result.get("method"),
+                "corners": result.get("corners"),
+                "abstained": bool(result.get("abstained")),
+            },
+            "counts": {"candidates": len(rows), **by_verdict},
+            "candidates": rows,
+        }, f, indent=1)
+    return by_verdict
+
+
 def main() -> None:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--photo", required=True)
@@ -899,6 +1126,9 @@ def main() -> None:
     ap.add_argument("--out-overlay", help="Optional PNG showing the detected quad on the photo")
     ap.add_argument("--out-zooms", help="Optional directory for 2x corner close-ups")
     ap.add_argument("--tone", help="Skip the sweep and force one band, e.g. --tone 20,40")
+    ap.add_argument("--click", help="A point inside the screen, X,Y in photo pixels")
+    ap.add_argument("--trace", help="Write every candidate quad, with its score and "
+                                    "what became of it, to this JSON file")
     args = ap.parse_args()
 
     photo = cv2.imread(args.photo, cv2.IMREAD_COLOR)
@@ -914,7 +1144,23 @@ def main() -> None:
         except ValueError:
             sys.exit("error: --tone must be LO,HI (e.g. 20,40)")
 
-    result = detect(gray, tone)
+    click = None
+    if args.click:
+        try:
+            click = tuple(float(v) for v in args.click.split(","))
+            if len(click) != 2:
+                raise ValueError
+        except ValueError:
+            sys.exit("error: --click must be X,Y (e.g. --click 850,637)")
+
+    trace = [] if args.trace else None
+    result = detect(gray, tone, color=photo, click=click, trace=trace)
+    if trace is not None:
+        # Written whether or not anything was found: a run that found NOTHING is
+        # the most interesting one to inspect, and it is exactly the run that
+        # would otherwise leave no trace at all.
+        write_trace(args.trace, args.photo, photo.shape, click, result, trace)
+        print(f"trace: {len(trace)} candidates -> {args.trace}", file=sys.stderr)
     if result is None:
         sys.exit(
             "error: no screen-like quad found. The screen's tone probably isn't "