screengraft 0.52.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.52.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
 
@@ -80,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, start: float = 0.0):
+                 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, start)
+        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, dof_start=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,8 +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_start=dof_start)
+                               **(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
@@ -669,17 +667,27 @@ def _blend_args(b):
 
 
 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."""
+    """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, 0.0
-    return angle % 360.0, float(min(max(strength, 0.0), 1.0)), float(min(max(start, 0.0), 0.95))
+        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")
@@ -1180,9 +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],
-                                             "dof_start": _dof_args(b)[2]}).start()
+                                             "dof": _dof_args(b)}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1216,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_start = _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)
@@ -1238,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_start": dof_start,
+                          "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
@@ -1266,9 +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,
-                                             "dof_start": dof_start}).start()
+                                             "dof": dof}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1291,13 +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_start = _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,
-                                dof_start=dof_start)
+                                blend=blend, reflection=reflection, **dof)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
                 if u.path == "/api/preview":
@@ -1333,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_start": dof_start,
+                          "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_start: 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")
@@ -321,6 +322,8 @@ class Plan:
         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)
@@ -332,7 +335,9 @@ class Plan:
         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)
+                                  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.
@@ -437,7 +442,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
             specular: float = 0.75, blend: str = "replace",
             reflection: float = DEFAULT_REFLECTION,
             dof_angle: float = 0.0, dof_strength: float = 0.0,
-            dof_start: float = 0.0) -> np.ndarray:
+            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
@@ -451,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_start=dof_start)
+                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)
 
@@ -540,7 +547,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   reflection: float = DEFAULT_REFLECTION,
                   start_frame: int = 0, max_frames: int = None,
                   dof_angle: float = 0.0, dof_strength: float = 0.0,
-                  dof_start: float = 0.0) -> dict:
+                  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.
 
@@ -568,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_start=dof_start)
+                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.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.
+**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. **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.
+**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

@@ -639,6 +639,7 @@
   #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}
@@ -1142,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">
@@ -2576,7 +2577,7 @@ 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));
+  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();
@@ -2595,7 +2596,22 @@ async function measureDof(){
       autoPreview();   // still on, at the slider's own numbers
       return;
     }
-    dofStart = 0; 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}×`;
@@ -2616,79 +2632,76 @@ $('#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. */
+   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
-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
+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 C = st.corners, a = dofAng * Math.PI / 180;
+  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 = 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 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 {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]];
+  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 && !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.
+  const show = dofOn && st.corners && st.shotSize && !im.hidden && im.naturalWidth && $('#liveWrap').hidden;
   gz.toggleAttribute('hidden', !show);
   if (!show) return;
-  const W = im.naturalWidth, H = im.naturalHeight;
-  gz.setAttribute('viewBox', `0 0 ${W} ${H}`);
+  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();
-  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 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 beyond = fe > 1.0001;
+  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="${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){
+    `<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, H = $('#outImg').naturalHeight;
-  return [(e.clientX - rc.left) * W / rc.width, (e.clientY - rc.top) * H / rc.height];
+  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 => {
@@ -2698,19 +2711,20 @@ gz.addEventListener('pointerdown', e => {
 });
 gz.addEventListener('pointermove', e => {
   if (!gzDrag) return;
-  const p = gizmoPos(e), g = gizmoGeom();
+  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, 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)));
+    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 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]];
+    // 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;
@@ -3117,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(), dof_start: dofStartV(),
+    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){
@@ -3176,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(), dof_start: dofStartV(), 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;
@@ -3306,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(), dof_start: dofStartV(), 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);
@@ -3352,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(), dof_start: dofStartV(), 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