screengraft 0.51.0 → 0.53.0

package/package.json

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

@@ -16,6 +16,16 @@ 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.
+
+WHICH SPACE THE RAMP LIVES IN (13 Sep 2026). The plane of focus cuts the
+screen along a line, and blur grows with depth *along the screen*, so
+iso-blur lines are parallel ON THE SCREEN PLANE — and parallel lines on a
+receding plane converge in the photograph, like the phone's own edges. The
+first version ramped linearly in photo pixels, which is only right for a
+screen seen square-on; the mismatch was felt on a steep fit ("top and
+bottom are not perpendicular"). `space="screen"` builds the ramp in the
+screenshot's own coordinates and projects it through the fit's homography;
+`space="photo"` is kept so the sidecars written by v0.51–v0.52 reproduce.
 """
 import math
 
@@ -34,17 +44,23 @@ def sigma_max(corners, strength: float) -> float:
     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.
+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.
 
-    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.
+    `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, :]
@@ -74,17 +90,45 @@ def _blur(img: np.ndarray, sigma: float) -> np.ndarray:
     return cv2.GaussianBlur(img, (k, k), sigma, borderType=cv2.BORDER_REPLICATE)
 
 
+def screen_ramp(src_w: int, src_h: int, angle_deg: float, start: float, end: float) -> np.ndarray:
+    """The ramp in SCREENSHOT space: 0 up to `start`, 1 from `end`, linear
+    between, along `angle` (0 = toward +x, 90 = toward +y of the screenshot),
+    both as fractions of the screenshot's extent along that direction."""
+    a = math.radians(angle_deg)
+    d = np.array([math.cos(a), math.sin(a)], dtype=np.float64)
+    q = np.array([[0, 0], [src_w, 0], [src_w, src_h], [0, src_h]], dtype=np.float64)
+    proj = q @ d
+    lo, hi = float(proj.min()), float(proj.max())
+    start = float(np.clip(start, 0.0, 0.95))
+    end = float(np.clip(end, start + 0.05, 1.5))
+    s0, s1 = lo + start * (hi - lo), lo + end * (hi - lo)
+    xs = np.arange(src_w, dtype=np.float64)[None, :] + 0.5
+    ys = np.arange(src_h, dtype=np.float64)[:, None] + 0.5
+    t = (xs * d[0] + ys * d[1] - s0) / max(s1 - s0, 1e-6)
+    return np.clip(t, 0.0, 1.0).astype(np.float32)
+
+
 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):
+                 x0: int, y0: int, start: float = 0.0, end: float = 1.0,
+                 space: str = "photo", H=None, src_size=None):
         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)
+        if space == "screen" and H is not None and src_size is not None:
+            sw, sh = src_size
+            src = screen_ramp(sw, sh, angle_deg, start, end)
+            T = np.array([[1, 0, -x0], [0, 1, -y0], [0, 0, 1]], dtype=np.float64)
+            t = cv2.warpPerspective(src, T @ np.asarray(H, dtype=np.float64), (w, h),
+                                    flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
+            t = np.clip(t, 0.0, 1.0).astype(np.float32)
+        else:
+            t = ramp(corners, angle_deg, x0, y0, w, h, start)
+        self.t = t                                      # kept for tests and the trace
         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)

package/scripts/ui.py

@@ -578,8 +578,7 @@ 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,
-                   dof_angle=0.0, dof_strength=0.0):
+                   start_frame=0, max_frames=None, *, smoothing=0.0, dof=None):
     """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
@@ -605,7 +604,7 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
                                            else reflection),
                                start_frame=start_frame, max_frames=max_frames,
-                               dof_angle=dof_angle, dof_strength=dof_strength)
+                               **(dof or {}))
         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
@@ -668,15 +667,27 @@ def _blend_args(b):
 
 
 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."""
+    """Depth-of-field kwargs from the page, as a dict compose() takes directly.
+
+    Absent or null strength means 0 -- no field, 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), `end` absent means 1 (to the far edge), `space` absent means
+    "photo": the v0.51–v0.52 model, so those sidecars reproduce too; the page
+    sends "screen" now (see dof.py's module docstring for why).
+    """
     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)
+        end = float(b.get("dof_end") if b.get("dof_end") is not None else 1.0)
     except (TypeError, ValueError):
-        return 0.0, 0.0
-    return angle % 360.0, float(min(max(strength, 0.0), 1.0))
+        strength, angle, start, end = 0.0, 0.0, 0.0, 1.0
+    space = "screen" if b.get("dof_space") == "screen" else "photo"
+    start = float(min(max(start, 0.0), 0.95))
+    return {"dof_angle": angle % 360.0, "dof_strength": float(min(max(strength, 0.0), 1.0)),
+            "dof_start": start, "dof_end": float(min(max(end, start + 0.05), 1.5)),
+            "dof_space": space}
 
 
 ROLES = ("photo", "screenshot")
@@ -1177,8 +1188,7 @@ class Handler(BaseHTTPRequestHandler):
                                            blend, reflection, None, "preview",
                                            fit_frame, max_frames),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof_angle": _dof_args(b)[0],
-                                             "dof_strength": _dof_args(b)[1]}).start()
+                                             "dof": _dof_args(b)}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1212,7 +1222,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)
+                dof = _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)
@@ -1234,7 +1244,9 @@ 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_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
+                          "dof_start": dof["dof_start"], "dof_end": dof["dof_end"],
+                          "dof_space": dof["dof_space"],
                           # 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
@@ -1262,8 +1274,7 @@ class Handler(BaseHTTPRequestHandler):
                                            gr, grain, preset, fit_frame,
                                            blend, reflection, result),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof_angle": dof_angle,
-                                             "dof_strength": dof_strength}).start()
+                                             "dof": dof}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1286,12 +1297,11 @@ 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)
+                dof = _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,
-                                dof_angle=dof_angle, dof_strength=dof_strength)
+                                blend=blend, reflection=reflection, **dof)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
                 if u.path == "/api/preview":
@@ -1327,7 +1337,9 @@ 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_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
+                          "dof_start": dof["dof_start"], "dof_end": dof["dof_end"],
+                          "dof_space": dof["dof_space"],
                           "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

@@ -269,7 +269,8 @@ class Plan:
                  corner_radius: float = 0.0, grain: bool = False,
                  blend: str = "replace", reflection: float = DEFAULT_REFLECTION,
                  corner_smoothing: float = 0.0,
-                 dof_angle: float = 0.0, dof_strength: float = 0.0):
+                 dof_angle: float = 0.0, dof_strength: float = 0.0, dof_start: float = 0.0,
+                 dof_end: float = 1.0, dof_space: str = "photo"):
         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")
@@ -320,6 +321,9 @@ class Plan:
         # 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))
+        self.dof_end = float(np.clip(dof_end, self.dof_start + 0.05, 1.5))
+        self.dof_space = "screen" if dof_space == "screen" else "photo"
         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)
@@ -330,7 +334,10 @@ class Plan:
         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)
+                                  self.warped_mask[by0:by1, bx0:bx1], bx0, by0,
+                                  start=self.dof_start, end=self.dof_end,
+                                  space=self.dof_space, H=self.H,
+                                  src_size=(self.new_w, self.new_h))
 
     def _prep(self, frame: np.ndarray, bbox=None) -> np.ndarray:
         """Warp one frame. With `bbox`, warp only that window of the canvas.
@@ -434,7 +441,9 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
             grade: float = 0.0, grain: bool = False, screen_off: np.ndarray = None,
             specular: float = 0.75, blend: str = "replace",
             reflection: float = DEFAULT_REFLECTION,
-            dof_angle: float = 0.0, dof_strength: float = 0.0) -> np.ndarray:
+            dof_angle: float = 0.0, dof_strength: float = 0.0,
+            dof_start: float = 0.0, dof_end: float = 1.0,
+            dof_space: str = "photo") -> 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
@@ -448,7 +457,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
     plan = Plan(photo, screenshot.shape, corners, corner_radius, grain=grain,
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
-                dof_angle=dof_angle, dof_strength=dof_strength)
+                dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
+                dof_end=dof_end, dof_space=dof_space)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -536,7 +546,9 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   frames_dir: str = None, progress=None, blend: str = "replace",
                   reflection: float = DEFAULT_REFLECTION,
                   start_frame: int = 0, max_frames: int = None,
-                  dof_angle: float = 0.0, dof_strength: float = 0.0) -> dict:
+                  dof_angle: float = 0.0, dof_strength: float = 0.0,
+                  dof_start: float = 0.0, dof_end: float = 1.0,
+                  dof_space: str = "photo") -> 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.
 
@@ -564,7 +576,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
     plan = Plan(photo, first.shape, corners, corner_radius, grain=grain,
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
-                dof_angle=dof_angle, dof_strength=dof_strength)
+                dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
+                dof_end=dof_end, dof_space=dof_space)
     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.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.
+**What ships (v0.53):** 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,7 +13,7 @@ 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.
+**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, defined in the screen's own plane and projected through the fit (so the two lines converge with the phone's edges on a steep shot, as real iso-blur lines do): a solid line where focus ends (drag its centre), a dashed line where the blur reaches its full amount (drag its centre to move it, its end pips to turn both, and slide the diamond along it for how much blur). 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.
 

package/ui/index.html

@@ -625,6 +625,23 @@
 
   #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.thumb{fill:#fff;stroke:#f5623d;stroke-width:2}
+  #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 +1040,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.
@@ -1126,7 +1143,7 @@
         <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" style="color:var(--mute)">Blur grows toward (of the screen)</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">
@@ -2541,8 +2558,10 @@ $('#emisAmt').onchange = e => { setEmis(true, parseFloat(e.target.value)); autoP
 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];
@@ -2558,9 +2577,10 @@ 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('dof', on ? '1' : '0'); remember('dofAng', String(dofAng)); remember('dofStr', String(dofStr)); remember('dofStart', String(dofStart)); remember('dofEnd', String(dofEnd));
   setSectionOpen($('#secDof'), on);
   paintDof();
+  paintGizmo();
 }
 let dofMeasuredFor = null;   // photo path the last measurement was for
 async function measureDof(){
@@ -2576,7 +2596,22 @@ async function measureDof(){
       autoPreview();   // still on, at the slider's own numbers
       return;
     }
-    setDof(true, r.angle, Math.max(r.strength, 0.05));
+    // The estimator's angle is in PHOTO space; the gizmo and the engine work in
+    // the screen's own plane. Map a short step from the quad's centre through
+    // the inverse homography and take its direction there.
+    let ang = r.angle;
+    if (st.shotSize){
+      const [sw, sh] = st.shotSize, rect = [[0,0],[sw,0],[sw,sh],[0,sh]];
+      const Hi = solveHomography(st.corners, rect);
+      if (Hi){
+        const c = st.corners.reduce((acc,cc)=>[acc[0]+cc[0]/4, acc[1]+cc[1]/4],[0,0]);
+        const a = r.angle * Math.PI / 180, step = 40;
+        const p0 = applyH(Hi, c), p1 = applyH(Hi, [c[0] + Math.cos(a)*step, c[1] + Math.sin(a)*step]);
+        ang = (Math.atan2(p1[1]-p0[1], p1[0]-p0[0]) * 180 / Math.PI + 360) % 360;
+      }
+    }
+    dofStart = 0; dofEnd = 1; setDof(true, ang, 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}×`;
@@ -2595,6 +2630,110 @@ $('#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) -- defined IN THE SCREEN'S OWN PLANE and
+   projected through the fit's homography. The plane of focus cuts the screen
+   along a line and blur grows with depth along the screen, so iso-blur lines
+   are parallel on the screen and converge in the photograph like the phone's
+   own edges; drawn in photo space they were parallel on the picture and wrong
+   on any steep fit (reported 13 Sep 2026). The SOLID line is where focus
+   ends; the DASHED line is where the blur reaches its full amount, and it can
+   sit anywhere on the screen or a little past it. Handles:
+     solid line centre  -- move focus (start)
+     dashed line centre -- move where the ramp ends (end); spacing = ramp length
+     dashed line pips   -- turn both lines (direction), ⇧ snaps to 15°
+     diamond on the dashed line -- slide along it for how much blur (strength)
+   Everything is computed in screenshot pixels and mapped to the photo with H;
+   the SVG's viewBox is the photo so 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
+let dofEnd = parseFloat(recall('dofEnd','1')); if (!(dofEnd > 0)) dofEnd = 1;
+function dofEndV(){ return dofOn ? dofEnd : 1; }
+function applyH(Hm, p){ const w = Hm[6]*p[0] + Hm[7]*p[1] + Hm[8]; return [(Hm[0]*p[0] + Hm[1]*p[1] + Hm[2]) / w, (Hm[3]*p[0] + Hm[4]*p[1] + Hm[5]) / w]; }
+function gizmoGeom(){
+  const [sw, sh] = st.shotSize, a = dofAng * Math.PI / 180;
+  const rect = [[0,0],[sw,0],[sw,sh],[0,sh]];
+  const H = solveHomography(rect, st.corners), Hi = solveHomography(st.corners, rect);
+  const d = [Math.cos(a), Math.sin(a)], u = [-d[1], d[0]];
+  const pd = rect.map(c => c[0]*d[0] + c[1]*d[1]), pu = rect.map(c => c[0]*u[0] + c[1]*u[1]);
+  const C = st.corners;
+  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 {H, Hi, d, u, lo: Math.min(...pd), hi: Math.max(...pd), ulo: Math.min(...pu), uhi: Math.max(...pu), side};
+}
+// a screen-space point at fraction f along d and fraction k across u
+function gzPt(g, f, k){ const c = g.lo + f*(g.hi - g.lo), w = g.ulo + k*(g.uhi - g.ulo); return [c*g.d[0] + w*g.u[0], c*g.d[1] + w*g.u[1]]; }
+function paintGizmo(){
+  const im = $('#outImg');
+  const show = dofOn && st.corners && st.shotSize && !im.hidden && im.naturalWidth && $('#liveWrap').hidden;
+  gz.toggleAttribute('hidden', !show);
+  if (!show) return;
+  const W = im.naturalWidth, Hh = im.naturalHeight;
+  gz.setAttribute('viewBox', `0 0 ${W} ${Hh}`);
+  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(); if (!g.H || !g.Hi) return;
+  const P = (f, q) => applyH(g.H, gzPt(g, f, q));
+  const a0 = P(dofStart, -0.06), a1 = P(dofStart, 1.06), ac = P(dofStart, 0.5);
+  const b0 = P(dofEnd, -0.06), b1 = P(dofEnd, 1.06), bc = P(dofEnd, 0.5);
+  const th = P(dofEnd, 0.08 + 0.84 * dofStr);           // the strength thumb slides along the dashed line
+  const sigma = dofStr * SIGMA_FULL_FRAC * g.side;
+  const r = 6 * k, rp = 4 * k, fs11 = 11 * k, off = 14 * k;
+  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 away = unit(sub(bc, ac));                        // label offsets: away from the other line
+  const beyond = dofEnd > 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="${ac[0]}" cy="${ac[1]}" r="${r}" class="h" data-h="start"/>` +
+    `<circle cx="${b0[0]}" cy="${b0[1]}" r="${rp}" class="h pip" data-h="rotA"/>` +
+    `<circle cx="${b1[0]}" cy="${b1[1]}" r="${rp}" class="h pip" data-h="rotB"/>` +
+    `<circle cx="${bc[0]}" cy="${bc[1]}" r="${r}" class="h hollow" data-h="end"/>` +
+    `<rect x="${th[0]-r}" y="${th[1]-r}" width="${2*r}" height="${2*r}" transform="rotate(45 ${th[0]} ${th[1]})" class="h thumb" data-h="str"/>` +
+    T([ac[0] - away[0]*off, ac[1] - away[1]*off], 'sharp', 4*k) +
+    T([bc[0] + away[0]*off, bc[1] + away[1]*off], `σ ${sigma.toFixed(0)}px from here${beyond ? ' · past the screen' : ''}`, 4*k) +
+    T([th[0] + away[0]*off*1.6, th[1] + away[1]*off*1.6], `${Math.round(dofStr*100)}%`, 4*k);
+}
+// pointer position in SCREENSHOT pixels
+function gizmoPos(e, g){
+  const rc = gz.getBoundingClientRect();
+  const W = $('#outImg').naturalWidth, Hh = $('#outImg').naturalHeight;
+  const photo = [(e.clientX - rc.left) * W / rc.width, (e.clientY - rc.top) * Hh / rc.height];
+  return applyH(g.Hi, photo);
+}
+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 g = gizmoGeom(); if (!g.Hi) return;
+  const p = gizmoPos(e, g);
+  const f = (p[0]*g.d[0] + p[1]*g.d[1] - g.lo) / (g.hi - g.lo);
+  const q = (p[0]*g.u[0] + p[1]*g.u[1] - g.ulo) / (g.uhi - g.ulo);
+  if (gzDrag.h === 'start'){
+    dofStart = Math.max(0, Math.min(0.95, Math.min(f, dofEnd - 0.05)));
+  } else if (gzDrag.h === 'end'){
+    dofEnd = Math.max(dofStart + 0.05, Math.min(1.5, f));
+  } else if (gzDrag.h === 'str'){
+    dofStr = Math.max(0.05, Math.min(1, (q - 0.08) / 0.84));
+  } else {
+    // Turn about the dashed line's centre; the pip under the pointer follows.
+    const c = gzPt(g, dofEnd, 0.5);
+    const v = [p[0]-c[0], p[1]-c[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
@@ -2800,6 +2939,7 @@ function syncOut(){
     const a = $('#scroller'), b = $('#outWrap');
     b.scrollLeft = a.scrollLeft; b.scrollTop = a.scrollTop;
   }
+  paintGizmo();
 }
 $('#scroller').addEventListener('scroll', () => {
   syncOut();
@@ -2822,6 +2962,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';
@@ -2990,7 +3131,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(), dof_angle: dofAngle(), dof_strength: dofStrength(),
+    await api('/api/preview_video', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_space: 'screen',
                                      device: st.type, grade: gradeValue(),
                                      reflection: emisValue(), fit_frame: +$('#vframe').value});
   }catch(e){
@@ -3049,7 +3190,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(), dof_angle: dofAngle(), dof_strength: dofStrength(), 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(), dof_end: dofEndV(), dof_space: 'screen', device: st.type, grade: gradeValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => {
       outNat = im.naturalWidth;
@@ -3179,7 +3320,7 @@ async function renderVideo(){
   b.disabled = true;
   setRenderProgress(0);
   try{
-    await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), device: st.type,
+    await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), smoothing: smoothingValue(), dof_angle: dofAngle(), dof_strength: dofStrength(), dof_start: dofStartV(), dof_end: dofEndV(), dof_space: 'screen', device: st.type,
                               grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){
     setRenderProgress(null);
@@ -3225,7 +3366,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(), dof_angle: dofAngle(), dof_strength: dofStrength(), 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(), dof_end: dofEndV(), dof_space: 'screen', 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