screengraft 0.49.0 → 0.51.0

package/README.md

@@ -29,6 +29,10 @@ prototype, then put the recording inside a real photograph.
 - **Realism pass** *(optional)* — matches the screen's white balance and grain to
   the light in the room, and can lift the device's real reflections from a
   screen-off frame of the same shot.
+- **Depth of field** *(optional)* — a blur that grows across the screen in one
+  direction, glass edge included, so a screenshot on a phone shot at an angle
+  goes soft where the phone does. Direction and strength are yours; *Measure
+  from photo* proposes them from the photograph's own screen boundary.
 - **Emissive screens** *(optional)* — a display emits light *and* reflects the
   room, which is why a switched-off phone looks dark grey rather than black.
   Paint a true-black UI on flat and it reads as a hole cut in the photo. Turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.49.0",
+  "version": "0.51.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/dof.py

@@ -0,0 +1,231 @@
+"""Depth of field across the screen — a blur that grows in one direction.
+
+A phone photographed at an angle is a plane receding from the camera, so
+focus falls off *linearly across the quad*: sharp at the near edge, softer
+toward the far one. Two numbers describe it — the direction the blur grows in
+(`angle`, degrees, photo space, 0 = toward +x, 90 = toward +y) and how fast
+(`strength`, 0..1) — and both can be read off the photograph, because the
+bezel around the screen already carries the camera's own defocus.
+
+Blur is applied in PHOTO space, after the warp, to the premultiplied screen
+layer and its mask together (`blur_layer`). Blurring the layer alone would
+pull the black outside the quad into its edge and leave a sharp alpha edge
+inside a soft bezel — the tell in a bad mockup. Premultiplied, the edge
+softens exactly as the colour does.
+
+Spatially varying Gaussian: DOF_LEVELS blur levels, per pixel a linear blend
+of the two nearest. Standard, cheap (five separable blurs on the quad's
+window), and byte-identical to no blur at strength 0.
+"""
+import math
+
+import cv2
+import numpy as np
+
+DOF_LEVELS = 5          # sigma steps between 0 and sigma_max (0 is the identity)
+DOF_MAX_FRAC = 0.02     # strength 1.0 = sigma of 2% of the quad's longer side (16px on an 800px screen)
+
+
+def sigma_max(corners, strength: float) -> float:
+    """Blur at the far edge, in photo pixels, for a given strength."""
+    q = np.asarray(corners, dtype=np.float64)
+    side = max(np.linalg.norm(q[1] - q[0]), np.linalg.norm(q[2] - q[1]),
+               np.linalg.norm(q[3] - q[2]), np.linalg.norm(q[0] - q[3]))
+    return float(np.clip(strength, 0.0, 1.0)) * DOF_MAX_FRAC * float(side)
+
+
+def ramp(corners, angle_deg: float, x0: int, y0: int, w: int, h: int) -> np.ndarray:
+    """Per-pixel 0..1 distance along `angle` across the quad, over a window.
+
+    0 at the quad's nearest extent in that direction, 1 at its farthest; pixels
+    outside the quad clamp. The window is (x0, y0, w, h) in photo pixels.
+    """
+    a = math.radians(angle_deg)
+    d = np.array([math.cos(a), math.sin(a)], dtype=np.float64)
+    q = np.asarray(corners, dtype=np.float64)
+    proj = q @ d
+    lo, hi = float(proj.min()), float(proj.max())
+    if hi - lo < 1e-6:
+        return np.zeros((h, w), dtype=np.float32)
+    xs = np.arange(x0, x0 + w, dtype=np.float64)[None, :]
+    ys = np.arange(y0, y0 + h, dtype=np.float64)[:, None]
+    t = (xs * d[0] + ys * d[1] - lo) / (hi - lo)
+    return np.clip(t, 0.0, 1.0).astype(np.float32)
+
+
+def level_weights(t: np.ndarray, levels: int = DOF_LEVELS):
+    """Blend weights (levels, h, w): each pixel splits between its two nearest
+    sigma steps. Sums to 1 everywhere."""
+    pos = t * (levels - 1)
+    lo = np.floor(pos).astype(np.int32)
+    lo = np.clip(lo, 0, levels - 2)
+    f = (pos - lo).astype(np.float32)
+    W = np.zeros((levels,) + t.shape, dtype=np.float32)
+    rows, cols = np.indices(t.shape)
+    W[lo, rows, cols] = 1.0 - f
+    W[lo + 1, rows, cols] = f
+    return W
+
+
+def _blur(img: np.ndarray, sigma: float) -> np.ndarray:
+    if sigma <= 0.0:
+        return img
+    k = int(2 * math.ceil(3 * sigma) + 1)
+    return cv2.GaussianBlur(img, (k, k), sigma, borderType=cv2.BORDER_REPLICATE)
+
+
+class Field:
+    """Everything that does not change per frame: the ramp, the weights, the
+    blurred masks. `blur_layer` then costs `levels - 1` blurs of the colour."""
+
+    def __init__(self, corners, angle_deg: float, strength: float, mask: np.ndarray,
+                 x0: int, y0: int):
+        h, w = mask.shape[:2]
+        self.x0, self.y0 = x0, y0
+        self.smax = sigma_max(corners, strength)
+        self.sigmas = [self.smax * k / (DOF_LEVELS - 1) for k in range(DOF_LEVELS)]
+        t = ramp(corners, angle_deg, x0, y0, w, h)
+        self.W = level_weights(t)                       # (L, h, w)
+        m = mask.astype(np.float32) / 255.0
+        self.masks = [_blur(m, s) for s in self.sigmas]  # each (h, w)
+        self.alpha = np.zeros_like(m)
+        for k in range(DOF_LEVELS):
+            self.alpha += self.W[k] * self.masks[k]
+        self.alpha3 = np.repeat(self.alpha[:, :, None], 3, axis=2)
+
+    @property
+    def pad(self) -> int:
+        """How far the soft edge reaches outside the sharp mask."""
+        return int(math.ceil(3 * self.smax))
+
+    def blur_layer(self, colour: np.ndarray) -> np.ndarray:
+        """Blur a warped screen window (float32 BGR, h×w×3) by the field.
+
+        Premultiplied by the sharp mask, blurred per level, blended by the
+        weights, then un-premultiplied by the blended mask — so the colour at
+        a soft edge is the screen's own, not the screen mixed with whatever
+        the warp put outside the quad. (The warp replicates the edge outward,
+        so in practice that is nearly the screen's own colour already; the
+        premultiplication is what keeps it exact rather than nearly.)
+        """
+        m0 = self.masks[0][:, :, None]
+        pm = colour * m0
+        num = np.zeros_like(colour)
+        for k in range(DOF_LEVELS):
+            bk = pm if self.sigmas[k] <= 0.0 else _blur(pm, self.sigmas[k])
+            num += self.W[k][:, :, None] * bk
+        den = np.maximum(self.alpha3, 1e-4)
+        out = num / den
+        return np.where(self.alpha3 > 1e-4, out, colour)
+
+
+# ---------------------------------------------------------------- measure --
+
+DOF_PROFILE_HALF = 14   # px either side of the screen boundary to fit the step
+DOF_MIN_SPREAD = 1.6    # far-edge sigma / near-edge sigma below this = flat
+DOF_MIN_SIGMA = 0.9     # a step narrower than this is the render's own antialiasing
+
+
+def _edge_profiles(gray: np.ndarray, A, B, n, half: int, trim: float = 0.12):
+    """Intensity profiles ACROSS edge A→B, one column per sample point along
+    it, from `half` px inside the screen to `half` px outside, along the
+    outward unit normal `n`. Rectified with remap, so a tilted edge reads as
+    a straight step."""
+    A = np.asarray(A, dtype=np.float64); B = np.asarray(B, dtype=np.float64)
+    u = B - A
+    L = float(np.linalg.norm(u))
+    if L < 8:
+        return None
+    u /= L
+    s = np.linspace(trim * L, (1 - trim) * L, max(8, int((1 - 2 * trim) * L / 2)))
+    d = np.arange(-half, half + 1, dtype=np.float64)
+    xs = A[0] + s[None, :] * u[0] + d[:, None] * n[0]
+    ys = A[1] + s[None, :] * u[1] + d[:, None] * n[1]
+    return cv2.remap(gray.astype(np.float32), xs.astype(np.float32), ys.astype(np.float32),
+                     cv2.INTER_LINEAR, borderMode=cv2.BORDER_REFLECT)
+
+
+def step_sigma(profiles: np.ndarray) -> float:
+    """Blur of a step edge, in pixels, from profiles across it (rows = across,
+    columns = samples along the edge).
+
+    A step of amplitude A blurred by a Gaussian of sigma has a peak derivative
+    of A / (sigma * sqrt(2*pi)), so sigma = A / (sqrt(2*pi) * peak). Only the
+    DOMINANT transition in each column is read: the strongest gradient near
+    the boundary, with A taken between the plateaus 3 sigma-ish either side of
+    it. The second-moment estimate was tried first and saturated at ~5px on
+    sharp renders, because a ±14px profile crosses glass edge, bezel and body
+    and its derivative is spread over all three. Reduced by the median across
+    columns so a corner arc or a reflection on a few samples does not move it;
+    columns with no real step are left out.
+    """
+    smooth = cv2.GaussianBlur(profiles, (1, 3), 0.6)      # tame sensor noise along the profile
+    g = np.diff(smooth, axis=0)                            # (2*half, N)
+    ag = np.abs(g)
+    n_across, N = ag.shape
+    half = n_across // 2
+    lo_i, hi_i = max(1, half - 6), min(n_across - 1, half + 6)   # the boundary is near the centre
+    peak = lo_i + ag[lo_i:hi_i].argmax(axis=0)
+    out = []
+    for j in range(N):
+        pk = int(peak[j]); gm = float(ag[pk, j])
+        if gm < 1.5:
+            continue
+        # plateaus: 4..9 px either side of the peak, clamped to the profile
+        a0, a1 = max(0, pk - 9), max(0, pk - 4)
+        b0, b1 = min(n_across, pk + 5), min(n_across, pk + 10)
+        if a1 <= a0 or b1 <= b0:
+            continue
+        A = abs(float(smooth[b0:b1, j].mean()) - float(smooth[a0:a1, j].mean()))
+        if A < 12.0:                                      # no step worth reading
+            continue
+        out.append(A / (math.sqrt(2 * math.pi) * gm))
+    if len(out) < 4:
+        return 0.0
+    return float(np.median(out))
+
+
+def measure(photo: np.ndarray, corners) -> dict:
+    """Direction and strength of defocus from the screen's own boundary.
+
+    Four blur widths, one per edge (sigma in pixels, `step_sigma`), the
+    edge midpoints as positions → a plane sigma(x, y) = a·x + b·y + c by least
+    squares. The blur grows along the plane's gradient: angle = atan2(b, a).
+    Strength is the far edge's sigma against DOF_MAX_FRAC of the longer side,
+    which is what the blur uses, so a measured strength reproduces the measured
+    blur. Below DOF_MIN_SPREAD between the softest and sharpest edge the photo
+    is in focus across the screen (or uniformly soft, which is not depth of
+    field) and the answer is `flat`.
+    """
+    gray = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY) if photo.ndim == 3 else photo
+    q = np.asarray(corners, dtype=np.float64)
+    centre = q.mean(axis=0)
+    sig, mids = [], []
+    for i in range(4):
+        A, B = q[i], q[(i + 1) % 4]
+        u = B - A
+        n = np.array([-u[1], u[0]]) / max(np.linalg.norm(u), 1e-6)
+        mid = (A + B) / 2
+        if np.dot(n, centre - mid) > 0:     # pointing in: flip to outward
+            n = -n
+        prof = _edge_profiles(gray, A, B, n, DOF_PROFILE_HALF)
+        if prof is None:
+            continue
+        sg = step_sigma(prof)
+        if sg > 0.0:
+            sig.append(sg); mids.append(mid)
+    if len(sig) < 3:
+        return {"angle": 0.0, "strength": 0.0, "flat": True, "sigma": [round(v, 2) for v in sig]}
+    sig = np.array(sig); mids = np.array(mids)
+    lo = max(float(sig.min()), DOF_MIN_SIGMA)
+    spread = float(sig.max() / lo)
+    out = {"sigma": sig.round(2).tolist(), "spread": round(spread, 2)}
+    if spread < DOF_MIN_SPREAD:
+        out.update({"angle": 0.0, "strength": 0.0, "flat": True})
+        return out
+    Amat = np.column_stack([mids[:, 0], mids[:, 1], np.ones(len(mids))])
+    (a, b, c), *_ = np.linalg.lstsq(Amat, sig, rcond=None)
+    angle = math.degrees(math.atan2(b, a)) % 360.0
+    strength = float(np.clip((sig.max() - lo) / max(sigma_max(q, 1.0), 1e-6), 0.0, 1.0))
+    out.update({"angle": round(angle, 1), "strength": round(strength, 3), "flat": False})
+    return out

package/scripts/scan.py

@@ -53,7 +53,13 @@ def thumb(item, out_dir: str, size: int = 320):
     """Write a small JPEG thumbnail; returns its path or None."""
     os.makedirs(out_dir, exist_ok=True)
     base = os.path.splitext(item["name"])[0]
-    out = os.path.join(out_dir, f"{abs(hash(item['path']))}_{base[:40]}.jpg")
+    # The mtime is part of the name: a file overwritten in place gets a new
+    # thumbnail instead of the one made from its old bytes (12 Sep 2026).
+    try:
+        stamp = int(os.path.getmtime(item["path"]))
+    except OSError:
+        stamp = 0
+    out = os.path.join(out_dir, f"{abs(hash(item['path']))}_{stamp}_{base[:40]}.jpg")
     if os.path.exists(out):
         return out
     if sys.platform == "darwin":

package/scripts/ui.py

@@ -49,6 +49,7 @@ 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 dof as DOF   # noqa: E402
 import scan as S  # noqa: E402
 import warp as W  # noqa: E402
 
@@ -577,7 +578,8 @@ 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, kind="render",
-                   start_frame=0, max_frames=None, *, smoothing=0.0):
+                   start_frame=0, max_frames=None, *, smoothing=0.0,
+                   dof_angle=0.0, dof_strength=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
@@ -602,7 +604,8 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
                                            else reflection),
-                               start_frame=start_frame, max_frames=max_frames)
+                               start_frame=start_frame, max_frames=max_frames,
+                               dof_angle=dof_angle, dof_strength=dof_strength)
         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
@@ -664,6 +667,18 @@ def _blend_args(b):
     return "emissive", float(max(0.0, min(1.0, float(r))))
 
 
+def _dof_args(b):
+    """(dof_angle, dof_strength) from the page. Absent or null strength means
+    0 -- no field, and every path in Plan untouched -- so a client that predates
+    depth of field and a sidecar replayed through the CLI both reproduce."""
+    try:
+        strength = float(b.get("dof_strength") or 0.0)
+        angle = float(b.get("dof_angle") or 0.0)
+    except (TypeError, ValueError):
+        return 0.0, 0.0
+    return angle % 360.0, float(min(max(strength, 0.0), 1.0))
+
+
 ROLES = ("photo", "screenshot")
 
 
@@ -699,6 +714,15 @@ def _adopt(role, path):
         e = FIT.recall(FIT.key_for(im))
         if e:
             meta["remembered"] = e
+    # mtime rides along as the page's cache-buster: the same path with new
+    # bytes (imported, cleared, overwritten on disk, imported again) used to
+    # come back as the OLD picture in every <img> the browser had cached --
+    # chip swatch, popover preview, the canvas itself for a photo -- while the
+    # composite, which the server renders from disk, was already new.
+    try:
+        meta["mtime"] = int(os.path.getmtime(real))
+    except OSError:
+        meta["mtime"] = 0
     return {"path": real, "size": [im.shape[1], im.shape[0]], **meta}
 
 
@@ -941,6 +965,29 @@ class Handler(BaseHTTPRequestHandler):
                                     "with status=done.",
                 }))
 
+            if u.path == "/api/dof":
+                # Depth of field read off the photograph's own screen boundary:
+                # the direction the blur grows in and how far, from the blur
+                # width of each edge of the quad. `flat` means the bezel is
+                # sharp all round and the feature has nothing to match.
+                ppath = SESSION.state.get("photo")
+                if not ppath:
+                    return self._json({"error": "no photo chosen"}, 400)
+                photo, _ = _read_image(ppath)
+                corners = _quad(b["corners"])
+                return self._json(DOF.measure(photo, corners))
+
+            if u.path == "/api/job/cancel":
+                # The page gave up on a pending job. Marked, not deleted: the
+                # agent's complete_job then answers "already cancelled" instead
+                # of finding no job and guessing, and wait_for_job skips it.
+                job = SESSION.read_job()
+                if job and job.get("status") == "pending":
+                    job["status"] = "cancelled"
+                    job["completed"] = time.time()
+                    _write_json_atomic(SESSION.job_path, job)
+                return self._json(job or {"status": "none"})
+
             if u.path == "/api/job/adopt":
                 # page calls this once job.status == done, to make the export the screenshot
                 with open(SESSION.job_path) as f:
@@ -1129,7 +1176,9 @@ class Handler(BaseHTTPRequestHandler):
                                            gr, grain, "web", fit_frame,
                                            blend, reflection, None, "preview",
                                            fit_frame, max_frames),
-                                     kwargs={"smoothing": _smoothing(b)}).start()
+                                     kwargs={"smoothing": _smoothing(b),
+                                             "dof_angle": _dof_args(b)[0],
+                                             "dof_strength": _dof_args(b)[1]}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1163,6 +1212,7 @@ class Handler(BaseHTTPRequestHandler):
                 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)
+                dof_angle, dof_strength = _dof_args(b)
                 preset = "prores" if b.get("preset") == "prores" else "web"
                 ext = ".mov" if preset == "prores" else ".mp4"
                 os.makedirs(OUT_DIR, exist_ok=True)
@@ -1184,6 +1234,7 @@ class Handler(BaseHTTPRequestHandler):
                           "grade": gr, "grain": grain,
                           "video": True, "preset": preset, "fit_frame": fit_frame,
                           "blend": blend, "reflection": reflection,
+                          "dof_angle": dof_angle, "dof_strength": dof_strength,
                           # 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
@@ -1210,7 +1261,9 @@ class Handler(BaseHTTPRequestHandler):
                                      args=(photo, spath, corners, dest, radius_px,
                                            gr, grain, preset, fit_frame,
                                            blend, reflection, result),
-                                     kwargs={"smoothing": _smoothing(b)}).start()
+                                     kwargs={"smoothing": _smoothing(b),
+                                             "dof_angle": dof_angle,
+                                             "dof_strength": dof_strength}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1233,10 +1286,12 @@ class Handler(BaseHTTPRequestHandler):
                 gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
                 blend, reflection = _blend_args(b)
                 smoothing = _smoothing(b)
+                dof_angle, dof_strength = _dof_args(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)
+                                blend=blend, reflection=reflection,
+                                dof_angle=dof_angle, dof_strength=dof_strength)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
                 if u.path == "/api/preview":
@@ -1272,6 +1327,7 @@ class Handler(BaseHTTPRequestHandler):
                           "corner_smoothing": smoothing,
                           "grade": gr, "grain": bool(b.get("grain", gr > 0)),
                           "blend": blend, "reflection": reflection,
+                          "dof_angle": dof_angle, "dof_strength": dof_strength,
                           "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,

package/scripts/warp.py

@@ -37,6 +37,7 @@ import cv2
 import numpy as np
 
 import grade as _grade   # M2: the realism pass
+import dof as _dof       # depth of field across the screen
 
 
 MASK_SS = 4   # destination-space supersampling for the screen's edge
@@ -267,7 +268,8 @@ class Plan:
     def __init__(self, photo: np.ndarray, frame_shape, corners,
                  corner_radius: float = 0.0, grain: bool = False,
                  blend: str = "replace", reflection: float = DEFAULT_REFLECTION,
-                 corner_smoothing: float = 0.0):
+                 corner_smoothing: float = 0.0,
+                 dof_angle: float = 0.0, dof_strength: float = 0.0):
         dst_quad = np.array(corners, dtype=np.float32)
         if shoelace_area(dst_quad) < 1.0:
             raise ValueError("degenerate quad (near-zero area) — check corner order TL,TR,BR,BL")
@@ -313,9 +315,22 @@ class Plan:
         # Integer bbox of the quad, clamped to the canvas and padded by a pixel
         # so the antialiased edge is never clipped.
         xs, ys = dst_quad[:, 0], dst_quad[:, 1]
-        bx0, by0 = max(0, int(np.floor(xs.min())) - 1), max(0, int(np.floor(ys.min())) - 1)
-        bx1, by1 = min(pw, int(np.ceil(xs.max())) + 2), min(ph, int(np.ceil(ys.max())) + 2)
+        # Depth of field widens the window: the soft edge reaches 3 sigma past
+        # the sharp mask, and a window that clipped it would leave a hard line
+        # exactly where the blur was meant to remove one.
+        self.dof_strength = float(np.clip(dof_strength, 0.0, 1.0))
+        self.dof_angle = float(dof_angle)
+        reach = int(np.ceil(3 * _dof.sigma_max(dst_quad, self.dof_strength))) if self.dof_strength > 0 else 0
+        bx0, by0 = max(0, int(np.floor(xs.min())) - 1 - reach), max(0, int(np.floor(ys.min())) - 1 - reach)
+        bx1, by1 = min(pw, int(np.ceil(xs.max())) + 2 + reach), min(ph, int(np.ceil(ys.max())) + 2 + reach)
         self.bbox = (bx0, by0, bx1, by1) if bx1 > bx0 and by1 > by0 else None
+        # The field is built once: ramp, level weights, the blurred masks.
+        # At strength 0 there is no field and every path below is untouched,
+        # which is what keeps every earlier sidecar reproducing byte for byte.
+        self.dof = None
+        if self.dof_strength > 0 and self.bbox is not None:
+            self.dof = _dof.Field(dst_quad, self.dof_angle, self.dof_strength,
+                                  self.warped_mask[by0:by1, bx0:bx1], bx0, by0)
 
     def _prep(self, frame: np.ndarray, bbox=None) -> np.ndarray:
         """Warp one frame. With `bbox`, warp only that window of the canvas.
@@ -377,13 +392,21 @@ class Plan:
         simplest code is the one to trust, and on for video renders. Both
         produce identical bytes; test_video.py asserts it rather than assuming.
         """
-        if fast and self.bbox is not None:
+        # Depth of field always takes the windowed path: the field is built on
+        # the window, and the still and video renders must share one code
+        # path here for the same reason they share Plan.
+        if (fast or self.dof is not None) and self.bbox is not None:
             x0, y0, x1, y1 = self.bbox
             warped_screen = self._prep(frame, self.bbox)
             if self.grade_params is not None:
                 warped_screen = _grade.apply_light(warped_screen, self.grade_params)
             out = self.photo.copy()
             win = self.mask3[y0:y1, x0:x1]
+            if self.dof is not None:
+                # Blur colour and mask together, premultiplied, so the glass
+                # edge goes soft exactly as the far end of the bezel already is.
+                warped_screen = self.dof.blur_layer(warped_screen.astype(np.float32))
+                win = self.dof.alpha3
             pw = self.photo[y0:y1, x0:x1]
             src = self._blend(pw, warped_screen)
             out[y0:y1, x0:x1] = np.clip(
@@ -410,7 +433,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
             corner_smoothing: float = 0.0,
             grade: float = 0.0, grain: bool = False, screen_off: np.ndarray = None,
             specular: float = 0.75, blend: str = "replace",
-            reflection: float = DEFAULT_REFLECTION) -> np.ndarray:
+            reflection: float = DEFAULT_REFLECTION,
+            dof_angle: float = 0.0, dof_strength: float = 0.0) -> np.ndarray:
     """Warp `screenshot` into the quad `corners` (TL,TR,BR,BL, photo pixels) on `photo`.
 
     Single resampling pass at the photo's resolution; deterministic. This is the
@@ -423,7 +447,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
     # asserted byte-identical to this function's output.
     plan = Plan(photo, screenshot.shape, corners, corner_radius, grain=grain,
                 corner_smoothing=corner_smoothing,
-                blend=blend, reflection=reflection)
+                blend=blend, reflection=reflection,
+                dof_angle=dof_angle, dof_strength=dof_strength)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -510,7 +535,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   preset: str = "web", fit_frame: int = 0, audio: bool = True,
                   frames_dir: str = None, progress=None, blend: str = "replace",
                   reflection: float = DEFAULT_REFLECTION,
-                  start_frame: int = 0, max_frames: int = None) -> dict:
+                  start_frame: int = 0, max_frames: int = None,
+                  dof_angle: float = 0.0, dof_strength: float = 0.0) -> dict:
     """Inject a VIDEO into a still photo. The photo does not move, so there is
     exactly one homography and the whole of Plan is computed once.
 
@@ -537,7 +563,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
     first = read_frame_at(video_path, fit_frame)
     plan = Plan(photo, first.shape, corners, corner_radius, grain=grain,
                 corner_smoothing=corner_smoothing,
-                blend=blend, reflection=reflection)
+                blend=blend, reflection=reflection,
+                dof_angle=dof_angle, dof_strength=dof_strength)
     plan.bind_grade(first, grade)
 
     ph, pw = photo.shape[:2]

package/skills/inject-screenshot/SKILL.md

@@ -5,7 +5,7 @@ description: Injects a UI screenshot OR a screen recording onto a photographed d
 
 # Inject a screenshot onto a photographed device
 
-**What ships (v0.49):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
+**What ships (v0.51):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
 
 The geometry is exact (`warp.py`); the detection is advisory (`detect.py`) and the human corrects it. **When a detection is wrong and you want to know why**, ask for the candidate list: `POST /api/detect {"trace": true}` writes `<session>/candidates.json`, or run `python3 scripts/detect.py --photo P --out-corners /tmp/c.json --trace /tmp/t.json` (add `--click X,Y`). Every candidate quad is in there with its score and whether it was accepted, rejected, never reached, or filtered out by the click — which is what separates "the screen was never proposed" from "it was proposed and something else won".
 
@@ -13,6 +13,8 @@ The geometry is exact (`warp.py`); the detection is advisory (`detect.py`) and t
 
 **The realism pass ships and is ON by default** (`grade.py`): it matches the injected screen's white balance and grain to the light around it, at a strength the designer sets in the rail. It can also lift the device's real specular highlights from a screen-off reference frame, though the UI cannot supply one yet. Off is a first-class choice and keeps the screenshot's colour exactly — say so if the user is reviewing brand colour.
 
+**Depth of field** *(off by default)*: a phone shot at an angle is a plane receding from the camera, so its far end is softer than its near end, and a screenshot pasted pin-sharp across all of it gives the fake away. On, the screenshot blurs across the screen in one direction — **direction** (where the blur grows toward) and **strength** — and the glass edge softens with it. **Measure from photo** reads both off the photograph's own screen boundary; on a real photograph that works, on a *mockup template* the device is usually rendered sharp with the blur only on the background, so it answers "flat" and the designer sets it by eye. The measured strength is a floor (the estimator saturates around 5px of blur), never a ceiling. Suggest it when the photo has visible bokeh — a blurred hand, table edge or background — and the composite's screen looks pasted on. The live in-place playback cannot show it; the composite and Render preview do.
+
 **Video ships too.** The screen source can be a video (mp4/mov/webm) as well as a still — pick it exactly like a screenshot, choose which frame to match the edges on, **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, so placement and motion can be judged with no wait; **Render preview** composites a few seconds through the real pipeline when the grade, grain and true blend are what you need to see — and the primary button becomes **Render**. The photo does not move, so there is one homography and every frame gets the same geometry; the light match is measured once from the frame you fitted on, so the screen cannot pulse as the UI scrolls. Output is H.264 at CRF 16 (near-visually-lossless) or ProRes 422 HQ. This is what pairs with a prototype recording: record the prototype, then inject the recording into a real photograph.
 
 Still missing: **no ML detection** (measured, and it segments the phone body rather than the glass, so it is not shipped), **no occluder handling** — a finger or glare in front of the screen gets painted over — and **no camera motion**: the photo must be a still, so a clip of a moving phone is not this. Also, detection **abstains** rather than guessing when the background is itself neutral (a pale tiled floor, a plain wall); the edges get placed by hand there, which is normal, not a failure. Say so if any of it matters for the photo.
@@ -94,7 +96,7 @@ It parks until the user presses a button and returns within ~150 ms of the press
 
 | result | what to do |
 |---|---|
-| `status=job`, `job.type="figma_export"` | Extract `fileKey` and `nodeId` from `job.url` (`1-2` → `1:2`), export via the Figma MCP (`download_assets`, PNG, scale 3), save to `job.save_to`, then `complete_job(status="done", path=<saved file>)`. Re-arm. |
+| `status=job`, `job.type="figma_export"` | Extract `fileKey` and `nodeId` from `job.url` (`1-2` → `1:2`), export via the Figma MCP (`download_assets`, PNG, scale 3), save to `job.save_to`, then `complete_job(status="done", path=<saved file>)`. If `complete_job` answers that the job is already **cancelled**, the user pressed Cancel in the page — say so in one line and re-arm; do not retry. Re-arm. |
 | `status=job`, `job.type="present"` | `present_files` on `job.paths`, report what you checked in the composite (§3), then `complete_job(status="done")`. Re-arm. |
 | `status=timeout` | Nothing pressed yet. Call again to keep waiting. Re-arm two or three times, then stop and say you've stopped waiting — do not loop forever burning turns. |
 | `status=ui_closed` | The UI exited. Stop; say so. |

package/ui/index.html

@@ -384,6 +384,11 @@
   .seg button.sel{background:var(--raise);color:var(--ink);font-weight:600}
   .seg button.sel:hover{background:var(--raise-mid)}
   .seg button.sel:active{background:var(--raise-low);transform:none}
+  /* A toggle in the strip head. On = the raised surface every selected thing
+     on this page has (the segmented thumb, the device chip), off = a label. */
+  .striphead button[aria-pressed]{background:transparent;border-color:transparent;box-shadow:none;color:var(--mute)}
+  .striphead button[aria-pressed]:hover{color:var(--ink)}
+  .striphead button[aria-pressed="true"]{background:var(--raise);border-color:var(--edge);color:var(--ink);font-weight:600}
   /* Input chip (Figma 5:14 / 5:20). Surface and shadow are declared here rather
    than inherited from the base button rule, so the filled state is explicit and
    the .is-empty override below has something definite to override.
@@ -1044,7 +1049,7 @@
                end. Icon-only, so each carries an aria-label — a title alone
                names it for a mouse and not for a screen reader. -->
           <button class="sm icon" id="playlive" aria-label="Play the clip on the photo"
-                  title="Play the clip on the photo, right now. The browser applies the same four corners and corner radius, and approximates emissive with screen blending; the colour grade and grain are not in this view.">
+                  title="Play the clip on the photo, right now. The browser applies the same four corners and corner radius, and approximates emissive with screen blending; the colour grade, grain and depth of field are not in this view.">
             <svg viewBox="0 0 12 12" width="11" height="11" aria-hidden="true" focusable="false"><path d="M3 1.5 10 6 3 10.5Z" fill="currentColor"/></svg>
           </button>
           <button class="sm" id="playclip"
@@ -1108,6 +1113,35 @@
           </div>
           </div></div>
       </div>
+      <div class="sect" id="secDof" data-on="0">
+        <div class="sect-top">
+          <div class="sect-left">
+            <h4>Depth of field</h4>
+            <button class="info" type="button" aria-label="About depth of field"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path fill="currentColor" d="M8.36 1.01C12.06 1.2 15 4.26 15 8l-.01.36C14.8 12.06 11.74 15 8 15l-.36-.01C4.06 14.81 1.19 11.94 1.01 8.36L1 8c0-3.87 3.13-7 7-7l.36.01ZM8 2C4.69 2 2 4.69 2 8c0 3.31 2.69 6 6 6 3.31 0 6-2.69 6-6 0-3.31-2.69-6-6-6Zm.5 8l.5 0v1L7 11v-1h.5V7H7V6h1.5v4ZM7.9 4c.33 0 .6.27.6.6a.6.6 0 1 1-1.21 0c0-.33.28-.6.61-.6Z"/></svg><span class="tip" role="tooltip">A phone shot at an angle is a plane receding from the camera, so its far end is softer than its near end — and a screenshot pasted pin-sharp across all of it gives the fake away. On, the screenshot blurs across the screen in one direction, and the glass edge softens with it. Measure reads the direction and a starting strength off your photo's own bezel; the strength it finds is a floor, so raise it if the far end of the phone looks softer than the screen.</span></button>
+          </div>
+          <button class="switch" id="dofBtn" role="switch" aria-checked="false" aria-label="Depth of field">
+            <span class="sw-track"><span class="sw-handle"></span><span class="sw-grip"></span></span>
+          </button>
+        </div>
+        <div class="sect-body"><div class="sect-body-in">
+          <div style="display:grid;gap:var(--s2)">
+            <div style="display:flex;align-items:center;justify-content:space-between;gap:var(--s2)">
+              <span class="sm" style="color:var(--mute)">Blur grows toward</span>
+              <span class="sm" id="dofDirVal" style="font-variant-numeric:tabular-nums"></span>
+            </div>
+            <input type="range" id="dofDir" min="0" max="355" step="5" value="90" aria-label="Direction the blur grows in">
+            <div style="display:flex;align-items:center;justify-content:space-between;gap:var(--s2)">
+              <span class="sm" style="color:var(--mute)">Strength</span>
+              <span class="sm" id="dofStrVal" style="font-variant-numeric:tabular-nums"></span>
+            </div>
+            <input type="range" id="dofStr" min="0" max="1" step="0.05" value="0.3" aria-label="Blur strength at the far edge">
+            <div style="display:flex;align-items:center;gap:var(--s2)">
+              <button class="sm" id="dofMeasure" title="Read the direction and a starting strength off the photo's own bezel">Measure from photo</button>
+              <span class="status sm" id="dofSt" style="min-width:0"></span>
+            </div>
+          </div>
+          </div></div>
+      </div>
       <div class="sect" id="secEdge" data-on="1">
         <div class="sect-top">
           <div class="sect-left">
@@ -1136,6 +1170,7 @@
       <span class="lbl">Edge view</span>
       <span class="stepper dock-step"><button class="sm" id="stripOut">&minus;</button><button class="sm" id="stripIn">+</button></span>
       <span class="sm" id="stripZ" style="color:var(--mute);font-variant-numeric:tabular-nums"></span>
+      <button class="sm" id="stripHC" aria-pressed="false" title="Stretch the strip's own tonal range to full contrast. For a dark screen on a dark frame, where the boundary is a few levels apart. The strip only — the composite is untouched.">Contrast</button>
       <span class="spacer"></span>
       <span class="sm" id="stripSt" style="color:var(--mute)"></span>
     </div>
@@ -1174,8 +1209,8 @@
 
 <div class="pop" id="pop2">
   <h3>Screenshot to put on the screen</h3>
-  <p class="sub">A PNG/JPG of the UI — or paste a Figma frame link and Claude will export it for you.</p>
-  <div class="row" style="margin-bottom:8px"><input type="text" id="figma" placeholder="https://www.figma.com/design/…?node-id=…" style="flex:1"><button id="figmaBtn">Export from Figma</button></div>
+  <p class="sub">A PNG/JPG of the UI — or paste a Figma frame link and Claude will import it for you.</p>
+  <div class="row" style="margin-bottom:8px"><input type="text" id="figma" placeholder="https://www.figma.com/design/…?node-id=…" style="flex:1"><button id="figmaBtn">Import from Figma</button></div>
   <div class="status sm" id="figmaSt" style="margin-bottom:10px"></div>
   <div class="hintline" id="figmaHint" hidden style="margin-bottom:10px"></div>
   <div class="picker">
@@ -1387,6 +1422,9 @@ const api = async (p, body, raw) => {
   const j = await r.json(); if (!r.ok) throw new Error(j.error || r.statusText); return j;
 };
 const fileURL = p => '/file?path=' + encodeURIComponent(p);
+// A source's URL carries the file's mtime, so new bytes at an old path are
+// fetched rather than served from the browser's cache (see _adopt in ui.py).
+const srcURL = (p, v) => fileURL(p) + (v ? '&v=' + v : '');
 const st = {photo:null, shot:null, corners:null, frac:0, type:null, preset:null, measured:null,
             // Where the quad on screen came from: 'detected' | 'remembered' | 'restored'
             // | 'default'. The tool's contract is that it never presents a guess as a
@@ -1591,7 +1629,8 @@ function setChosen(role, path, size, el, meta){
   if (el) el.classList.add('sel');
   // A video cannot be shown by <img>, so a clip gets its poster frame instead.
   const thumb = (meta && meta.poster) ? meta.poster : path;
-  $('#pv'+n).innerHTML = `<img src="${fileURL(thumb)}" alt="">`;
+  const ver = (meta && meta.mtime) || Date.now();
+  $('#pv'+n).innerHTML = `<img src="${srcURL(thumb, ver)}" alt="">`;
   const chip = $('#chip'+n);
   chip.classList.remove('is-empty');
   // The file's own name and nothing else. The size and, for a clip, the frame
@@ -1607,14 +1646,16 @@ function setChosen(role, path, size, el, meta){
   if ((role==='photo' ? st.photo : st.shot) !== path) dropResult();
   chip.title = `${homePath(path)}\n${size[0]}×${size[1]}`
     + (meta && meta.video ? ` · ${meta.frames} frames @ ${Math.round(meta.fps)}fps` : '');
-  $('#sw'+n).style.background = `center/cover no-repeat url("${fileURL(thumb)}")`;
+  $('#sw'+n).style.background = `center/cover no-repeat url("${srcURL(thumb, ver)}")`;
   $('#clear'+n).hidden = false;
   // A fit the server recognised from this photograph's own pixels. Held
   // rather than applied here: the quad only means anything once there is a
   // screenshot to put inside it, which is what maybeStart() waits for.
-  if (role==='photo'){ st.photo = path; st.corners = null;
+  if (role==='photo'){ st.photo = path; st.photoV = ver; st.corners = null;
     st.remembered = (meta && meta.remembered) || null; }
-  else { st.shot = path; st.shotSize = size; st.video = meta && meta.video ? meta : null; syncVideoUI();
+  else { st.shot = path; st.shotV = ver; st.shotSize = size; st.video = meta && meta.video ? meta : null; syncVideoUI();
+    // The status line may still be narrating the clear ("Screenshot removed…").
+    if (st.corners){ $('#detSt').className = 'status ok'; $('#detSt').textContent = 'Screenshot changed — the fit on the photo is kept'; }
     // A detected quad is re-oriented for the new screenshot; a remembered or
     // hand-placed one is somebody's decision and is left alone.
     if (st.corners && st.quadFrom === 'detected' && orientQuad()){ draw(); drawStrip(); autoPreview(); } }
@@ -1687,6 +1728,7 @@ async function awaitJob({onDone, onError, cancelled}) {
     if (cancelled()) return;
     if (j.status === 'done') return onDone(j);
     if (j.status === 'error') return onError(j);
+    if (j.status === 'cancelled') return;   // this page cancelled it (or another tab did)
     if (j.status === 'none') {
       // The job file is gone — a wiped session, or a restarted server. The
       // server answers 'none' instantly, so looping on it would spin as fast
@@ -1696,16 +1738,37 @@ async function awaitJob({onDone, onError, cancelled}) {
     // 'pending' with waited:true — the long poll timed out server-side; go again.
   }
 }
+/* Import from Figma. One button, two jobs: it starts the import, and while
+   the import is pending it reads "Cancel" and stops it — before this the only
+   way out of a pending import was to reload the page (12 Sep 2026). Cancelling
+   tells the server to mark the job cancelled, so an agent that is still
+   exporting gets "already cancelled" from complete_job instead of landing a
+   file on a request nobody is waiting for. */
+let figmaInFlight = null;   // {stop} while an import is pending
 $('#figmaBtn').onclick = async () => {
+  const s = $('#figmaSt'), hint = $('#figmaHint'), btn = $('#figmaBtn');
+  if (figmaInFlight){
+    const inflight = figmaInFlight;
+    try { await api('/api/job/cancel', {}); } catch (e) { /* already finished — the poll will say */ }
+    inflight.stop('', 'Import cancelled.');
+    return;
+  }
   const url = $('#figma').value.trim(); if (!url) return;
-  const s = $('#figmaSt'), hint = $('#figmaHint');
-  const btn = $('#figmaBtn'); btn.disabled = true;
+  // Only a Figma frame link can be imported, and the job is answered by the
+  // agent, so a wrong URL used to cost a full round trip before anyone saw it
+  // (12 Sep 2026: the workbench's own address was pasted and went out as a job).
+  if (!/^https:\/\/(www\.)?figma\.com\/(design|board|slides|file)\/[^/?#]+/.test(url) || !/node-id=\d+[-:]\d+/.test(url)){
+    s.className = 'status sm err';
+    s.textContent = 'That is not a Figma frame link. Copy the link from Figma (Share → Copy link, or right-click the frame → Copy link) — it needs node-id=… in it.';
+    return;
+  }
   const t0 = Date.now();
   let finished = false;
+  btn.textContent = 'Cancel'; btn.title = 'Stop waiting for this import';
   const paint = () => {
     const el = Math.round((Date.now() - t0) / 1000);
     s.className = 'status sm busy';
-    s.innerHTML = `Exporting from Figma <span class="el">${el}s</span>`;
+    s.innerHTML = `Importing from Figma <span class="el">${el}s</span>`;
     if (el >= NUDGE_AFTER && hint.hidden) {
       hint.hidden = false;
       hint.innerHTML = 'Taking longer than usual. Claude picks this up automatically while it\'s ' +
@@ -1720,26 +1783,33 @@ $('#figmaBtn').onclick = async () => {
   // return so the number is right the moment the designer looks at it again.
   document.addEventListener('visibilitychange', paint);
   const stop = (cls, text) => {
-    finished = true;
+    if (finished) return;
+    finished = true; figmaInFlight = null;
     clearInterval(tick);
     document.removeEventListener('visibilitychange', paint);
-    btn.disabled = false; hint.hidden = true;
+    btn.textContent = 'Import from Figma'; btn.title = '';
+    hint.hidden = true;
     s.className = 'status sm ' + cls; s.textContent = text;
-    // The popover is usually closed by now — the in-place line would go unread.
-    toast(cls === 'ok' ? 'ok' : 'err', cls === 'ok' ? 'Screenshot exported from Figma.' : text);
+    // ONE channel. While the picker is open the line under the field is in
+    // view, and a toast on top of it said the same sentence twice, overlapping
+    // the popover (12 Sep 2026). A toast only when the popover is closed and
+    // the line would go unread.
+    if (!$('#pop2').classList.contains('on') && cls)
+      toast(cls === 'ok' ? 'ok' : 'err', cls === 'ok' ? 'Screenshot imported from Figma.' : text);
   };
+  figmaInFlight = {stop};
   try { await api('/api/figma', {url}); }
-  catch (e) { return stop('err', 'Could not queue the export: ' + e.message); }
+  catch (e) { return stop('err', 'Could not start the import: ' + e.message); }
   await awaitJob({
     cancelled: () => finished,
     onDone: async () => {
       try {
         const r = await api('/api/job/adopt', {});
-        stop('ok', 'Exported');
+        stop('ok', 'Imported');
         setChosen('screenshot', r.path, r.size, null, r);
-      } catch (e) { stop('err', 'Exported, but the file could not be read: ' + e.message); }
+      } catch (e) { stop('err', 'Imported, but the file could not be read: ' + e.message); }
     },
-    onError: (j) => stop('err', 'Export failed: ' + (j.message || '')),
+    onError: (j) => stop('err', 'Import failed: ' + (j.message || '')),
   });
 };
 
@@ -1814,7 +1884,7 @@ async function maybeStart(){
     else if (st.remembered) applyRemembered();
     else detect();
   };
-  img.src = fileURL(st.photo);
+  img.src = srcURL(st.photo, st.photoV);
 }
 function computeFit(){
   const box = $('#scroller');
@@ -2461,9 +2531,104 @@ $('#emisAmt').oninput  = e => { emisAmt = parseFloat(e.target.value); paintEmis(
 $('#emisAmt').onchange = e => { setEmis(true, parseFloat(e.target.value)); autoPreview(); };
 
 
+/* Depth of field: a blur that grows across the screen in one direction, and
+   the glass edge softening with it (dof.py). Off sends nothing, so the engine
+   takes the byte-identical path it took before the feature existed. The
+   direction and strength are the designer's numbers; Measure proposes them
+   from the photograph's own bezel and says how far it can be trusted — the
+   measured strength is a floor (the estimator saturates around 5px of blur),
+   never a ceiling. The live layer cannot show it; the composite does. */
+let dofOn  = recall('dof','0') === '1';
+let dofAng = parseFloat(recall('dofAng','90')) || 0;
+let dofStr = parseFloat(recall('dofStr','0.3')); if (!(dofStr >= 0)) dofStr = 0.3;
+function dofAngle(){ return dofOn ? dofAng : 0; }
+function dofStrength(){ return dofOn ? dofStr : 0; }
+function dofWord(a){
+  const names = ['the right','the bottom-right','the bottom','the bottom-left','the left','the top-left','the top','the top-right'];
+  return names[Math.round(((a % 360) + 360) % 360 / 45) % 8];
+}
+function paintDof(){
+  setSwitch($('#dofBtn'), dofOn);
+  $('#dofDirVal').textContent = `${dofWord(dofAng)} · ${Math.round(dofAng)}°`;
+  $('#dofStrVal').textContent = Math.round(dofStr * 100) + '%';
+  const d = $('#dofDir'); d.value = Math.round(dofAng / 5) * 5; d.style.setProperty('--p', (dofAng % 360) / 355);
+  const st = $('#dofStr'); st.value = dofStr; st.style.setProperty('--p', dofStr);
+}
+function setDof(on, ang, str){
+  dofOn = on;
+  if (ang !== undefined) dofAng = ((ang % 360) + 360) % 360;
+  if (str !== undefined) dofStr = Math.max(0, Math.min(1, str));
+  remember('dof', on ? '1' : '0'); remember('dofAng', String(dofAng)); remember('dofStr', String(dofStr));
+  setSectionOpen($('#secDof'), on);
+  paintDof();
+}
+let dofMeasuredFor = null;   // photo path the last measurement was for
+async function measureDof(){
+  const s = $('#dofSt');
+  if (!(st.photo && st.corners)){ s.className = 'status sm'; s.textContent = 'Fit the screen first.'; return; }
+  s.className = 'status sm busy'; s.textContent = 'Measuring…';
+  try {
+    const r = await api('/api/dof', {corners: st.corners});
+    dofMeasuredFor = st.photo;
+    if (r.flat){
+      s.className = 'status sm'; s.textContent = 'The bezel is sharp all round — nothing to match. Set by eye if you want it anyway.';
+      s.title = `Edge blur ${(r.sigma || []).map(v => v.toFixed(1)).join(' / ')}px`;
+      autoPreview();   // still on, at the slider's own numbers
+      return;
+    }
+    setDof(true, r.angle, Math.max(r.strength, 0.05));
+    s.className = 'status sm ok';
+    s.textContent = `Measured: grows toward ${dofWord(r.angle)}. Strength is a floor — raise it if the far end looks softer.`;
+    s.title = `Edge blur ${r.sigma.map(v => v.toFixed(1)).join(' / ')}px, spread ${r.spread}×`;
+    autoPreview();
+  } catch (e) { s.className = 'status sm err'; s.textContent = 'Could not measure: ' + e.message; }
+}
+$('#dofBtn').onclick = () => {
+  setDof(!dofOn);
+  // First time on for this photograph: propose from the photo rather than
+  // from a remembered slider position that belongs to another one.
+  if (dofOn && dofMeasuredFor !== st.photo && st.corners) measureDof(); else autoPreview();
+};
+$('#dofDir').oninput  = e => { dofAng = parseFloat(e.target.value); paintDof(); };
+$('#dofDir').onchange = e => { setDof(true, parseFloat(e.target.value)); autoPreview(); };
+$('#dofStr').oninput  = e => { dofStr = parseFloat(e.target.value); paintDof(); };
+$('#dofStr').onchange = e => { setDof(true, undefined, parseFloat(e.target.value)); autoPreview(); };
+$('#dofMeasure').onclick = measureDof;
+
 $('#edgeBtn').onclick = () => setLoupeMode(loupeMode === 'float' ? 'dock' : 'float');
 
-function paintStrip(c, W, H, i){
+/* Contrast for the strip only. A dark screen on a dark frame puts the
+   boundary a few levels apart — 8 against 20 — which is invisible at any
+   zoom, and no amount of magnification adds contrast. This takes the strip's
+   own 1st–99th percentile of luminance and stretches it to 0–255, the same
+   gain on every channel so hue is kept. It is a viewing aid: the composite,
+   the fit and the saved file never see it. Per strip, per frame — 1280×130
+   is 166k pixels and this runs on every hover. */
+let stripHC = recall('stripHC','0') === '1';
+function stretchContrast(c, W, H){
+  const im = c.getImageData(0, 0, W, H), d = im.data, n = W*H;
+  const hist = new Uint32Array(256);
+  for (let k = 0; k < n; k++){
+    const o = k*4;
+    hist[(d[o]*77 + d[o+1]*151 + d[o+2]*28) >> 8]++;
+  }
+  let lo = 0, hi = 255, acc = 0;
+  for (let v = 0; v < 256; v++){ acc += hist[v]; if (acc > n*0.01){ lo = v; break; } }
+  acc = 0;
+  for (let v = 255; v >= 0; v--){ acc += hist[v]; if (acc > n*0.01){ hi = v; break; } }
+  if (hi - lo < 2) return;
+  const g = 255 / (hi - lo);
+  const lut = new Uint8ClampedArray(256);
+  for (let v = 0; v < 256; v++) lut[v] = Math.max(0, Math.min(255, (v - lo) * g));
+  for (let o = 0; o < n*4; o += 4){ d[o] = lut[d[o]]; d[o+1] = lut[d[o+1]]; d[o+2] = lut[d[o+2]]; }
+  c.putImageData(im, 0, 0);
+}
+function setStripHC(on){
+  stripHC = on; remember('stripHC', on ? '1' : '0');
+  $('#stripHC').setAttribute('aria-pressed', on ? 'true' : 'false');
+}
+$('#stripHC').onclick = () => { setStripHC(!stripHC); drawStrip(); };
+function paintStrip(c, W, H, i, mode){
   c.setTransform(1,0,0,1,0,0);
   c.fillStyle = '#0c0c0b'; c.fillRect(0,0,W,H);
   const A = st.corners[i], B = st.corners[(i+1)%4];
@@ -2478,7 +2643,25 @@ function paintStrip(c, W, H, i){
   c.imageSmoothingEnabled = true;
   c.drawImage(img, 0, 0);
   c.restore();
+  if (stripHC) stretchContrast(c, W, H);
   cased(c, () => { c.beginPath(); c.moveTo(0, H/2); c.lineTo(W, H/2); }, 1.25, CORE_ACTIVE);
+  // Which end is about to swing. The canvas shows this with the pivot pips,
+  // but the eye is on the strip while an edge is being placed, and "rotA" /
+  // "rotB" are meaningless there without a mark. A grab near one end pivots
+  // on the OTHER: the pivot end gets the same filled pip the canvas uses, the
+  // swinging end a double arrow across the rule. Translate marks nothing —
+  // both ends move. Left in the strip is A, the edge's first corner.
+  if (mode === 'rotA' || mode === 'rotB'){
+    // At 0.16 / 0.84 of the edge: where the canvas draws its pips, and clear
+    // of the screen/outside labels at the left edge.
+    const pivotX = mode === 'rotA' ? W*0.16 : W*0.84, swingX = mode === 'rotA' ? W*0.84 : W*0.16;
+    casedDisc(c, pivotX, H/2, 3.5, CORE_ACTIVE);
+    cased(c, () => { c.beginPath();
+      c.moveTo(swingX, H/2 - 22); c.lineTo(swingX, H/2 + 22);
+      c.moveTo(swingX - 5, H/2 - 16); c.lineTo(swingX, H/2 - 22); c.lineTo(swingX + 5, H/2 - 16);
+      c.moveTo(swingX - 5, H/2 + 16); c.lineTo(swingX, H/2 + 22); c.lineTo(swingX + 5, H/2 + 16); },
+      1.5, CORE_ACTIVE);
+  }
   cased(c, () => { c.beginPath();
     for (const f of [0.25,0.5,0.75]){ c.moveTo(W*f, H/2-9); c.lineTo(W*f, H/2+9); } },
     1, 'rgba(255,255,255,.7)');
@@ -2488,6 +2671,11 @@ function paintStrip(c, W, H, i){
   casedText(c, 'screen', 9, inwardIsDown ? H/2 + 15 : H/2 - 15, 'rgba(255,255,255,.95)');
   casedText(c, 'outside', 9, inwardIsDown ? H/2 - 15 : H/2 + 15, 'rgba(255,255,255,.62)');
 }
+function swingText(mode){
+  if (mode === 'rotA') return 'the right end swings, pivot on the left';
+  if (mode === 'rotB') return 'the left end swings, pivot on the right';
+  return 'flat on the rule means aligned';
+}
 function drawStrip(){
   const a = drag || hover || pick;
   const has = !!(st.corners && a && a.kind === 'edge' && img.naturalWidth);
@@ -2500,13 +2688,13 @@ function drawStrip(){
       $('#stripSt').textContent = 'Hover or drag an edge — this straightens it, so misalignment shows as a wedge.';
       return;
     }
-    paintStrip(sctx, W, H, a.i);
-    $('#stripSt').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px · ${(H/(2*stripHalf)).toFixed(1)}× across the boundary — flat on the rule means aligned`;
+    paintStrip(sctx, W, H, a.i, a.mode);
+    $('#stripSt').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px · ${(H/(2*stripHalf)).toFixed(1)}× across the boundary — ${swingText(a.mode)}`;
   } else {
     const fl = $('#floatLoupe');
     if (!has){ fl.classList.remove('on'); return; }
-    paintStrip(fctx, stripF.width, stripF.height, a.i);
-    $('#stripFCap').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px — flat on the rule means aligned`;
+    paintStrip(fctx, stripF.width, stripF.height, a.i, a.mode);
+    $('#stripFCap').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px — ${swingText(a.mode)}`;
     fl.classList.add('on');
     const w = fl.offsetWidth || 356, h = fl.offsetHeight || 130;
     let x = lastPointer[0] + 26, y = lastPointer[1] - h - 18;
@@ -2653,6 +2841,9 @@ function showResult(what){
      geometry       — exact, the same four corners the render uses
      corner radius  — applied in the video's own pixel space, before the warp,
                       which is where compose() applies it
+     depth of field — ABSENT. A blur that grows across the screen has no
+                      CSS equivalent that follows a homography; the composite
+                      is the only view that shows it.
      emissive       — APPROXIMATED with `screen` blending. Same idea (the
                       screen's light plus the glass beneath it), not the same
                       arithmetic as compose()'s emissive.
@@ -2749,10 +2940,10 @@ async function playLive(){
   if (!(st.photo && st.shot && st.corners && st.video)) return;
   if (!$('#liveWrap').hidden && !$('#liveVid').paused) return stopLive();
   const v = $('#liveVid'), s = $('#outSt');
-  $('#liveBg').src = fileURL(st.photo);
+  $('#liveBg').src = srcURL(st.photo, st.photoV);
   if (!v.src || v.dataset.src !== st.shot){
     v.dataset.src = st.shot;
-    v.src = fileURL(st.shot);
+    v.src = srcURL(st.shot, st.shotV);
   }
   showResult('live');
   await new Promise(r => {
@@ -2799,7 +2990,7 @@ async function playClip(){
   // a preview the user did not ask for, and the wait goes silent again.
   building = true;
   try{
-    await api('/api/preview_video', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(),
+    await api('/api/preview_video', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(),
                                      device: st.type, grade: gradeValue(),
                                      reflection: emisValue(), fit_frame: +$('#vframe').value});
   }catch(e){
@@ -2858,7 +3049,7 @@ async function renderPreview(){
   const say = t => { if (!building && $('#liveWrap').hidden) s.textContent = t; };
   say('Rendering…');
   try{
-    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), device: st.type, grade: gradeValue(), reflection: emisValue()});
+    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => {
       outNat = im.naturalWidth;
@@ -2988,7 +3179,7 @@ async function renderVideo(){
   b.disabled = true;
   setRenderProgress(0);
   try{
-    await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), device: st.type,
+    await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), device: st.type,
                               grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){
     setRenderProgress(null);
@@ -3034,7 +3225,7 @@ $('#save').onclick = async () => {
   if (st.video) return renderVideo();
   const b = $('#save'); b.textContent = 'Saving…'; b.disabled = true;
   try{
-    const r = await api('/api/save', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), device: st.type, grade: gradeValue(), reflection: emisValue()});
+    const r = await api('/api/save', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     b.textContent = saveLabel();
     // The real destination, not a hardcoded one: --out-dir means saves usually
     // land in the project folder now, and telling the user "~/Desktop" when
@@ -3110,8 +3301,10 @@ $('#imp').onclick = async () => {
     b.onclick=()=>{setType(t); applyPreset(); autoPreview();}; types.appendChild(b);
   }
   setLoupeMode(loupeMode);
+  setStripHC(stripHC);
   setGrade(gradeOn, gradeAmt);
   setEmis(emisOn, emisAmt);
+  setDof(dofOn, dofAng, dofStr);
   setRadiusOn(radiusOn);
   sectionsBooted = true;   // animate from here on, not during the first paint
   // Compare is the DEFAULT view: judging a fit means comparing it with the