screengraft 0.54.7 → 0.55.0

package/README.md

@@ -138,8 +138,10 @@ outside the screen mask. It never touches the pixels you designed.
    warp never area-averages, so warping a 1206×2622 screenshot into a 226×454
    quad without it turns body text into noise.
 3. **Realism pass** *(optional)* — white balance and exposure toward the
-   surrounding light, grain matched to the photo's own noise floor, real
-   speculars lifted from a screen-off reference.
+   surrounding light, grain measured from the photo's own noise floor and
+   laid on the screen at 0.7× of it (a lit screen sits in the highlights, where
+   8-bit noise is lower than on the body around it), real speculars lifted
+   from a screen-off reference.
 4. **Video**, when the source is a clip — everything a fixed photo and a fixed
    quad make constant is computed once, and only the frame changes. Three
    consequences worth naming, because each is a way video normally goes wrong:

package/package.json

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

@@ -281,7 +281,7 @@ def measure(photo: np.ndarray, corners) -> dict:
         out.update({"angle": 0.0, "strength": 0.0, "flat": True})
         return out
     Amat = np.column_stack([mids[:, 0], mids[:, 1], np.ones(len(mids))])
-    (a, b, c), *_ = np.linalg.lstsq(Amat, sig, rcond=None)
+    (a, b, _c), *_ = np.linalg.lstsq(Amat, sig, rcond=None)
     angle = math.degrees(math.atan2(b, a)) % 360.0
     strength = float(np.clip((sig.max() - lo) / max(sigma_max(q, 1.0), 1e-6), 0.0, 1.0))
     out.update({"angle": round(angle, 1), "strength": round(strength, 3), "flat": False})

package/scripts/grade.py

@@ -131,6 +131,15 @@ def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
 
 
 GRAIN_GATE = 20.0        # grey levels: above this a residual is an edge, not grain
+# How much of the SURROUND's noise floor a lit screen should carry. The sigma is
+# measured on the ring around the screen -- bezel and body, usually the darkest
+# thing near it -- but the injected screen is usually the brightest thing in
+# the frame, and after the sRGB curve a highlight carries less noise in grey
+# levels than a shadow does. Measured on the 38-photo corpus (13 Sep 2026):
+# the 192-255 band's floor is a median 0.67x the 0-63 band's. A designer's
+# eye on a full-resolution save said the same thing first: "a bit smaller".
+# 1.0 is the pre-v0.55 behaviour and is what an old sidecar replays with.
+SCREEN_GRAIN_GAIN = 0.7
 _MEDIAN_HP_GAIN = 0.909  # a 3x3 median high-pass absorbs this much of iid noise
                          # (measured, 5 seeds x sigma 1-5, spread < 0.3%)
 

package/scripts/ui.py

@@ -50,6 +50,7 @@ import detect as D  # noqa: E402
 import fitfile as FF  # noqa: E402
 import fits as FIT  # noqa: E402
 import dof as DOF   # noqa: E402
+import grade as _grade  # noqa: E402
 import scan as S  # noqa: E402
 import warp as W  # noqa: E402
 
@@ -578,7 +579,8 @@ PREVIEW_SECONDS = 6.0
 
 def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame,
                    blend="replace", reflection=None, result=None, kind="render",
-                   start_frame=0, max_frames=None, *, smoothing=0.0, dof=None):
+                   start_frame=0, max_frames=None, *, smoothing=0.0, dof=None,
+                   grain_gain=1.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
@@ -598,7 +600,7 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
     try:
         info = W.compose_video(photo, video_path, corners, dest,
                                corner_radius=radius_px, corner_smoothing=smoothing,
-                               grade=gr, grain=grain,
+                               grade=gr, grain=grain, grain_gain=grain_gain,
                                preset=preset, fit_frame=fit_frame, progress=progress,
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
@@ -666,6 +668,22 @@ def _blend_args(b):
     return "emissive", float(max(0.0, min(1.0, float(r))))
 
 
+def _grain_gain(b) -> float:
+    """How much of the surround's noise floor the screen carries.
+
+    The page does not set this; fresh renders get grade.SCREEN_GRAIN_GAIN. It
+    is read from the body so a sidecar replayed through the API keeps its own
+    value -- a sidecar from before the gain existed carries none and passes
+    1.0 explicitly at the replay site, never here.
+    """
+    try:
+        g = float(b.get("grain_gain")) if b.get("grain_gain") is not None \
+            else _grade.SCREEN_GRAIN_GAIN
+    except (TypeError, ValueError):
+        g = _grade.SCREEN_GRAIN_GAIN
+    return float(min(max(g, 0.0), 2.0))
+
+
 def _dof_args(b):
     """Depth-of-field kwargs from the page, as a dict compose() takes directly.
 
@@ -1194,7 +1212,8 @@ class Handler(BaseHTTPRequestHandler):
                                            blend, reflection, None, "preview",
                                            fit_frame, max_frames),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof": _dof_args(b)}).start()
+                                             "dof": _dof_args(b),
+                                             "grain_gain": _grain_gain(b)}).start()
                 except BaseException:
                     with RENDER_LOCK:
                         RENDER.update(state="error", message="could not start the preview")
@@ -1247,7 +1266,7 @@ class Handler(BaseHTTPRequestHandler):
                 result = {"output": dest, "photo": ppath, "screenshot": spath,
                           "corners": corners, "radius_frac": frac, "radius_px": radius_px,
                           "device": b.get("device"), "corner_smoothing": _smoothing(b),
-                          "grade": gr, "grain": grain,
+                          "grade": gr, "grain": grain, "grain_gain": _grain_gain(b),
                           "video": True, "preset": preset, "fit_frame": fit_frame,
                           "blend": blend, "reflection": reflection,
                           "dof_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
@@ -1280,7 +1299,8 @@ class Handler(BaseHTTPRequestHandler):
                                            gr, grain, preset, fit_frame,
                                            blend, reflection, result),
                                      kwargs={"smoothing": _smoothing(b),
-                                             "dof": dof}).start()
+                                             "dof": dof,
+                                             "grain_gain": result["grain_gain"]}).start()
                 except BaseException:
                     # If the thread cannot even be created, the flag must not
                     # outlive the request.
@@ -1304,9 +1324,11 @@ class Handler(BaseHTTPRequestHandler):
                 blend, reflection = _blend_args(b)
                 smoothing = _smoothing(b)
                 dof = _dof_args(b)
+                grain_gain = _grain_gain(b)
                 out = W.compose(photo, shot, corners, radius_px,
                                 corner_smoothing=smoothing,
                                 grade=gr, grain=bool(b.get("grain", gr > 0)),
+                                grain_gain=grain_gain,
                                 blend=blend, reflection=reflection, **dof)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
@@ -1342,6 +1364,7 @@ class Handler(BaseHTTPRequestHandler):
                           "radius_frac": frac, "radius_px": radius_px, "device": b.get("device"),
                           "corner_smoothing": smoothing,
                           "grade": gr, "grain": bool(b.get("grain", gr > 0)),
+                          "grain_gain": grain_gain,
                           "blend": blend, "reflection": reflection,
                           "dof_angle": dof["dof_angle"], "dof_strength": dof["dof_strength"],
                           "dof_start": dof["dof_start"], "dof_end": dof["dof_end"],

package/scripts/warp.py

@@ -270,7 +270,8 @@ class Plan:
                  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_end: float = 1.0, dof_space: str = "photo", dof_end2=None):
+                 dof_end: float = 1.0, dof_space: str = "photo", dof_end2=None,
+                 grain_gain: float = 1.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")
@@ -310,8 +311,12 @@ class Plan:
                                 self.corner_smoothing)
         self.warped_mask = _warp_mask_antialiased(src_mask, self.H, pw, ph, dst_quad)
         self.mask3 = cv2.merge([self.warped_mask] * 3).astype(np.float32) / 255.0
+        # The floor is the surround's; the screen carries `grain_gain` of it
+        # (see grade.SCREEN_GRAIN_GAIN). Defaults to 1.0 so a sidecar written
+        # before the gain existed reproduces its save byte for byte.
+        self.grain_gain = float(max(grain_gain, 0.0))
         self.grain_sigma = (_grade.measure_grain(photo, _grade.surround_ring(self.warped_mask))
-                            if grain else 0.0)
+                            * self.grain_gain if grain else 0.0)
         self.grade_params = None
         # Integer bbox of the quad, clamped to the canvas and padded by a pixel
         # so the antialiased edge is never clipped.
@@ -444,7 +449,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
             reflection: float = DEFAULT_REFLECTION,
             dof_angle: float = 0.0, dof_strength: float = 0.0,
             dof_start: float = 0.0, dof_end: float = 1.0,
-            dof_space: str = "photo", dof_end2=None) -> np.ndarray:
+            dof_space: str = "photo", dof_end2=None,
+            grain_gain: float = 1.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
@@ -459,7 +465,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
-                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2)
+                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
+                grain_gain=grain_gain)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -549,7 +556,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   start_frame: int = 0, max_frames: int = None,
                   dof_angle: float = 0.0, dof_strength: float = 0.0,
                   dof_start: float = 0.0, dof_end: float = 1.0,
-                  dof_space: str = "photo", dof_end2=None) -> dict:
+                  dof_space: str = "photo", dof_end2=None,
+                  grain_gain: float = 1.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.
 
@@ -578,7 +586,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                 corner_smoothing=corner_smoothing,
                 blend=blend, reflection=reflection,
                 dof_angle=dof_angle, dof_strength=dof_strength, dof_start=dof_start,
-                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2)
+                dof_end=dof_end, dof_space=dof_space, dof_end2=dof_end2,
+                grain_gain=grain_gain)
     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.54):** 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.55):** 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".
 

package/ui/index.html

@@ -2920,9 +2920,38 @@ function swingText(mode){
   if (mode === 'rotB') return 'the left end swings, pivot on the right';
   return 'flat on the rule means aligned';
 }
+/* A corner under the pointer gets a plain magnified view instead of the
+   rectified strip: the strip straightens ONE edge, and a corner is where two
+   meet, so straightening either would bend the other. Same magnification as
+   the strip (H / 2·stripHalf, so the ± buttons work here too), centred on the
+   corner, unrotated, with both edges drawn through it and the ring at the
+   centre. Requested 13 Sep 2026; edges keep the strip as it is. */
+function paintCorner(c, W, H, i){
+  c.setTransform(1,0,0,1,0,0);
+  c.fillStyle = '#0c0c0b'; c.fillRect(0,0,W,H);
+  const P = st.corners[i], M = H / (2*stripHalf);
+  c.save();
+  c.setTransform(M, 0, 0, M, W/2 - P[0]*M, H/2 - P[1]*M);
+  c.imageSmoothingEnabled = true;
+  c.drawImage(img, 0, 0);
+  c.restore();
+  if (stripHC) stretchContrast(c, W, H);
+  const toS = q => [W/2 + (q[0]-P[0])*M, H/2 + (q[1]-P[1])*M];
+  const prev = st.corners[(i+3)%4], next = st.corners[(i+1)%4];
+  for (const q of [prev, next]){
+    const e = toS(q), d = unit(sub(e, [W/2, H/2]));
+    const s0 = add([W/2, H/2], mul(d, HANDLE_GAP_S)), s1 = add([W/2, H/2], mul(d, 4000));
+    cased(c, () => { c.beginPath(); c.moveTo(s0[0], s0[1]); c.lineTo(s1[0], s1[1]); }, QUAD_W, CORE_QUAD);
+  }
+  casedRing(c, W/2, H/2, 4, CORE_QUAD);
+  c.font = '600 11px system-ui'; c.textBaseline = 'middle';
+  casedText(c, LBL[i], W/2 + 12, H/2 - 12, 'rgba(255,255,255,.95)');
+}
+const HANDLE_GAP_S = 4 + 1 + CASE_PAD/2 + 1;   // the same break the canvas leaves around a ring
 function drawStrip(){
   const a = drag || hover || pick;
-  const has = !!(st.corners && a && a.kind === 'edge' && img.naturalWidth);
+  const has = !!(st.corners && a && (a.kind === 'edge' || a.kind === 'corner') && img.naturalWidth);
+  const corner = has && a.kind === 'corner';
   $('#stripZ').textContent = '±' + stripHalf + 'px';
   if (loupeMode === 'dock'){
     $('#floatLoupe').classList.remove('on');
@@ -2932,13 +2961,23 @@ function drawStrip(){
       $('#stripSt').textContent = 'Hover or drag an edge — this straightens it, so misalignment shows as a wedge.';
       return;
     }
-    paintStrip(sctx, W, H, a.i, a.mode);
-    $('#stripSt').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px · ${(H/(2*stripHalf)).toFixed(1)}× across the boundary — ${swingText(a.mode)}`;
+    if (corner){
+      paintCorner(sctx, W, H, a.i);
+      $('#stripSt').textContent = `${LBL[a.i]} corner · ${(H/(2*stripHalf)).toFixed(1)}× — where the two edges meet`;
+    } else {
+      paintStrip(sctx, W, H, a.i, a.mode);
+      $('#stripSt').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px · ${(H/(2*stripHalf)).toFixed(1)}× across the boundary — ${swingText(a.mode)}`;
+    }
   } else {
     const fl = $('#floatLoupe');
     if (!has){ fl.classList.remove('on'); return; }
-    paintStrip(fctx, stripF.width, stripF.height, a.i, a.mode);
-    $('#stripFCap').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px — ${swingText(a.mode)}`;
+    if (corner){
+      paintCorner(fctx, stripF.width, stripF.height, a.i);
+      $('#stripFCap').textContent = `${LBL[a.i]} corner · ${(stripF.height/(2*stripHalf)).toFixed(1)}× — where the two edges meet`;
+    } else {
+      paintStrip(fctx, stripF.width, stripF.height, a.i, a.mode);
+      $('#stripFCap').textContent = `${EDGE_LBL[a.i]} edge · ±${stripHalf}px — ${swingText(a.mode)}`;
+    }
     fl.classList.add('on');
     const w = fl.offsetWidth || 356, h = fl.offsetHeight || 130;
     let x = lastPointer[0] + 26, y = lastPointer[1] - h - 18;