screengraft 0.24.1 → 0.25.2

package/README.md

@@ -76,7 +76,7 @@ npx screengraft --out-dir ./mockups
 ```
 
 npm is a delivery mechanism here, not a claim about the language: the tool is
-Python and OpenCV, and `bin/screengraft.js` is a launcher. It installs nothing
+Python and OpenCV, and `cli/screengraft.js` is a launcher. It installs nothing
 behind your back — if the engine is missing it prints the one command that
 builds it (`npx screengraft --install`) and exits.
 
@@ -138,15 +138,25 @@ you, and nothing below ever touches it.
 
 **Working files** live in `~/.screengraft/sessions/<timestamp>/` — one directory
 per run. A source you pick by path is never copied: screengraft reads it where it
-is. A source you drag in or browse to has to be copied, because a browser hands
-over bytes and will not say where they came from — and that copy, along with the
-preview and thumbnails, is **deleted when the run ends**. Anything left behind by
-a crash is swept the next time you launch.
-
-What survives is the `result.json` sidecar: a few hundred bytes recording the
-corners, radius, grade and blend of that fit, referencing your original files by
-path. It reproduces a composite exactly, and it is the first thing a bug report
-should include. Keep the recipe, not the ingredients.
+is, and screengraft never deletes a file of yours. A source you drag in or browse
+to has to be copied, because a browser hands over bytes and will not say where
+they came from.
+
+What happens to that copy depends on whether the run produced anything:
+
+- **A run that saved a mockup keeps its source.** The `result.json` sidecar names
+  it, and a recipe naming a file that no longer exists is not a recipe.
+- **A run that produced nothing keeps nothing.** That is the common case and
+  where the disk goes — previews, thumbnails, poster frames and abandoned
+  uploads are all swept when the run ends, or at the next launch after a crash.
+
+What survives either way is the `result.json` sidecar: a few hundred bytes
+recording the corners, radius, grade and blend of that fit. It reproduces a
+composite exactly, and it is the first thing a bug report should include.
+
+Sidecars written by v0.23.0–v0.25.1 may name a dragged-in source that release
+deleted. Those cannot be repaired — the bytes are gone — but screengraft now
+marks them `"source_retained": false` rather than leaving them looking valid.
 
 
 ## Roadmap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.24.1",
+  "version": "0.25.2",
   "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",
@@ -33,10 +33,10 @@
   },
   "type": "commonjs",
   "bin": {
-    "screengraft": "bin/screengraft.js"
+    "screengraft": "cli/screengraft.js"
   },
   "files": [
-    "bin/",
+    "cli/",
     "scripts/",
     "ui/",
     "mcp/",
@@ -61,6 +61,6 @@
     "linux"
   ],
   "scripts": {
-    "start": "node bin/screengraft.js"
+    "start": "node cli/screengraft.js"
   }
 }

package/scripts/grade.py

@@ -130,21 +130,46 @@ def match_light(photo: np.ndarray, warped: np.ndarray, mask: np.ndarray,
     return apply_light(warped, light_params(photo, warped, mask, strength))
 
 
+GRAIN_GATE = 20.0        # grey levels: above this a residual is an edge, not grain
+_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%)
+
+
 def measure_grain(photo: np.ndarray, ring: np.ndarray) -> float:
     """The photo's noise floor, in grey levels, measured where the screen isn't.
 
-    High-pass with a 3x3 median (cheap, edge-preserving) and take the MEDIAN
-    absolute deviation of the residual rather than its standard deviation: a
-    bezel edge or a highlight inside the ring is a huge outlier, and a mean-based
-    estimate would read the edge as noise and dump visible grain on the screen.
-    0.6745 converts MAD to a sigma for a normal distribution.
+    High-pass with a 3x3 median (cheap, edge-preserving), gate the outliers off,
+    then take the MEAN absolute deviation of what is left.
+
+    Why the mean and not the median: `photo` is uint8 and so is the
+    median blur, so the residual is integer-valued, and a median of integers is
+    an integer or a half. The old MAD/0.6745 could therefore only ever return
+    multiples of 1.4826 — and under one grey level it returned a flat 0, so a
+    lightly-noisy photograph got no grain at all. Two of the three surviving
+    reference photos measured exactly 0.0 that way while actually carrying 0.39
+    and 1.46. A mean over the same integers resolves continuously.
+
+    Robustness moves from the statistic to the GATE. A 3x3 median is
+    edge-preserving, so a clean step edge leaves a residual of exactly 0 and was
+    never the danger the old docstring guarded against; what does leak is fine
+    repeating texture and specks, whose residuals are large. Discarding
+    |resid| > GRAIN_GATE drops those and leaves the noise floor untouched:
+    identical for any gate in 8..40, unbiased out to sigma 4, and 5x below the
+    smallest texture residual that breaks it — a 9px-pitch line pattern reads
+    27.0 ungated against a true 1.0.
+
+    0.7979 is E|X|/sigma for a normal; _MEDIAN_HP_GAIN undoes the noise the
+    median filter itself absorbs.
     """
     g = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
     resid = g.astype(np.float32) - cv2.medianBlur(g, 3).astype(np.float32)
     px = resid[ring.astype(bool)]
     if px.size < 500:
         return 0.0
-    return float(np.median(np.abs(px - np.median(px))) / 0.6745)
+    px = px[np.abs(px) <= GRAIN_GATE]
+    if px.size < 500:
+        return 0.0
+    return float(np.mean(np.abs(px - px.mean())) / 0.7979 / _MEDIAN_HP_GAIN)
 
 
 def add_grain(img: np.ndarray, mask: np.ndarray, sigma: float, seed: int = 0) -> np.ndarray:

package/scripts/ui.py

@@ -155,14 +155,54 @@ _RESIDUE_PREFIXES = ("photo-", "screenshot-", "poster-", "frame-")
 _RESIDUE_NAMES = ("preview.png", "figma-export.png")
 
 
+def _sidecar_sources(d):
+    """Absolute paths inside `d` that this session's result.json still names.
+
+    v0.23.0 swept these too, and the sidecar's whole promise is that a fit can
+    be re-run from it. That promise held for a source picked by PATH, which
+    was never copied -- and quietly broke for a drag-drop or browse, where the
+    browser hands over bytes with no origin and the copy in the session IS the
+    original as far as the sidecar is concerned. Measured after the first sweep:
+    9 of 9 such sidecars pointed at a deleted file.
+
+    So the rule is now: a session that produced output keeps what its sidecar
+    names. A session that produced nothing keeps nothing -- there is no recipe
+    to protect, which is the common case and where the volume is.
+
+    Only paths INSIDE the session are returned. A path-picked source lives in
+    the user's own folders and was never ours to keep or delete.
+
+    Note the sidecar is rewritten on every save, so it names the LAST fit. An
+    earlier source replaced within the same session is not protected: the record
+    is what survives, and the record says what it says.
+    """
+    try:
+        with open(os.path.join(d, "result.json")) as f:
+            res = json.load(f)
+    except (OSError, ValueError):
+        return set()
+    root = os.path.realpath(d)
+    keep = set()
+    for key in ("photo", "screenshot"):
+        p = res.get(key)
+        if not p:
+            continue
+        rp = os.path.realpath(p)
+        if rp == root or rp.startswith(root + os.sep):
+            keep.add(rp)
+    return keep
+
+
 def _sweep_session(d):
     """Delete a session's copied and derived media. Returns bytes reclaimed.
 
-    Never touches *.json, and never touches OUT_DIR -- the actual outputs live
-    in the project folder and are the point of the whole exercise.
+    Never touches *.json, never touches OUT_DIR -- the actual outputs live in
+    the project folder and are the point of the whole exercise -- and never
+    touches a source the session's own result.json still names (see above).
     """
     freed = 0
     thumbs = os.path.join(d, "thumbs")
+    protected = _sidecar_sources(d)
     for base, _, files in os.walk(d):
         for f in files:
             keep = f.endswith(".json")
@@ -171,6 +211,8 @@ def _sweep_session(d):
             if keep or not residue:
                 continue
             fp = os.path.join(base, f)
+            if os.path.realpath(fp) in protected:
+                continue
             try:
                 freed += os.path.getsize(fp)
                 os.remove(fp)
@@ -179,6 +221,39 @@ def _sweep_session(d):
     return freed
 
 
+def _mark_unreproducible(d):
+    """Stamp a sidecar whose named source no longer exists.
+
+    For the sessions v0.23.0 already swept, nothing can be recovered -- the
+    bytes are gone and the browser never said where they came from. What can be
+    fixed is the claim: a sidecar that names a deleted file reads exactly like
+    one that works, and the difference only shows up when someone tries to
+    re-run it. `source_retained: false` says so up front.
+
+    Idempotent, and it never touches a sidecar whose files are intact.
+    """
+    path = os.path.join(d, "result.json")
+    try:
+        with open(path) as f:
+            res = json.load(f)
+    except (OSError, ValueError):
+        return False
+    if "source_retained" in res:
+        return False
+    named = [res.get(k) for k in ("photo", "screenshot")]
+    if not any(named) or all(p and os.path.exists(p) for p in named if p):
+        return False
+    res["source_retained"] = False
+    tmp = path + ".tmp"
+    try:
+        with open(tmp, "w") as f:
+            json.dump(res, f, indent=1)
+        os.replace(tmp, path)
+    except OSError:
+        return False
+    return True
+
+
 def _prune_sessions(keep):
     """Sweep every session but the live one, at launch.
 
@@ -191,7 +266,10 @@ def _prune_sessions(keep):
     /api/use records the path and reads through it. Only a drag-drop or a browse
     has to be copied, because the browser hands over bytes and will not say
     where they came from. So this is the other half of the same policy: what
-    cannot avoid being copied does not outlive the run that needed it.
+    cannot avoid being copied does not outlive the run that needed it --
+    UNLESS the run produced something, in which case its sidecar names the
+    source and _sweep_session keeps it. See _sidecar_sources: reproducibility
+    beats disk exactly where a fit actually happened, and nowhere else.
     """
     root = os.path.dirname(keep)
     freed = 0
@@ -204,6 +282,10 @@ def _prune_sessions(keep):
         if d == keep or not os.path.isdir(d):
             continue
         freed += _sweep_session(d)
+        # After sweeping, not before: a sidecar is only unreproducible once its
+        # source is actually gone, and from here on the sweep leaves it alone.
+        # This is for the sessions the previous release already emptied.
+        _mark_unreproducible(d)
     return freed
 
 

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.24):** 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 — 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.25):** 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 — 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.
 

package/ui/index.html

@@ -101,12 +101,27 @@
 
   /* The shell IS the viewport. Nothing scrolls except the canvas, so the
      fitting surface can never be pushed off-screen by finished work. */
-  .app{height:100%;display:grid;grid-template-rows:auto minmax(0,1fr) auto;min-height:0;
+  /* The ROWS were given minmax(0,1fr) and the column was left implicit,
+     which means `auto` — and an auto track is floored at its content's
+     min-content width, so the whole app grew to 896px inside a 742px viewport
+     and the page scrolled sideways. Same discipline, same axis: a track that
+     may not exceed its share needs the 0 minimum stated. This is the root of
+     the overflow; the topbar and #stage reported with it were victims, sized by
+     a container that had already grown. */
+  .app{height:100%;display:grid;grid-template-rows:auto minmax(0,1fr) auto;
+       grid-template-columns:minmax(0,1fr);min-height:0;
        padding-bottom:32px;background:var(--bg)}
 
   .topbar{display:flex;align-items:center;gap:8px;padding:0 12px 0 var(--s4);height:56px;
           background:var(--card);border-bottom:1px solid var(--line);
           box-shadow:inset 0 1px 0 rgba(255,255,255,.04), 0 1px 0 rgba(0,0,0,.25)}
+  /* A nowrap flex row whose children keep min-width:auto cannot shrink
+     below their content, so at 742px Save and Send to Claude sat at x=750..885
+     — outside the viewport and unclickable. The chips carry a filename and are
+     the part that should give; the actions are fixed-size and must not. */
+  .topbar > *{min-width:0}
+  .tb-chips{overflow:hidden}
+  .tb-actions{flex:none}
   .tb-left{display:flex;align-items:center;gap:var(--s9)}
   .tb-chips{display:flex;align-items:center;gap:var(--s2)}
   .tb-arrow{color:var(--mute)}
@@ -302,7 +317,12 @@
     .stage > .rail{grid-column:2;grid-row:1 / span 2}
   }
   #types{flex-wrap:nowrap}
+  /* The same omission one level down: rows constrained, column implicit.
+     min-width:0 lets the PANE shrink; it does nothing for the auto track
+     inside it, which was still sizing to the header's min-content — 798px
+     wide in a 398px column. */
   .pane{min-width:0;min-height:0;display:grid;grid-template-rows:auto minmax(0,1fr);
+        grid-template-columns:minmax(0,1fr);
         position:relative;   /* the frame the corner bar is anchored to */
         border-right:1px solid var(--line)}
   .panehead{display:flex;align-items:center;gap:var(--s2);padding:var(--s2) var(--s4);background:var(--card);