screengraft 0.20.4 → 0.21.0

package/README.md

@@ -29,6 +29,11 @@ prototype, then put the recording inside a real photograph.
 - **Realism pass** *(optional)* — matches the screen's white balance and grain to
   the light in the room, and can lift the device's real reflections from a
   screen-off frame of the same shot.
+- **Emissive screens** *(optional)* — a display emits light *and* reflects the
+  room, which is why a switched-off phone looks dark grey rather than black.
+  Paint a true-black UI on flat and it reads as a hole cut in the photo. Turn
+  this on and the screenshot composites over the device's own glass, so the
+  photo's highlights carry across the screen.
 - **Video, not just stills.** The screen source can be an `mp4`/`mov`/`webm`.
   You match the edges on one frame and every frame gets that same geometry — the
   photograph is still, so there is nothing to track and nothing to drift. Output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.20.4",
+  "version": "0.21.0",
   "description": "Put a UI screenshot or screen recording onto a photographed device screen with the perspective exactly right — a homography you confirm by hand, not a generative guess.",
   "keywords": [
     "mockup",

package/scripts/ui.py

@@ -215,14 +215,18 @@ RENDER = {"state": "idle", "done": 0, "total": 0, "output": None, "message": Non
 RENDER_LOCK = threading.Lock()
 
 
-def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame):
+def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame,
+                   blend="replace", reflection=None):
     def progress(done, total):
         with RENDER_LOCK:
             RENDER["done"], RENDER["total"] = done, total
     try:
         info = W.compose_video(photo, video_path, corners, dest,
                                corner_radius=radius_px, grade=gr, grain=grain,
-                               preset=preset, fit_frame=fit_frame, progress=progress)
+                               preset=preset, fit_frame=fit_frame, progress=progress,
+                               blend=blend,
+                               reflection=(W.DEFAULT_REFLECTION if reflection is None
+                                           else reflection))
         with RENDER_LOCK:
             RENDER.update(state="done", output=dest, info=info,
                           done=info["frames"], total=info["frames"], message=None)
@@ -231,6 +235,21 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
             RENDER.update(state="error", message=str(e))
 
 
+def _blend_args(b):
+    """(blend, reflection) from the page's single `reflection` field.
+
+    One field, not two: the page sends a number when the switch is on and null
+    when it is off, so there is no way to express the contradictory state
+    "emissive with no strength" — which is just `replace` under a different
+    name. compose() still takes both, because the engine should not have to
+    infer intent from a null.
+    """
+    r = b.get("reflection")
+    if r is None:
+        return "replace", W.DEFAULT_REFLECTION
+    return "emissive", float(max(0.0, min(1.0, float(r))))
+
+
 def _guess_type(corners):
     c = np.array(corners, dtype=float)
     w = (np.linalg.norm(c[1] - c[0]) + np.linalg.norm(c[2] - c[3])) / 2
@@ -465,6 +484,7 @@ class Handler(BaseHTTPRequestHandler):
                 radius_px = frac * first.shape[1]
                 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)
                 preset = "prores" if b.get("preset") == "prores" else "web"
                 ext = ".mov" if preset == "prores" else ".mp4"
                 os.makedirs(OUT_DIR, exist_ok=True)
@@ -484,11 +504,13 @@ class Handler(BaseHTTPRequestHandler):
                           "corners": corners, "radius_frac": frac, "radius_px": radius_px,
                           "device": b.get("device"), "grade": gr, "grain": grain,
                           "video": True, "preset": preset, "fit_frame": fit_frame,
+                          "blend": blend, "reflection": reflection,
                           "saved": time.time()}
                 _write_json_atomic(SESSION.result_path, result)
                 threading.Thread(target=_render_worker, daemon=True,
                                  args=(photo, spath, corners, dest, radius_px,
-                                       gr, grain, preset, fit_frame)).start()
+                                       gr, grain, preset, fit_frame,
+                                       blend, reflection)).start()
                 return self._json({"started": True, "output": dest, "preset": preset})
 
             if u.path in ("/api/preview", "/api/save"):
@@ -502,8 +524,10 @@ class Handler(BaseHTTPRequestHandler):
                 # is the point (a brand review), and the grade is the right one
                 # when the photograph is (a portfolio shot).
                 gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                blend, reflection = _blend_args(b)
                 out = W.compose(photo, shot, corners, radius_px,
-                                grade=gr, grain=bool(b.get("grain", gr > 0)))
+                                grade=gr, grain=bool(b.get("grain", gr > 0)),
+                                blend=blend, reflection=reflection)
                 SESSION.update(corners=corners, radius_frac=frac, device=b.get("device"),
                                grade=gr)
                 if u.path == "/api/preview":
@@ -537,6 +561,7 @@ class Handler(BaseHTTPRequestHandler):
                 result = {"output": dest, "photo": ppath, "screenshot": spath, "corners": corners,
                           "radius_frac": frac, "radius_px": radius_px, "device": b.get("device"),
                           "grade": gr, "grain": bool(b.get("grain", gr > 0)),
+                          "blend": blend, "reflection": reflection,
                           "saved": time.time()}
                 _write_json_atomic(SESSION.result_path, result)
                 SESSION.update(output=dest)

package/scripts/warp.py

@@ -40,6 +40,12 @@ import grade as _grade   # M2: the realism pass
 
 MASK_SS = 4   # destination-space supersampling for the screen's edge
 
+# How much of the device's own glass shows through under an emissive screen.
+# Measured 9 Sep 2026 on an automotive render whose UI is 56% true black: at 0
+# the screen is a hole, by 25% it sits in the scene, 50% reads clearly as glass,
+# and past 75% the content loses contrast. 0.35 is the middle of the usable band.
+DEFAULT_REFLECTION = 0.35
+
 
 def rounded_mask(w: int, h: int, radius: float) -> np.ndarray:
     """White-on-black mask, full frame minus rounded corners cut to black.
@@ -146,13 +152,16 @@ class Plan:
     """
 
     def __init__(self, photo: np.ndarray, frame_shape, corners,
-                 corner_radius: float = 0.0, grain: bool = False):
+                 corner_radius: float = 0.0, grain: bool = False,
+                 blend: str = "replace", reflection: float = DEFAULT_REFLECTION):
         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")
         self.photo = photo
         self.dst_quad = dst_quad
         self.grain = grain
+        self.blend = blend if blend in ("replace", "emissive") else "replace"
+        self.reflection = float(np.clip(reflection, 0.0, 1.0))
 
         top = float(np.linalg.norm(dst_quad[1] - dst_quad[0]))
         bottom = float(np.linalg.norm(dst_quad[2] - dst_quad[3]))
@@ -215,6 +224,31 @@ class Plan:
         self.grade_params = _grade.light_params(
             self.photo, self._prep(frame), self.warped_mask, strength) if strength > 0 else None
 
+    def _blend(self, photo_win, warped_win):
+        """Emitted light over reflected light, or a plain replace.
+
+        `replace` treats the screenshot as paint: the device's own screen
+        surface is discarded. That is right for a reflective surface and wrong
+        for an emissive one — a real display shows EMISSION PLUS the room
+        reflecting off its glass, which is why a switched-off phone reads dark
+        grey and never black. Paint true black onto a lit dashboard and it
+        reads as a hole cut in the render (reported 9 Sep 2026 from an
+        automotive UI that is 56% #000).
+
+        `emissive` composites the screenshot OVER the surface instead, with a
+        screen blend so highlights cannot blow out, and `reflection` scaling how
+        much of the glass survives underneath. The payoff is not only the black
+        level: the specular streak running across the dashboard continues
+        across the screen, and that continuity is what stops a composite
+        reading as an inset panel. No amount of colour-matching can add it,
+        because the surface carrying it has already been thrown away.
+        """
+        if self.blend != "emissive":
+            return warped_win
+        P = photo_win.astype(np.float32) * float(self.reflection)
+        U = warped_win.astype(np.float32)
+        return 255.0 - (255.0 - P) * (255.0 - U) / 255.0
+
     def render(self, frame: np.ndarray, screen_off: np.ndarray = None,
                specular: float = 0.75, fast: bool = False) -> np.ndarray:
         """Composite one frame onto the photo.
@@ -231,15 +265,16 @@ class Plan:
                 warped_screen = _grade.apply_light(warped_screen, self.grade_params)
             out = self.photo.copy()
             win = self.mask3[y0:y1, x0:x1]
+            pw = self.photo[y0:y1, x0:x1]
+            src = self._blend(pw, warped_screen)
             out[y0:y1, x0:x1] = np.clip(
-                self.photo[y0:y1, x0:x1].astype(np.float32) * (1 - win)
-                + warped_screen.astype(np.float32) * win, 0, 255).astype(np.uint8)
+                pw.astype(np.float32) * (1 - win) + src * win, 0, 255).astype(np.uint8)
         else:
             warped_screen = self._prep(frame)
             if self.grade_params is not None:
                 warped_screen = _grade.apply_light(warped_screen, self.grade_params)
-            out = (self.photo.astype(np.float32) * (1 - self.mask3)
-                   + warped_screen.astype(np.float32) * self.mask3)
+            src = self._blend(self.photo, warped_screen)
+            out = (self.photo.astype(np.float32) * (1 - self.mask3) + src * self.mask3)
             out = np.clip(out, 0, 255).astype(np.uint8)
         if self.grain:
             # Seeded, so the grain is IDENTICAL in every frame. Over a still
@@ -254,7 +289,8 @@ class Plan:
 
 def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: float = 0.0,
             grade: float = 0.0, grain: bool = False, screen_off: np.ndarray = None,
-            specular: float = 0.75) -> np.ndarray:
+            specular: float = 0.75, blend: str = "replace",
+            reflection: float = DEFAULT_REFLECTION) -> 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
@@ -265,7 +301,8 @@ def compose(photo: np.ndarray, screenshot: np.ndarray, corners, corner_radius: f
     # specular) now lives in Plan, so the still and video paths run the SAME
     # code and cannot drift apart. See test_video.py: frame 0 of a render is
     # asserted byte-identical to this function's output.
-    plan = Plan(photo, screenshot.shape, corners, corner_radius, grain=grain)
+    plan = Plan(photo, screenshot.shape, corners, corner_radius, grain=grain,
+                blend=blend, reflection=reflection)
     plan.bind_grade(screenshot, grade)
     return plan.render(screenshot, screen_off=screen_off, specular=specular)
 
@@ -349,7 +386,8 @@ def read_frame_at(path: str, index: int = 0):
 def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
                   corner_radius: float = 0.0, grade: float = 0.0, grain: bool = False,
                   preset: str = "web", fit_frame: int = 0, audio: bool = True,
-                  frames_dir: str = None, progress=None) -> dict:
+                  frames_dir: str = None, progress=None, blend: str = "replace",
+                  reflection: float = DEFAULT_REFLECTION) -> 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.
 
@@ -367,7 +405,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
     """
     n_hint, fps, vw, vh = probe_video(video_path)
     first = read_frame_at(video_path, fit_frame)
-    plan = Plan(photo, first.shape, corners, corner_radius, grain=grain)
+    plan = Plan(photo, first.shape, corners, corner_radius, grain=grain,
+                blend=blend, reflection=reflection)
     plan.bind_grade(first, grade)
 
     ph, pw = photo.shape[:2]
@@ -413,7 +452,8 @@ def compose_video(photo: np.ndarray, video_path: str, corners, output: str,
     if count == 0:
         raise RuntimeError(f"no frames could be read from {video_path}")
     return {"frames": count, "fps": fps, "source_size": [vw, vh],
-            "output_size": [pw, ph], "preset": preset, "fit_frame": fit_frame}
+            "output_size": [pw, ph], "preset": preset, "fit_frame": fit_frame,
+            "blend": blend, "reflection": plan.reflection}
 
 
 def main() -> None:

package/skills/inject-screenshot/SKILL.md

@@ -5,10 +5,12 @@ description: Injects a UI screenshot OR a screen recording onto a photographed d
 
 # Inject a screenshot onto a photographed device
 
-**What ships (v0.20):** 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, then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas zoom/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.21):** 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, then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas zoom/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.
 
+**Emissive screen** *(off by default)*: a real display shows its own light **plus** the room reflecting off its glass — which is why a switched-off phone reads dark grey and never black. The default `replace` treats the screenshot as paint and discards the device's own screen surface, so a **true-black UI lands as a hole cut in the photo**, and the specular streak running across a dashboard or a phone stops dead at the screen edge. Turn Emissive on and the screenshot is composited *over* the glass instead: blacks become the device's own surface, and the photo's reflections carry across the screen. The strength sets how much glass shows through — **25–50% is the usable band**, past 75% the content loses contrast. Suggest it whenever the user's UI is dark and the composite reads as a flat inset; the realism pass cannot fix that, because it can only lift uniformly and the surface carrying the gradient has already been thrown away.
+
 **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.
 
 **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, 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

@@ -803,6 +803,23 @@
           </div>
           </div></div>
       </div>
+      <div class="sect" id="secEmissive" data-on="0">
+        <div class="sect-top">
+          <div class="sect-left">
+            <h4>Emissive screen</h4>
+            <button class="info" type="button" aria-label="About emissive screen"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path fill="currentColor" d="M8.36 1.01C12.06 1.2 15 4.26 15 8l-.01.36C14.8 12.06 11.74 15 8 15l-.36-.01C4.06 14.81 1.19 11.94 1.01 8.36L1 8c0-3.87 3.13-7 7-7l.36.01ZM8 2C4.69 2 2 4.69 2 8c0 3.31 2.69 6 6 6 3.31 0 6-2.69 6-6 0-3.31-2.69-6-6-6Zm.5 8l.5 0v1L7 11v-1h.5V7H7V6h1.5v4ZM7.9 4c.33 0 .6.27.6.6a.6.6 0 1 1-1.21 0c0-.33.28-.6.61-.6Z"/></svg><span class="tip" role="tooltip">A real display shows its own light PLUS the room reflecting off its glass — which is why a switched-off phone looks dark grey, never black. Off paints the screenshot on flat, so a true-black UI reads as a hole cut in the photo. On composites it over the glass, so the reflections and highlights already in your photo carry across the screen. Strength sets how much glass shows through.</span></button>
+          </div>
+          <button class="switch" id="emisBtn" role="switch" aria-checked="false" aria-label="Emissive screen">
+            <span class="sw-track"><span class="sw-handle"></span><span class="sw-grip"></span></span>
+          </button>
+        </div>
+        <div class="sect-body"><div class="sect-body-in">
+          <div style="display:grid;gap:var(--s2);justify-items:end">
+            <span class="sm" id="emisVal" style="font-variant-numeric:tabular-nums"></span>
+            <input type="range" id="emisAmt" min="0" max="1" step="0.05" value="0.35" aria-label="Reflection strength">
+          </div>
+          </div></div>
+      </div>
       <div class="sect" id="secEdge" data-on="1">
         <div class="sect-top">
           <div class="sect-left">
@@ -1660,6 +1677,31 @@ $('#gradeBtn').onclick = () => { setGrade(!gradeOn); autoPreview(); };
 $('#gradeAmt').oninput  = e => { gradeAmt = parseFloat(e.target.value); paintGrade(); };
 $('#gradeAmt').onchange = e => { setGrade(true, parseFloat(e.target.value)); autoPreview(); };
 
+/* Emissive screen. A display emits light AND reflects the room; `replace` models
+   only the first, which is why a true-black UI lands as a hole. Off by default so
+   nothing about an existing fit changes. */
+let emisOn  = recall('emis','0') === '1';
+let emisAmt = parseFloat(recall('emisAmt','0.35')) || 0.35;
+function emisValue(){ return emisOn ? emisAmt : null; }
+function paintEmis(){
+  setSwitch($('#emisBtn'), emisOn);
+  $('#emisVal').textContent = Math.round(emisAmt * 100) + '%';
+  const sl = $('#emisAmt');
+  sl.value = emisAmt;
+  sl.style.setProperty('--p', emisAmt);
+}
+function setEmis(on, amt){
+  emisOn = on;
+  if (amt !== undefined) emisAmt = amt;
+  remember('emis', on ? '1' : '0'); remember('emisAmt', String(emisAmt));
+  setSectionOpen($('#secEmissive'), on);
+  paintEmis();
+}
+$('#emisBtn').onclick = () => { setEmis(!emisOn); autoPreview(); };
+$('#emisAmt').oninput  = e => { emisAmt = parseFloat(e.target.value); paintEmis(); };
+$('#emisAmt').onchange = e => { setEmis(true, parseFloat(e.target.value)); autoPreview(); };
+
+
 $('#edgeBtn').onclick = () => setLoupeMode(loupeMode === 'float' ? 'dock' : 'float');
 
 function paintStrip(c, W, H, i){
@@ -1779,7 +1821,7 @@ async function renderPreview(){
   if (!(st.photo && st.shot && st.corners)) return;
   const s = $('#outSt'); s.textContent = 'Rendering…';
   try{
-    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), device: st.type, grade: gradeValue()});
+    const r = await api('/api/preview', {corners: st.corners, radius_frac: radiusValue(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     const im = $('#outImg');
     im.onload = () => { outNat = im.naturalWidth; im.hidden = false; $('#outEmpty').style.display='none'; syncOut(); };
     im.src = `${fileURL(r.path)}&t=${Date.now()}`;
@@ -1850,7 +1892,7 @@ async function renderVideo(){
   b.innerHTML = 'Rendering<span class="spin" aria-hidden="true"></span>';
   try{
     await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), device: st.type,
-                              grade: gradeValue(), preset, fit_frame: +$('#vframe').value});
+                              grade: gradeValue(), reflection: emisValue(), preset, fit_frame: +$('#vframe').value});
   }catch(e){ toast('err','Could not start the render: '+e.message); b.disabled=false; b.textContent='Render'; return; }
   // Poll rather than hold a request open: a clip is hundreds of frames and a
   // browser would time the request out long before the render finished.
@@ -1881,7 +1923,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(), device: st.type, grade: gradeValue()});
+    const r = await api('/api/save', {corners: st.corners, radius_frac: radiusValue(), device: st.type, grade: gradeValue(), reflection: emisValue()});
     b.textContent = 'Save';
     // The real destination, not a hardcoded one: --out-dir means saves usually
     // land in the project folder now, and telling the user "~/Desktop" when
@@ -1941,6 +1983,7 @@ $('#imp').onclick = async () => {
   }
   setLoupeMode(loupeMode);
   setGrade(gradeOn, gradeAmt);
+  setEmis(emisOn, emisAmt);
   setRadiusOn(radiusOn);
   sectionsBooted = true;   // animate from here on, not during the first paint
   // Compare is the DEFAULT view: judging a fit means comparing it with the