screengraft 0.50.0 → 0.52.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.50.0",
+  "version": "0.52.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,237 @@
+"""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,
+         start: float = 0.0) -> np.ndarray:
+    """Per-pixel 0..1 blur fraction along `angle` across the quad, over a window.
+
+    `start` (0..1) is where focus ends and the blur begins, as a fraction of
+    the quad's extent along the direction: 0 at the nearest extent (the whole
+    screen ramps, the default), 0.5 sharp across the near half then ramping.
+    1 at the farthest extent; 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())
+    start = float(np.clip(start, 0.0, 0.95))
+    lo = lo + start * (hi - lo)
+    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, start: float = 0.0):
+        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, start)
+        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, dof_start=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,9 @@ 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,
+                               dof_start=dof_start)
         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 +668,20 @@ def _blend_args(b):
     return "emissive", float(max(0.0, min(1.0, float(r))))
 
 
+def _dof_args(b):
+    """(dof_angle, dof_strength, dof_start) 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. `start` absent means 0: the whole screen ramps."""
+    try:
+        strength = float(b.get("dof_strength") or 0.0)
+        angle = float(b.get("dof_angle") or 0.0)
+        start = float(b.get("dof_start") or 0.0)
+    except (TypeError, ValueError):
+        return 0.0, 0.0, 0.0
+    return angle % 360.0, float(min(max(strength, 0.0), 1.0)), float(min(max(start, 0.0), 0.95))
+
+
 ROLES = ("photo", "screenshot")
 
 
@@ -699,6 +717,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 +968,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 +1179,10 @@ 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],
+                                             "dof_start": _dof_args(b)[2]}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1163,6 +1216,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_start = _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 +1238,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, "dof_start": dof_start,
                           # 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 +1265,10 @@ 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,
+                                             "dof_start": dof_start}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1233,10 +1291,13 @@ 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_start = _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,
+                                dof_start=dof_start)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
                 if u.path == "/api/preview":
@@ -1272,6 +1333,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, "dof_start": dof_start,
                           "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, dof_start: 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,24 @@ 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)
+        self.dof_start = float(np.clip(dof_start, 0.0, 0.95))
+        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,
+                                  start=self.dof_start)
 
     def _prep(self, frame: np.ndarray, bbox=None) -> np.ndarray:
         """Warp one frame. With `bbox`, warp only that window of the canvas.
@@ -377,13 +394,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 +435,9 @@ 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,
+            dof_start: 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 +450,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, dof_start=dof_start)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -510,7 +538,9 @@ 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,
+                  dof_start: 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 +567,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, dof_start=dof_start)
     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.50):** 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.52):** 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. **The gizmo on the result** is the primary control: a solid line over the screen where focus ends (drag to move, its end pips to turn), a dashed line where the blur reaches ~6px (drag closer for stronger, further for gentler); it fades when the pointer leaves the pane. The sliders and the gizmo are one model. 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

@@ -625,6 +625,22 @@
 
   #outPane{display:grid}
   #outWrap{overflow:auto;background:var(--well);display:grid;box-shadow:inset 0 1px 3px rgba(0,0,0,.5)}
+  /* The depth-of-field gizmo: an SVG laid exactly over the composite, drawn
+     in PHOTO pixels (its viewBox is the photo) so every coordinate is the
+     engine's own. Faint until the pointer is over the pane, so it never sits
+     on the composite being judged; solid while a handle is being dragged. */
+  #outWrap{position:relative}
+  #dofGizmo{position:absolute;pointer-events:none;opacity:.4;transition:opacity .15s;overflow:visible}
+  #outWrap:hover #dofGizmo,#dofGizmo.drag{opacity:1}
+  #dofGizmo .case{stroke:rgba(0,0,0,.6);fill:none;vector-effect:non-scaling-stroke}
+  #dofGizmo .focus{stroke:#f5623d;stroke-width:1.5;fill:none;vector-effect:non-scaling-stroke}
+  #dofGizmo .far{stroke:#f5623d;stroke-width:1.25;stroke-dasharray:6 6;fill:none;vector-effect:non-scaling-stroke}
+  #dofGizmo .far.out{stroke-dasharray:3 7;opacity:.75}
+  #dofGizmo .h{fill:#f5623d;stroke:#fff;stroke-width:1.5;vector-effect:non-scaling-stroke;pointer-events:auto;cursor:grab}
+  #dofGizmo .h.hollow{fill:#1a1a1a}
+  #dofGizmo .h.pip{fill:#f5623d}
+  #dofGizmo .h:active{cursor:grabbing}
+  #dofGizmo text{font:600 11px system-ui,-apple-system,sans-serif;fill:#fff;paint-order:stroke;stroke:rgba(0,0,0,.75);stroke-width:3px;stroke-linejoin:round;pointer-events:none}
   #outImg,#outVid{display:block;margin:auto}
   /* The live layer stacks the clip on the photo. `position:relative` on the
      wrapper and `transform-origin:0 0` on the video are what make the matrix3d
@@ -1023,7 +1039,7 @@
         <span class="spacer"></span>
         <span class="sm" style="color:var(--mute)">shares zoom &amp; pan</span>
       </div>
-      <div id="outWrap"><span class="empty" id="outEmpty">The composite appears here and updates as you drag.</span><img id="outImg" alt="" hidden><video id="outVid" hidden loop muted playsinline controls></video><!--
+      <div id="outWrap"><span class="empty" id="outEmpty">The composite appears here and updates as you drag.</span><img id="outImg" alt="" hidden><video id="outVid" hidden loop muted playsinline controls></video><svg id="dofGizmo" hidden aria-label="Depth of field: drag the solid line to place focus, its ends to turn it, the dashed line for strength"></svg><!--
         The live layer: the PHOTOGRAPH with the source clip warped onto the
         fitted quad by the browser. Not the composite — the composite already
         has a frame burned into it, so playing over that would show two screens.
@@ -1049,7 +1065,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"
@@ -1113,6 +1129,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">
@@ -1180,8 +1225,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">
@@ -1393,6 +1438,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
@@ -1597,7 +1645,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
@@ -1613,14 +1662,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(); } }
@@ -1693,6 +1744,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
@@ -1702,16 +1754,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 ' +
@@ -1726,26 +1799,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 || '')),
   });
 };
 
@@ -1820,7 +1900,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');
@@ -2467,6 +2547,179 @@ $('#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;
+let dofStart = parseFloat(recall('dofStart','0')); if (!(dofStart >= 0)) dofStart = 0;
+function dofAngle(){ return dofOn ? dofAng : 0; }
+function dofStrength(){ return dofOn ? dofStr : 0; }
+function dofStartV(){ return dofOn ? dofStart : 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)); remember('dofStart', String(dofStart));
+  setSectionOpen($('#secDof'), on);
+  paintDof();
+  paintGizmo();
+}
+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;
+    }
+    dofStart = 0; 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;
+
+/* ===== the depth-of-field gizmo ============================================
+   Two lines over the composite, the graduated-filter idiom (Lightroom's
+   gradient, Photoshop's tilt-shift). The SOLID line is where focus ends and
+   the blur begins; the DASHED line is where the blur reaches a REFERENCE
+   softness, GIZMO_REF of the engine's full blur (sigma_full = DOF_MAX_FRAC of
+   the screen's longer side) -- 30%, about 6px on a phone, the point where
+   text stops being readable. Not full blur: at 50% strength the full-blur
+   line sat three quarters of a screen above the phone, off the photograph
+   and out of reach. Drag the solid line's centre to move focus, either end
+   pip to turn both lines (direction), the dashed line's centre to set how
+   fast the blur grows (strength). The dashed line may still sit past the far
+   edge for a gentle falloff, drawn out over the photograph and capped at
+   GIZMO_FAR_MAX extents; gentler than that is the slider's job.
+   Mapping, so the gizmo and the sliders are one model:
+     start    = solid line's position, 0..0.95 of the quad's extent along the direction
+     strength = GIZMO_REF * (1 - start) / (far - start)   -- far = dashed line's position
+   Everything is drawn in PHOTO pixels: the SVG's viewBox is the photo, so no
+   coordinate here is converted, and it stays aligned at every zoom for free. */
+const gz = $('#dofGizmo');
+const SIGMA_FULL_FRAC = 0.02;   // mirrors dof.DOF_MAX_FRAC -- keep in step
+const GIZMO_REF = 0.3;          // the dashed line marks this fraction of full blur
+const GIZMO_FAR_MAX = 1.6;      // the dashed line is drawn no further than this many extents
+function gizmoGeom(){
+  const C = st.corners, a = dofAng * Math.PI / 180;
+  const d = [Math.cos(a), Math.sin(a)], u = [-d[1], d[0]];
+  const pd = C.map(c => c[0]*d[0] + c[1]*d[1]), pu = C.map(c => c[0]*u[0] + c[1]*u[1]);
+  const lo = Math.min(...pd), hi = Math.max(...pd), ulo = Math.min(...pu), uhi = Math.max(...pu);
+  const side = Math.max(vlen(sub(C[1],C[0])), vlen(sub(C[2],C[1])), vlen(sub(C[3],C[2])), vlen(sub(C[0],C[3])));
+  return {d, u, lo, hi, ulo, uhi, side};
+}
+// a line at fraction f along d, spanning the quad's extent along u (padded)
+function gizmoLine(g, f, pad){
+  const c = g.lo + f * (g.hi - g.lo);
+  const p0 = [c*g.d[0] + (g.ulo-pad)*g.u[0], c*g.d[1] + (g.ulo-pad)*g.u[1]];
+  const p1 = [c*g.d[0] + (g.uhi+pad)*g.u[0], c*g.d[1] + (g.uhi+pad)*g.u[1]];
+  return [p0, p1, [(p0[0]+p1[0])/2, (p0[1]+p1[1])/2]];
+}
+function paintGizmo(){
+  const im = $('#outImg');
+  const show = dofOn && st.corners && !im.hidden && im.naturalWidth && $('#liveWrap').hidden;
+  // An SVG element has no `.hidden` property (that is HTMLElement's), so
+  // assigning it makes a JS expando and leaves the attribute where it was.
+  gz.toggleAttribute('hidden', !show);
+  if (!show) return;
+  const W = im.naturalWidth, H = im.naturalHeight;
+  gz.setAttribute('viewBox', `0 0 ${W} ${H}`);
+  gz.style.left = im.offsetLeft + 'px'; gz.style.top = im.offsetTop + 'px';
+  gz.style.width = im.clientWidth + 'px'; gz.style.height = im.clientHeight + 'px';
+  const k = W / Math.max(im.clientWidth, 1);           // photo px per screen px
+  const g = gizmoGeom();
+  const fs = dofStart, fe = Math.min(GIZMO_FAR_MAX, fs + GIZMO_REF * (1 - fs) / Math.max(dofStr, 0.05));
+  const pinned = fs + GIZMO_REF * (1 - fs) / Math.max(dofStr, 0.05) > GIZMO_FAR_MAX;
+  const [a0, a1, ac] = gizmoLine(g, fs, 12 * k);
+  const [b0, b1, bc] = gizmoLine(g, fe, 12 * k);
+  const sigmaFull = SIGMA_FULL_FRAC * g.side;
+  const r = 6 * k, rp = 4 * k, fs11 = 11 * k;
+  const off = 16 * k;                                     // label offset along d
+  const L = (x, y, cls, extra='') => `<line x1="${x[0]}" y1="${x[1]}" x2="${y[0]}" y2="${y[1]}" class="${cls}" ${extra}/>`;
+  const T = (p, txt, dy) => `<text x="${p[0]}" y="${p[1] + dy}" text-anchor="middle" font-size="${fs11}">${txt}</text>`;
+  const beyond = fe > 1.0001;
+  gz.innerHTML =
+    L(a0, a1, 'case', 'stroke-width="4"') + L(a0, a1, 'focus') +
+    L(b0, b1, 'case', 'stroke-width="3.5"') + L(b0, b1, 'far' + (beyond ? ' out' : '')) +
+    `<circle cx="${a0[0]}" cy="${a0[1]}" r="${rp}" class="h pip" data-h="rotA"/>` +
+    `<circle cx="${a1[0]}" cy="${a1[1]}" r="${rp}" class="h pip" data-h="rotB"/>` +
+    `<circle cx="${ac[0]}" cy="${ac[1]}" r="${r}" class="h" data-h="start"/>` +
+    `<circle cx="${bc[0]}" cy="${bc[1]}" r="${r}" class="h hollow" data-h="far"/>` +
+    T([ac[0] - g.d[0]*off, ac[1] - g.d[1]*off], 'sharp', 4*k) +
+    T([bc[0] + g.d[0]*off, bc[1] + g.d[1]*off], pinned ? `gentler than this: use the slider` : `σ ${(GIZMO_REF * sigmaFull).toFixed(0)}px here${beyond ? ' · past the screen' : ''}`, 4*k);
+}
+// pointer position in PHOTO pixels
+function gizmoPos(e){
+  const rc = gz.getBoundingClientRect();
+  const W = $('#outImg').naturalWidth, H = $('#outImg').naturalHeight;
+  return [(e.clientX - rc.left) * W / rc.width, (e.clientY - rc.top) * H / rc.height];
+}
+let gzDrag = null;
+gz.addEventListener('pointerdown', e => {
+  const h = e.target.dataset && e.target.dataset.h; if (!h) return;
+  e.preventDefault(); gz.setPointerCapture(e.pointerId);
+  gzDrag = {h}; gz.classList.add('drag');
+});
+gz.addEventListener('pointermove', e => {
+  if (!gzDrag) return;
+  const p = gizmoPos(e), g = gizmoGeom();
+  const f = (p[0]*g.d[0] + p[1]*g.d[1] - g.lo) / (g.hi - g.lo);
+  if (gzDrag.h === 'start'){
+    dofStart = Math.max(0, Math.min(0.95, f));
+  } else if (gzDrag.h === 'far'){
+    // strength from the spacing; the far line never comes inside the screen
+    // (strength is capped at 1) and never so far that the blur vanishes.
+    const fe = Math.min(GIZMO_FAR_MAX, Math.max(f, dofStart + 0.05));
+    dofStr = Math.max(0.05, Math.min(1, GIZMO_REF * (1 - dofStart) / Math.max(fe - dofStart, 1e-3)));
+  } else {
+    // Turn about the focus line's centre: the pip under the pointer follows it.
+    const [, , ac] = gizmoLine(g, dofStart, 0);
+    const v = [p[0]-ac[0], p[1]-ac[1]];
+    const sign = gzDrag.h === 'rotB' ? 1 : -1;      // rotB sits at +u, rotA at -u
+    dofAng = ((Math.atan2(v[1]*sign, v[0]*sign) * 180 / Math.PI - 90) % 360 + 360) % 360;
+    if (e.shiftKey) dofAng = Math.round(dofAng / 15) * 15;
+  }
+  paintDof(); paintGizmo(); autoPreview();
+});
+const gzUp = e => { if (!gzDrag) return; gzDrag = null; gz.classList.remove('drag'); setDof(true); autoPreview(); };
+gz.addEventListener('pointerup', gzUp); gz.addEventListener('pointercancel', gzUp);
+
 $('#edgeBtn').onclick = () => setLoupeMode(loupeMode === 'float' ? 'dock' : 'float');
 
 /* Contrast for the strip only. A dark screen on a dark frame puts the
@@ -2672,6 +2925,7 @@ function syncOut(){
     const a = $('#scroller'), b = $('#outWrap');
     b.scrollLeft = a.scrollLeft; b.scrollTop = a.scrollTop;
   }
+  paintGizmo();
 }
 $('#scroller').addEventListener('scroll', () => {
   syncOut();
@@ -2694,6 +2948,7 @@ function autoPreview(){
    it. */
 function showResult(what){
   $('#outImg').hidden = what !== 'still';
+  if (what !== 'still') $('#dofGizmo').setAttribute('hidden', '');
   const v = $('#outVid');
   if (what !== 'clip' && !v.hidden){ try { v.pause(); } catch(e){} }
   v.hidden = what !== 'clip';
@@ -2713,6 +2968,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.
@@ -2809,10 +3067,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 => {
@@ -2859,7 +3117,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(), dof_start: dofStartV(),
                                      device: st.type, grade: gradeValue(),
                                      reflection: emisValue(), fit_frame: +$('#vframe').value});
   }catch(e){
@@ -2918,7 +3176,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(), dof_start: dofStartV(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => {
       outNat = im.naturalWidth;
@@ -3048,7 +3306,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(), dof_start: dofStartV(), device: st.type,
                               grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){
     setRenderProgress(null);
@@ -3094,7 +3352,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(), dof_start: dofStartV(), 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
@@ -3173,6 +3431,7 @@ $('#imp').onclick = async () => {
   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