screengraft 0.51.0 → 0.52.0

package/package.json

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

@@ -34,17 +34,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.
-
-    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.
+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, :]
@@ -79,12 +85,12 @@ class Field:
     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):
         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)
+        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)

package/scripts/ui.py

@@ -579,7 +579,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_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
@@ -605,7 +605,8 @@ 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_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
@@ -668,15 +669,17 @@ 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."""
+    """(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
-    return angle % 360.0, float(min(max(strength, 0.0), 1.0))
+        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")
@@ -1178,7 +1181,8 @@ class Handler(BaseHTTPRequestHandler):
                                            fit_frame, max_frames),
                                      kwargs={"smoothing": _smoothing(b),
                                              "dof_angle": _dof_args(b)[0],
-                                             "dof_strength": _dof_args(b)[1]}).start()
+                                             "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")
@@ -1212,7 +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_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)
@@ -1234,7 +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_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
@@ -1263,7 +1267,8 @@ class Handler(BaseHTTPRequestHandler):
                                            blend, reflection, result),
                                      kwargs={"smoothing": _smoothing(b),
                                              "dof_angle": dof_angle,
-                                             "dof_strength": dof_strength}).start()
+                                             "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.
@@ -1286,12 +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_args(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,
-                                dof_angle=dof_angle, dof_strength=dof_strength)
+                                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":
@@ -1327,7 +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_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

@@ -269,7 +269,7 @@ 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):
         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 +320,7 @@ 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))
         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 +331,8 @@ 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)
 
     def _prep(self, frame: np.ndarray, bbox=None) -> np.ndarray:
         """Warp one frame. With `bbox`, warp only that window of the canvas.
@@ -434,7 +436,8 @@ 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) -> 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 +451,7 @@ 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)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -536,7 +539,8 @@ 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) -> 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 +568,7 @@ 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)
     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.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,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: 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.
 

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.
@@ -2541,8 +2557,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 +2576,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));
   setSectionOpen($('#secDof'), on);
   paintDof();
+  paintGizmo();
 }
 let dofMeasuredFor = null;   // photo path the last measurement was for
 async function measureDof(){
@@ -2576,7 +2595,7 @@ async function measureDof(){
       autoPreview();   // still on, at the slider's own numbers
       return;
     }
-    setDof(true, r.angle, Math.max(r.strength, 0.05));
+    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}×`;
@@ -2595,6 +2614,112 @@ $('#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
@@ -2800,6 +2925,7 @@ function syncOut(){
     const a = $('#scroller'), b = $('#outWrap');
     b.scrollLeft = a.scrollLeft; b.scrollTop = a.scrollTop;
   }
+  paintGizmo();
 }
 $('#scroller').addEventListener('scroll', () => {
   syncOut();
@@ -2822,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';
@@ -2990,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(), 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(),
                                      device: st.type, grade: gradeValue(),
                                      reflection: emisValue(), fit_frame: +$('#vframe').value});
   }catch(e){
@@ -3049,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(), 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(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => {
       outNat = im.naturalWidth;
@@ -3179,7 +3306,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(), device: st.type,
                               grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){
     setRenderProgress(null);
@@ -3225,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(), 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(), 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