screengraft 0.25.1 → 0.37.0

package/scripts/ui.py

@@ -47,6 +47,8 @@ sys.path.insert(0, HERE)
 import cv2  # noqa: E402
 import numpy as np  # noqa: E402
 import detect as D  # noqa: E402
+import fitfile as FF  # noqa: E402
+import fits as FIT  # noqa: E402
 import scan as S  # noqa: E402
 import warp as W  # noqa: E402
 
@@ -76,17 +78,104 @@ def _write_json_atomic(path, obj):
     os.replace(tmp, path)
 
 # Corner radius as a fraction of the SCREEN'S WIDTH, per device preset.
-# Approximations from public specs (pt): iPhone 15/16 393pt wide, ~55pt radius;
-# Pro Max 430pt; iPads ~18pt on 744-1024pt; MacBook display corners ~12px on
-# ~1500pt; monitors square. Good enough to start a drag from; measure beats these.
+#
+# The iPhone values are DERIVED, not estimated: radius in points from Apple's
+# private `UIScreen._displayCornerRadius`, as collected by kylebshr/ScreenCorners,
+# divided by the model's logical width in points. Both are exact, so the fraction
+# is too — the only approximation left is that a photographed screen is not
+# always exactly its logical aspect.
+#
+# There is no single "iPhone radius" and the spread is large: 39pt on an iPhone X
+# against 62pt on a 17 Pro, and because width also changes, two models with the
+# SAME radius land on different fractions (55pt is 14.0% of a 393pt iPhone 16 and
+# 12.8% of a 430pt 16 Plus). A single preset could not have covered these.
+#
+#   group                                        radius   width    frac
+#   iPhone 17 Pro / 17 / 16 Pro                   62.0     402     0.154
+#   iPhone Air                                    62.0     420     0.148
+#   iPhone 17 Pro Max / 16 Pro Max                62.0     440     0.141
+#   iPhone 16 / 15 Pro / 15 / 14 Pro              55.0     393     0.140
+#   iPhone 16 Plus / 15 Pro Max / 15 Plus /
+#     14 Pro Max                                  55.0     430     0.128
+#   iPhone 14 Plus / 13 Pro Max / 12 Pro Max      53.33    428     0.125
+#   iPhone 16e / 14 / 13 Pro / 13 / 12 Pro / 12   47.33    390     0.121
+#   iPhone 13 mini / 12 mini                      44.0     375     0.117
+#   iPhone 11 / XR                                41.5     414     0.100
+#   iPhone 11 Pro / XS / X                        39.0     375     0.104
+#   iPhone 11 Pro Max / XS Max                    39.0     414     0.094
+#   iPhone SE / 8 / 7                              0       -       0
+#
+# Two caveats worth knowing before trusting a preset over a measurement:
+#
+# 1. ScreenCorners lists the plain **iPhone 13** nowhere, while listing the 13
+#    Pro at 47.33. The 13 and 13 Pro share a 390x844 display, so 47.33 is the
+#    inference here rather than a reported value. It is the only entry below
+#    that is not directly attested.
+# 2. Apple's display corners are a **continuous curve**, not a circular arc, and
+#    compose() applies a circular radius. Matched by number they are not matched
+#    by shape — a continuous corner reads slightly tighter at the diagonal. The
+#    preset is a starting position; the measured radius, when the photograph
+#    gives one, beats it.
+#
+# `label` is what fits the closed dropdown at its real width. `full` is the
+# exact membership and the numbers it came from, and the page puts it in the
+# CAPTION under the slider — not in a tooltip on the <option>, which a native
+# macOS select popup does not reliably render. The short label must never be
+# the only place the truth lives.
+#
+# `smoothing` is Figma's corner smoothing for that device: Apple's display
+# corners are a continuous curve, not a circular arc, so every Apple preset
+# carries 0.6 — the value Figma labels "iOS". Android and the square entries
+# carry nothing and stay circular. It is a property of the DEVICE, which is why
+# it lives here rather than in a control: a photograph of an iPhone does not
+# have a smoothing preference, it has a shape.
+#
+# iPads: 18pt on every rounded model, over 744pt (mini) / 834pt (11" / Air) /
+# 1024pt (12.9"). MacBook display corners ~12px on ~1500pt. Monitors square.
 PRESETS = [
-    {"id": "phone-iphone", "type": "phone", "label": "iPhone 15 / 16 / Pro", "frac": 0.140},
-    {"id": "phone-iphone-max", "type": "phone", "label": "iPhone Plus / Pro Max", "frac": 0.128},
+    # Newest first — that is the order a photograph is likely to be of.
+    {"id": "phone-iphone-17pro", "type": "phone", "smoothing": 0.6, "frac": 0.154,
+     "label": "iPhone 17 Pro / 17 / 16 Pro",
+     "full": "iPhone 17 Pro, iPhone 17, iPhone 16 Pro \u2014 62pt over 402pt"},
+    {"id": "phone-iphone-air", "type": "phone", "smoothing": 0.6, "frac": 0.148,
+     "label": "iPhone Air",
+     "full": "iPhone Air \u2014 62pt over 420pt"},
+    {"id": "phone-iphone-17promax", "type": "phone", "smoothing": 0.6, "frac": 0.141,
+     "label": "iPhone 17 Pro Max / 16 Pro Max",
+     "full": "iPhone 17 Pro Max, iPhone 16 Pro Max \u2014 62pt over 440pt"},
+    # Keeps its original id: this group is what "iPhone 15 / 16 / Pro" meant.
+    {"id": "phone-iphone", "type": "phone", "smoothing": 0.6, "frac": 0.140,
+     "label": "iPhone 16 / 15 / 15 Pro / 14 Pro",
+     "full": "iPhone 16, 15, 15 Pro, 14 Pro \u2014 55pt over 393pt"},
+    {"id": "phone-iphone-max", "type": "phone", "smoothing": 0.6, "frac": 0.128,
+     "label": "iPhone 15\u201316 Plus, 14\u201315 Pro Max",
+     "full": "iPhone 16 Plus, 15 Plus, 15 Pro Max, 14 Pro Max \u2014 55pt over 430pt"},
+    {"id": "phone-iphone-14plus", "type": "phone", "smoothing": 0.6, "frac": 0.125,
+     "label": "iPhone 14 Plus / 12\u201313 Pro Max",
+     "full": "iPhone 14 Plus, 13 Pro Max, 12 Pro Max \u2014 53.33pt over 428pt"},
+    {"id": "phone-iphone-12", "type": "phone", "smoothing": 0.6, "frac": 0.121,
+     "label": "iPhone 12\u201314 / 12\u201313 Pro / 16e",
+     "full": "iPhone 14, 13, 13 Pro, 12, 12 Pro, 16e \u2014 47.33pt over 390pt. The plain 13 is inferred: it shares the 390pt display with the 13 Pro."},
+    {"id": "phone-iphone-mini", "type": "phone", "smoothing": 0.6, "frac": 0.117,
+     "label": "iPhone 13 mini / 12 mini",
+     "full": "iPhone 13 mini, 12 mini \u2014 44pt over 375pt"},
+    {"id": "phone-iphone-x", "type": "phone", "smoothing": 0.6, "frac": 0.104,
+     "label": "iPhone 11 Pro / XS / X",
+     "full": "iPhone 11 Pro, XS, X \u2014 39pt over 375pt"},
+    {"id": "phone-iphone-xr", "type": "phone", "smoothing": 0.6, "frac": 0.100,
+     "label": "iPhone 11 / XR",
+     "full": "iPhone 11, XR \u2014 41.5pt over 414pt"},
+    {"id": "phone-iphone-xsmax", "type": "phone", "smoothing": 0.6, "frac": 0.094,
+     "label": "iPhone 11 Pro Max / XS Max",
+     "full": "iPhone 11 Pro Max, XS Max \u2014 39pt over 414pt"},
+    {"id": "phone-iphone-se", "type": "phone", "frac": 0.0,
+     "label": "iPhone SE / 8 / 7",
+     "full": "iPhone SE (2nd/3rd gen), 8, 7 \u2014 square display corners, no radius"},
     {"id": "phone-android", "type": "phone", "label": "Android (typical)", "frac": 0.090},
-    {"id": "tablet-ipad-pro-11", "type": "tablet", "label": "iPad Pro 11 / Air", "frac": 0.022},
-    {"id": "tablet-ipad-pro-13", "type": "tablet", "label": "iPad Pro 13", "frac": 0.018},
-    {"id": "tablet-ipad-mini", "type": "tablet", "label": "iPad mini", "frac": 0.024},
-    {"id": "laptop-macbook", "type": "laptop", "label": "MacBook Air / Pro", "frac": 0.008},
+    {"id": "tablet-ipad-pro-11", "type": "tablet", "smoothing": 0.6, "label": "iPad Pro 11 / Air", "frac": 0.022},
+    {"id": "tablet-ipad-pro-13", "type": "tablet", "smoothing": 0.6, "label": "iPad Pro 13", "frac": 0.018},
+    {"id": "tablet-ipad-mini", "type": "tablet", "smoothing": 0.6, "label": "iPad mini", "frac": 0.024},
+    {"id": "laptop-macbook", "type": "laptop", "smoothing": 0.6, "label": "MacBook Air / Pro", "frac": 0.008},
     {"id": "laptop-other", "type": "laptop", "label": "Other laptop (square)", "frac": 0.0},
     {"id": "desktop", "type": "desktop", "label": "Desktop monitor (square)", "frac": 0.0},
 ]
@@ -152,17 +241,57 @@ SESSION: Session = None
 _RESIDUE_PREFIXES = ("photo-", "screenshot-", "poster-", "frame-")
 # figma-export.png is a copy too -- the agent fetches the frame and drops it
 # here -- and re-exporting is one MCP round trip, so it is residue like the rest.
-_RESIDUE_NAMES = ("preview.png", "figma-export.png")
+_RESIDUE_NAMES = ("preview.png", "preview.mp4", "figma-export.png")
+
+
+def _sidecar_sources(d):
+    """Absolute paths inside `d` that this session's result.json still names.
+
+    v0.23.0 swept these too, and the sidecar's whole promise is that a fit can
+    be re-run from it. That promise held for a source picked by PATH, which
+    was never copied -- and quietly broke for a drag-drop or browse, where the
+    browser hands over bytes with no origin and the copy in the session IS the
+    original as far as the sidecar is concerned. Measured after the first sweep:
+    9 of 9 such sidecars pointed at a deleted file.
+
+    So the rule is now: a session that produced output keeps what its sidecar
+    names. A session that produced nothing keeps nothing -- there is no recipe
+    to protect, which is the common case and where the volume is.
+
+    Only paths INSIDE the session are returned. A path-picked source lives in
+    the user's own folders and was never ours to keep or delete.
+
+    Note the sidecar is rewritten on every save, so it names the LAST fit. An
+    earlier source replaced within the same session is not protected: the record
+    is what survives, and the record says what it says.
+    """
+    try:
+        with open(os.path.join(d, "result.json")) as f:
+            res = json.load(f)
+    except (OSError, ValueError):
+        return set()
+    root = os.path.realpath(d)
+    keep = set()
+    for key in ("photo", "screenshot"):
+        p = res.get(key)
+        if not p:
+            continue
+        rp = os.path.realpath(p)
+        if rp == root or rp.startswith(root + os.sep):
+            keep.add(rp)
+    return keep
 
 
 def _sweep_session(d):
     """Delete a session's copied and derived media. Returns bytes reclaimed.
 
-    Never touches *.json, and never touches OUT_DIR -- the actual outputs live
-    in the project folder and are the point of the whole exercise.
+    Never touches *.json, never touches OUT_DIR -- the actual outputs live in
+    the project folder and are the point of the whole exercise -- and never
+    touches a source the session's own result.json still names (see above).
     """
     freed = 0
     thumbs = os.path.join(d, "thumbs")
+    protected = _sidecar_sources(d)
     for base, _, files in os.walk(d):
         for f in files:
             keep = f.endswith(".json")
@@ -171,6 +300,8 @@ def _sweep_session(d):
             if keep or not residue:
                 continue
             fp = os.path.join(base, f)
+            if os.path.realpath(fp) in protected:
+                continue
             try:
                 freed += os.path.getsize(fp)
                 os.remove(fp)
@@ -179,6 +310,39 @@ def _sweep_session(d):
     return freed
 
 
+def _mark_unreproducible(d):
+    """Stamp a sidecar whose named source no longer exists.
+
+    For the sessions v0.23.0 already swept, nothing can be recovered -- the
+    bytes are gone and the browser never said where they came from. What can be
+    fixed is the claim: a sidecar that names a deleted file reads exactly like
+    one that works, and the difference only shows up when someone tries to
+    re-run it. `source_retained: false` says so up front.
+
+    Idempotent, and it never touches a sidecar whose files are intact.
+    """
+    path = os.path.join(d, "result.json")
+    try:
+        with open(path) as f:
+            res = json.load(f)
+    except (OSError, ValueError):
+        return False
+    if "source_retained" in res:
+        return False
+    named = [res.get(k) for k in ("photo", "screenshot")]
+    if not any(named) or all(p and os.path.exists(p) for p in named if p):
+        return False
+    res["source_retained"] = False
+    tmp = path + ".tmp"
+    try:
+        with open(tmp, "w") as f:
+            json.dump(res, f, indent=1)
+        os.replace(tmp, path)
+    except OSError:
+        return False
+    return True
+
+
 def _prune_sessions(keep):
     """Sweep every session but the live one, at launch.
 
@@ -191,7 +355,10 @@ def _prune_sessions(keep):
     /api/use records the path and reads through it. Only a drag-drop or a browse
     has to be copied, because the browser hands over bytes and will not say
     where they came from. So this is the other half of the same policy: what
-    cannot avoid being copied does not outlive the run that needed it.
+    cannot avoid being copied does not outlive the run that needed it --
+    UNLESS the run produced something, in which case its sidecar names the
+    source and _sweep_session keeps it. See _sidecar_sources: reproducibility
+    beats disk exactly where a fit actually happened, and nowhere else.
     """
     root = os.path.dirname(keep)
     freed = 0
@@ -204,6 +371,10 @@ def _prune_sessions(keep):
         if d == keep or not os.path.isdir(d):
             continue
         freed += _sweep_session(d)
+        # After sweeping, not before: a sidecar is only unreproducible once its
+        # source is actually gone, and from here on the sweep leaves it alone.
+        # This is for the sessions the previous release already emptied.
+        _mark_unreproducible(d)
     return freed
 
 
@@ -385,12 +556,28 @@ def _read_source(path: str):
 # an HTTP request open — so the render runs on its own thread and the page
 # polls. ThreadingHTTPServer is already the server class, so this needs no
 # other machinery.
-RENDER = {"state": "idle", "done": 0, "total": 0, "output": None, "message": None}
+RENDER = {"state": "idle", "done": 0, "total": 0, "output": None, "message": None,
+          "kind": "render"}
 RENDER_LOCK = threading.Lock()
 
 
+# How wide a preview proxy is composited. Small enough that a clip can be
+# watched in seconds rather than minutes, large enough that the two things a
+# preview exists to judge -- the light match holding across the clip, and the
+# emissive blend against changing content -- are visible. It is a PROXY: it
+# never reaches --out-dir and never becomes the session output.
+PREVIEW_WIDTH = 720
+# ...and how much of the clip. A 2460-frame recording takes about as long to
+# composite as the render it is meant to save you from, and a preview you wait a
+# minute for is a render with a worse output. Six seconds from the frame you
+# fitted on is enough to watch the light match hold and the emissive blend move
+# with the content; the scrubber picks a different moment if you want one.
+PREVIEW_SECONDS = 6.0
+
+
 def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame,
-                   blend="replace", reflection=None, result=None):
+                   blend="replace", reflection=None, result=None, kind="render",
+                   start_frame=0, max_frames=None, *, smoothing=0.0):
     """Encode the clip, and only if that SUCCEEDS publish what it produced.
 
     `result` is the sidecar this render would write. It is handed to the worker
@@ -409,24 +596,57 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
             RENDER["done"], RENDER["total"] = done, total
     try:
         info = W.compose_video(photo, video_path, corners, dest,
-                               corner_radius=radius_px, grade=gr, grain=grain,
+                               corner_radius=radius_px, corner_smoothing=smoothing,
+                               grade=gr, grain=grain,
                                preset=preset, fit_frame=fit_frame, progress=progress,
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
-                                           else reflection))
+                                           else reflection),
+                               start_frame=start_frame, max_frames=max_frames)
+        if kind == "preview":
+            # A preview publishes NOTHING. It is not a save: no sidecar, no fit
+            # file, and above all not the session output -- /api/import reads
+            # that pointer, and handing Claude a 720px proxy instead of the
+            # mockup would be the render-output defect of 9 Sep, inverted.
+            with RENDER_LOCK:
+                RENDER.update(state="done", output=dest, info=info, kind=kind,
+                              done=info["frames"], total=info["frames"], message=None)
+            return
         if result is not None:
             _write_json_atomic(SESSION.result_path, {**result, "saved": time.time()})
+            # Same rule as /api/save, and for the same reason it lives after the
+            # encode: the fit is remembered by the run that produced a file.
+            key = FIT.key_for(photo)
+            FIT.remember(key, corners, result.get("radius_frac"),
+                         result.get("device"), result.get("photo"),
+                         (photo.shape[1], photo.shape[0]))
+            FF.write(dest, FF.build(corners, result.get("radius_frac"),
+                                    result.get("device"), result.get("photo"),
+                                    (photo.shape[1], photo.shape[0]), key))
         # The still path has always done this (see /api/save); the render path
         # never did, so /api/import -- which reads SESSION.state["output"] --
         # either found nothing or, worse, silently handed over the PREVIOUS
         # still image after a successful render.
         SESSION.update(output=dest)
         with RENDER_LOCK:
-            RENDER.update(state="done", output=dest, info=info,
+            RENDER.update(state="done", output=dest, info=info, kind=kind,
                           done=info["frames"], total=info["frames"], message=None)
     except Exception as e:                     # noqa: BLE001 - surfaced to the page
         with RENDER_LOCK:
-            RENDER.update(state="error", message=str(e))
+            RENDER.update(state="error", message=str(e), kind=kind)
+
+
+def _smoothing(b) -> float:
+    """Figma corner smoothing for this request, 0-1.
+
+    Absent means 0, which is a circular arc — so a client that predates
+    smoothing, and a sidecar replayed through the CLI, both get the shape they
+    got before. That default is the compatibility guarantee, not a convenience.
+    """
+    try:
+        return float(min(max(float(b.get("smoothing") or 0.0), 0.0), 1.0))
+    except (TypeError, ValueError):
+        return 0.0
 
 
 def _blend_args(b):
@@ -444,6 +664,44 @@ def _blend_args(b):
     return "emissive", float(max(0.0, min(1.0, float(r))))
 
 
+ROLES = ("photo", "screenshot")
+
+
+def _adopt(role, path):
+    """Make a chosen source the session's, and answer what the page needs.
+
+    /api/use and /api/upload differ only in where the bytes came from --
+    everything after that (the video probe, the session state, and now the
+    remembered fit) has to be identical for a drag-drop and a path pick, or the
+    feature works one way in and not the other. It was already written twice;
+    the fit lookup would have made it three, and a set of writers that
+    disagree is a defect this project has already shipped once.
+    """
+    # The role names a session-state key, and the line below writes it, so an
+    # unchecked role is a write primitive: role="output" sets the pointer
+    # /api/import reads, and the agent is then asked to show whatever file that
+    # names. Nothing on this port authenticates, so the caller is not
+    # necessarily the page. Two roles exist; anything else is a 400.
+    if role not in ROLES:
+        raise ValueError(f"role must be one of {', '.join(ROLES)}")
+    if role == "screenshot":
+        SESSION.update(fit_frame=0)
+        im, real, meta = _read_source(path)
+    else:
+        im, real = _read_image(path)
+        meta = {"video": False}
+    SESSION.update(**{role: real})
+    if role == "photo":
+        # The quad is a property of the PHOTOGRAPH, so a fit saved on an earlier
+        # run is a better starting position than any detector -- and a stronger
+        # claim, which is why the page states where the quad came from rather
+        # than presenting a memory as a detection.
+        e = FIT.recall(FIT.key_for(im))
+        if e:
+            meta["remembered"] = e
+    return {"path": real, "size": [im.shape[1], im.shape[0]], **meta}
+
+
 def _guess_type(corners):
     c = np.array(corners, dtype=float)
     w = (np.linalg.norm(c[1] - c[0]) + np.linalg.norm(c[2] - c[3])) / 2
@@ -476,13 +734,54 @@ class Handler(BaseHTTPRequestHandler):
         self.wfile.write(body)
 
     def _file(self, path, ctype=None):
+        """Serve a local file, answering a Range request when one is made.
+
+        A browser cannot SEEK in a video the server will only hand over whole:
+        it plays from the start and every jump snaps back to zero. That is not a
+        detail here -- the live view exists to be parked on the frame the edges
+        were matched against, and the frame scrubber is supposed to move it.
+        Measured before fixing: setting currentTime to 9.0s read back as 0.0.
+
+        So: advertise `Accept-Ranges`, and answer a single `bytes=a-b` with a
+        206. Multi-range is not implemented and is not needed -- media players
+        ask for one range at a time -- and anything unparseable falls through to
+        the whole file, which is what the spec asks for.
+        """
         try:
-            with open(path, "rb") as f:
-                data = f.read()
+            size = os.path.getsize(path)
+            f = open(path, "rb")
         except OSError:
             return self._json({"error": "not found"}, 404)
-        self.send_response(200)
-        self.send_header("Content-Type", ctype or mimetypes.guess_type(path)[0] or "application/octet-stream")
+        ctype = ctype or mimetypes.guess_type(path)[0] or "application/octet-stream"
+        start, end = 0, size - 1
+        partial = False
+        rng = self.headers.get("Range") or ""
+        if rng.startswith("bytes=") and "," not in rng:
+            a, _, b = rng[6:].partition("-")
+            try:
+                if a:
+                    start = int(a)
+                    end = int(b) if b else size - 1
+                elif b:                       # bytes=-N: the LAST n bytes
+                    start = max(0, size - int(b))
+                if 0 <= start <= end < size:
+                    partial = True
+                else:
+                    start, end = 0, size - 1
+            except ValueError:
+                start, end = 0, size - 1
+        try:
+            with f:
+                if partial:
+                    f.seek(start)
+                data = f.read(end - start + 1) if partial else f.read()
+        except OSError:
+            return self._json({"error": "not readable"}, 404)
+        self.send_response(206 if partial else 200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Accept-Ranges", "bytes")
+        if partial:
+            self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
         self.send_header("Content-Length", str(len(data)))
         self.send_header("Cache-Control", "no-store")
         self.end_headers()
@@ -566,27 +865,12 @@ class Handler(BaseHTTPRequestHandler):
                 with open(dest, "wb") as f:
                     f.write(self._body())
                 # A video is only ever a screen source; a photo must be a still.
-                if role == "screenshot":
-                    SESSION.update(fit_frame=0)
-                    im, real, meta = _read_source(dest)
-                else:
-                    im, real = _read_image(dest)
-                    meta = {"video": False}
-                SESSION.update(**{role: real})
-                return self._json({"path": real, "size": [im.shape[1], im.shape[0]], **meta})
+                return self._json(_adopt(role, dest))
 
             b = self._jbody()
 
             if u.path == "/api/use":
-                role = b["role"]
-                if role == "screenshot":
-                    SESSION.update(fit_frame=0)
-                    im, real, meta = _read_source(b["path"])
-                else:
-                    im, real = _read_image(b["path"])
-                    meta = {"video": False}
-                SESSION.update(**{role: real})
-                return self._json({"path": real, "size": [im.shape[1], im.shape[0]], **meta})
+                return self._json(_adopt(b["role"], b["path"]))
 
             if u.path == "/api/figma":
                 return self._json(SESSION.enqueue({
@@ -621,6 +905,29 @@ class Handler(BaseHTTPRequestHandler):
                 SESSION.update(screenshot=real)
                 return self._json({"path": real, "size": [im.shape[1], im.shape[0]]})
 
+            if u.path == "/api/fit":
+                # A fit file dropped onto the page. The page reads the bytes and
+                # posts the parsed document; only the server can judge it,
+                # because judging it means knowing what the OPEN photograph is.
+                #
+                # It never applies silently. Corners are meaningless on the wrong
+                # image and *plausible but wrong* on a crop of the right one,
+                # which is the more dangerous of the two — so every answer says
+                # which of four situations it is and the page says it out loud.
+                if not SESSION.state.get("photo"):
+                    raise ValueError("choose the photo first, then drop the fit onto it")
+                doc, err = FF.parse(b.get("fit"))
+                if err:
+                    return self._json({"error": err}, 400)
+                photo, _p = _read_image(SESSION.state["photo"])
+                corners, match, message = FF.apply_to(
+                    doc, (photo.shape[1], photo.shape[0]), FIT.key_for(photo))
+                return self._json({"corners": corners, "match": match,
+                                   "message": message,
+                                   "radius_frac": doc.get("radius_frac"),
+                                   "device": doc.get("device"),
+                                   "from": doc.get("photo", {}).get("name")})
+
             if u.path == "/api/detect":
                 if not SESSION.state.get("photo"):
                     raise ValueError("choose a photo first")
@@ -643,9 +950,23 @@ class Handler(BaseHTTPRequestHandler):
                         raise ValueError("the click is outside the photograph")
                 # `color` gives detect() the saturation detector — devices are
                 # neutral, furniture is not, and grayscale throws that away.
-                res = D.detect(gray, None, color=photo, click=click)
+                # The instrument, off unless asked for: the full
+                # candidate list, with each quad's score and what became of it,
+                # written beside the session. The page never shows it -- it is
+                # for the next person diagnosing a detection failure, and for a
+                # benchmark that needs to tell "never proposed" from "proposed
+                # and beaten". The response carries the counts and the path, not
+                # several hundred quads nobody asked the page to render.
+                trace = [] if (isinstance(b, dict) and b.get("trace")) else None
+                res = D.detect(gray, None, color=photo, click=click, trace=trace)
+                if trace is not None:
+                    tpath = os.path.join(SESSION.dir, "candidates.json")
+                    counts = D.write_trace(tpath, SESSION.state["photo"], photo.shape,
+                                           click, res, trace)
+                    trace_info = {"path": tpath, "candidates": len(trace), **counts}
                 if res is None:
                     return self._json({"found": False, "clicked": click is not None,
+                                       **({"trace": trace_info} if trace is not None else {}),
                                        "message": ("Nothing screen-shaped was found around that "
                                                    "point — try clicking nearer the middle of the "
                                                    "screen." if click is not None else
@@ -661,6 +982,7 @@ class Handler(BaseHTTPRequestHandler):
                     return self._json({"found": False,
                                        "message": res["abstain_reason"],
                                        "abstained": True,
+                                       **({"trace": trace_info} if trace is not None else {}),
                                        "inspect": res["corners"]})
                 res.pop("_corners_np", None)
                 res["found"] = True
@@ -670,6 +992,8 @@ class Handler(BaseHTTPRequestHandler):
                 res["confidence"] = ("corroborated" if res.get("agreement", {}).get("agree")
                                      else "unconfirmed")
                 res["type_guess"] = _guess_type(res["corners"])
+                if trace is not None:
+                    res["trace"] = trace_info
                 return self._json(res)
 
             if u.path == "/api/frame":
@@ -689,6 +1013,88 @@ class Handler(BaseHTTPRequestHandler):
                 SESSION.update(fit_frame=idx)
                 return self._json({"index": idx})
 
+            if u.path == "/api/preview_video":
+                # Watch the composite move before committing to a render.
+                #
+                # The one-frame preview cannot answer the two questions a CLIP
+                # raises, and they are the two settings most likely to misbehave
+                # over time: the light match is bound ONCE from the fitted frame
+                # (deliberately -- measuring per frame makes the screen pulse as
+                # the UI scrolls), so a badly chosen frame is wrong for the whole
+                # clip; and the emissive blend mixes the screenshot with the
+                # glass beneath it, so its effect changes as the content's own
+                # brightness does. Neither shows in a still.
+                #
+                # So this is a real composite through the same pipeline, at a
+                # smaller size -- not a CSS transform over a <video>, which would
+                # show the geometry moving and NONE of the grade, grain or blend,
+                # which is to say none of what it is for.
+                _need_sources()
+                photo, ppath = _read_image(SESSION.state["photo"])
+                spath = _safe_local_path(SESSION.state["screenshot"])
+                if not _is_video(spath):
+                    return self._json({"error": "the screen source is not a video"}, 400)
+                if not _have_ffmpeg():
+                    return self._json({"error": "ffmpeg is not installed",
+                                       "needs_ffmpeg": True}, 400)
+                with RENDER_LOCK:
+                    if RENDER["state"] == "running":
+                        return self._json({"error": "a render is already running"}, 409)
+                corners = _quad(b["corners"])
+                frac = float(b.get("radius_frac") or 0.0)
+                fit_frame = int(b.get("fit_frame") if b.get("fit_frame") is not None
+                                else _fit_frame())
+                first = W.read_frame_at(spath, fit_frame)
+                radius_px = frac * first.shape[1]
+                gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                grain = bool(b.get("grain", gr > 0))
+                blend, reflection = _blend_args(b)
+                # Downscale the PHOTO and scale the quad with it, rather than
+                # teaching compose_video about proxies: the same code path then
+                # produces the preview, so what is watched is what will render.
+                # The corner radius is in SCREENSHOT pixels and does not move.
+                scale = min(1.0, PREVIEW_WIDTH / float(photo.shape[1]))
+                if scale < 1.0:
+                    # EVEN dimensions, both of them. H.264 with yuv420p refuses an
+                    # odd width or height, and ffmpeg's way of refusing is to die
+                    # mid-stream -- which reaches Python as a BrokenPipeError on
+                    # the frame pipe, with the real complaint nowhere in sight.
+                    # Found by measuring rather than reading: 720 x 1536/2752
+                    # rounds to 401, and the whole preview vanished.
+                    def _even(v):
+                        return max(2, int(round(v / 2.0)) * 2)
+                    nw, nh = _even(photo.shape[1] * scale), _even(photo.shape[0] * scale)
+                    # Scale the quad by what the resize ACTUALLY did, not by the
+                    # ratio that was asked for: the evening moves it by up to a
+                    # pixel, and a quad scaled by the wrong factor is a fit that
+                    # does not match the preview it is shown in.
+                    sx, sy = nw / float(photo.shape[1]), nh / float(photo.shape[0])
+                    photo = cv2.resize(photo, (nw, nh), interpolation=cv2.INTER_AREA)
+                    corners = [[x * sx, y * sy] for x, y in corners]
+                _n, _fps, _vw, _vh = W.probe_video(spath)
+                max_frames = max(1, int(round(PREVIEW_SECONDS * (_fps or 30))))
+                dest = os.path.join(SESSION.dir, "preview.mp4")
+                with RENDER_LOCK:
+                    if RENDER["state"] == "running":
+                        return self._json({"error": "a render is already running"}, 409)
+                    RENDER.update(state="running", done=0, total=0, kind="preview",
+                                  output=None, message=None)
+                try:
+                    threading.Thread(target=_render_worker, daemon=True,
+                                     args=(photo, spath, corners, dest, radius_px,
+                                           gr, grain, "web", fit_frame,
+                                           blend, reflection, None, "preview",
+                                           fit_frame, max_frames),
+                                     kwargs={"smoothing": _smoothing(b)}).start()
+                except BaseException:
+                    with RENDER_LOCK:
+                        RENDER.update(state="error", message="could not start the preview")
+                    raise
+                return self._json({"started": True, "preview": dest,
+                                   "scale": round(scale, 4),
+                                   "seconds": PREVIEW_SECONDS,
+                                   "from_frame": fit_frame})
+
             if u.path == "/api/render":
                 # Video: same fit, same geometry, N frames instead of one.
                 _need_sources()
@@ -730,9 +1136,18 @@ class Handler(BaseHTTPRequestHandler):
                 # undercuts the determinism claim.
                 result = {"output": dest, "photo": ppath, "screenshot": spath,
                           "corners": corners, "radius_frac": frac, "radius_px": radius_px,
-                          "device": b.get("device"), "grade": gr, "grain": grain,
+                          "device": b.get("device"), "corner_smoothing": _smoothing(b),
+                          "grade": gr, "grain": grain,
                           "video": True, "preset": preset, "fit_frame": fit_frame,
-                          "blend": blend, "reflection": reflection}
+                          "blend": blend, "reflection": reflection,
+                          # A render is always the whole clip; only the preview
+                          # passes a segment. Recorded anyway, because the
+                          # sidecar's promise is EVERY argument that changes the
+                          # output — and if rendering a segment ever ships, the
+                          # recipe already carries it rather than silently
+                          # reproducing something else. test_sidecar.py caught
+                          # their absence the moment they were added.
+                          "start_frame": 0, "max_frames": None}
                 # `state="running"` means "a thread is running", so it is set
                 # here -- after every line that can raise, immediately before the
                 # thread exists. It used to be set at the top of this route, so a
@@ -744,13 +1159,14 @@ class Handler(BaseHTTPRequestHandler):
                 with RENDER_LOCK:
                     if RENDER["state"] == "running":
                         return self._json({"error": "a render is already running"}, 409)
-                    RENDER.update(state="running", done=0, total=0,
+                    RENDER.update(state="running", done=0, total=0, kind="render",
                                   output=None, message=None)
                 try:
                     threading.Thread(target=_render_worker, daemon=True,
                                      args=(photo, spath, corners, dest, radius_px,
                                            gr, grain, preset, fit_frame,
-                                           blend, reflection, result)).start()
+                                           blend, reflection, result),
+                                     kwargs={"smoothing": _smoothing(b)}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -772,7 +1188,9 @@ class Handler(BaseHTTPRequestHandler):
                 # when the photograph is (a portfolio shot).
                 gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
                 blend, reflection = _blend_args(b)
+                smoothing = _smoothing(b)
                 out = W.compose(photo, shot, corners, radius_px,
+                                corner_smoothing=smoothing,
                                 grade=gr, grain=bool(b.get("grain", gr > 0)),
                                 blend=blend, reflection=reflection)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
@@ -807,9 +1225,29 @@ class Handler(BaseHTTPRequestHandler):
                 # cannot be forgotten the same way.
                 result = {"output": dest, "photo": ppath, "screenshot": spath, "corners": corners,
                           "radius_frac": frac, "radius_px": radius_px, "device": b.get("device"),
+                          "corner_smoothing": smoothing,
                           "grade": gr, "grain": bool(b.get("grain", gr > 0)),
                           "blend": blend, "reflection": reflection,
                           "saved": time.time()}
+                # A fit is remembered when it PRODUCED something, not while it
+                # is being dragged: a quad on the canvas is a work in progress,
+                # a quad that made an output is one the person looked at and
+                # kept. Next run on this photograph starts from it.
+                key = FIT.key_for(photo)
+                FIT.remember(key, corners, frac, b.get("device"),
+                             ppath, (photo.shape[1], photo.shape[0]))
+                # ...and the portable half: a file beside the mockup, in the
+                # folder the user already chose. The store above is invisible and
+                # keyed on this machine's copy of the pixels; this one can be
+                # found in Finder, kept with the project, sent to someone, and
+                # dragged back in against a re-export the key would miss.
+                result["fit_file"] = FF.write(dest, FF.build(
+                    corners, frac, b.get("device"), ppath,
+                    (photo.shape[1], photo.shape[0]), key))
+                # Sidecar first, THEN the session output: /api/import reads that
+                # pointer and may be called the moment this returns, and the
+                # bug template asks for the sidecar first. Same publication order
+                # the render worker uses, and for the same reason.
                 _write_json_atomic(SESSION.result_path, result)
                 SESSION.update(output=dest)
                 return self._json(result)