screengraft 0.60.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screengraft",
-  "version": "0.60.0",
+  "version": "0.61.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/recents.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+screengraft -- the images a designer has actually used, per role.
+
+The picker used to list whatever was newest on ~/Desktop and ~/Downloads. That
+is a guess about where files live; this is a record of what was chosen. Every
+source that reaches the session through /api/use or /api/upload is written
+here, newest first, one list per role (a photograph of a device and a
+screenshot to put on it are different populations), and the picker shows the
+ones that still exist on disk.
+
+Store: ~/.screengraft/recents.json
+  {"photo": [{"path": ..., "name": ..., "used": <epoch>}, ...], "screenshot": [...]}
+
+An uploaded file's path is its session copy, which the launch-time sweep
+removes when nothing was saved from that session -- so an upload stays recent
+only as long as its session does. A file chosen by path is read through in
+place and stays for as long as the file does.
+
+First run: seeds itself from the sessions that already exist, oldest first,
+so the list is not empty for someone who has been using the tool for a week.
+"""
+import json
+import os
+import time
+
+ROLES = ("photo", "screenshot")
+CAP = 60
+
+
+def store_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".screengraft", "recents.json")
+
+
+def _load() -> dict:
+    try:
+        with open(store_path()) as f:
+            d = json.load(f)
+        if not isinstance(d, dict):
+            raise ValueError
+    except (OSError, ValueError):
+        d = _seed()
+    for r in ROLES:
+        d.setdefault(r, [])
+    return d
+
+
+def _save(d: dict):
+    p = store_path()
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    tmp = p + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(d, f, indent=1)
+    os.replace(tmp, p)
+
+
+def _seed() -> dict:
+    """Once: what the existing sessions say was used, in the order they ran."""
+    d = {r: [] for r in ROLES}
+    root = os.path.join(os.path.expanduser("~"), ".screengraft", "sessions")
+    try:
+        names = sorted(os.listdir(root))
+    except OSError:
+        return d
+    for n in names:
+        sp = os.path.join(root, n, "state.json")
+        try:
+            with open(sp) as f:
+                st = json.load(f)
+            used = os.path.getmtime(sp)
+        except (OSError, ValueError):
+            continue
+        for r in ROLES:
+            p = st.get(r)
+            if isinstance(p, str) and os.path.isfile(p):
+                _push(d, r, p, used)
+    return d
+
+
+def _push(d: dict, role: str, path: str, used: float):
+    lst = [e for e in d[role] if e.get("path") != path]
+    lst.insert(0, {"path": path, "name": os.path.basename(path), "used": used})
+    d[role] = lst[:CAP]
+
+
+def record(role: str, path: str):
+    if role not in ROLES or not path:
+        return
+    d = _load()
+    _push(d, role, os.path.realpath(path), time.time())
+    _save(d)
+
+
+def items(role: str, limit: int = 40) -> list:
+    """Newest-used first, only what still exists; dead entries are dropped."""
+    if role not in ROLES:
+        return []
+    d = _load()
+    live, out = [], []
+    for e in d[role]:
+        p = e.get("path")
+        if not (isinstance(p, str) and os.path.isfile(p)):
+            continue
+        live.append(e)
+        try:
+            st = os.stat(p)
+        except OSError:
+            continue
+        out.append({"path": p, "name": e.get("name") or os.path.basename(p), "used": e.get("used", 0),
+                    "mtime": st.st_mtime, "bytes": st.st_size,
+                    "ext": os.path.splitext(p)[1].lower(),
+                    "folder": _short_folder(os.path.dirname(p))})
+    if len(live) != len(d[role]):
+        d[role] = live
+        _save(d)
+    return out[:limit]
+
+
+def _short_folder(dirpath: str) -> str:
+    home = os.path.expanduser("~")
+    if dirpath.startswith(os.path.join(home, ".screengraft", "sessions")):
+        return "dropped in"
+    if dirpath.startswith(home + os.sep):
+        return "~" + dirpath[len(home):]
+    return dirpath

package/scripts/ui.py

@@ -50,6 +50,7 @@ import numpy as np  # noqa: E402
 import detect as D  # noqa: E402
 import fitfile as FF  # noqa: E402
 import fits as FIT  # noqa: E402
+import recents as RECENT  # noqa: E402
 import dof as DOF   # noqa: E402
 import grade as _grade  # noqa: E402
 import scan as S  # noqa: E402
@@ -727,6 +728,25 @@ def _dof_args(b):
 ROLES = ("photo", "screenshot")
 
 
+def _thumb_for(item):
+    """A thumbnail for a recent: scan.thumb for stills; the first frame for a clip."""
+    out_dir = os.path.join(SESSION.dir, "thumbs")
+    if item.get("ext") in VIDEO_EXT:
+        os.makedirs(out_dir, exist_ok=True)
+        out = os.path.join(out_dir, f"{abs(hash(item['path']))}_{int(item.get('mtime') or 0)}_clip.jpg")
+        if not os.path.exists(out):
+            try:
+                fr = W.read_frame_at(item["path"], 0)
+                h, w = fr.shape[:2]
+                sc = 320 / max(h, w)
+                fr = cv2.resize(fr, (max(1, int(w * sc)), max(1, int(h * sc))), interpolation=cv2.INTER_AREA)
+                cv2.imwrite(out, fr, [cv2.IMWRITE_JPEG_QUALITY, 80])
+            except Exception:
+                return None
+        return out
+    return S.thumb(item, out_dir)
+
+
 def _adopt(role, path):
     """Make a chosen source the session's, and answer what the page needs.
 
@@ -751,6 +771,7 @@ def _adopt(role, path):
         im, real = _read_image(path)
         meta = {"video": False}
     SESSION.update(**{role: real})
+    RECENT.record(role, real)
     if role == "photo":
         # The quad is a property of the PHOTOGRAPH, so a fit saved on an earlier
         # run is a better starting position than any detector -- and a stronger
@@ -956,10 +977,15 @@ class Handler(BaseHTTPRequestHandler):
                                    "home": HOME, "presets": PRESETS, "version": VERSION,
                                    "build": BUILD})
             if u.path == "/api/recent":
-                items = S.scan(days=int(q.get("days", ["14"])[0]), limit=int(q.get("limit", ["40"])[0]))
+                # What was USED, per role -- not what is newest in two folders.
+                # The folder scan (scan.py) still exists for the CLI and for a
+                # first run with nothing used yet; ?role= selects the list.
+                role = (q.get("role") or ["photo"])[0]
+                limit = int(q.get("limit", ["40"])[0])
+                items = RECENT.items(role, limit)
                 for it in items:
-                    it["thumb"] = S.thumb(it, os.path.join(SESSION.dir, "thumbs"))
-                return self._json({"items": items})
+                    it["thumb"] = _thumb_for(it)
+                return self._json({"items": items, "role": role})
             if u.path == "/file":
                 return self._file(_safe_local_path(q["path"][0]))
             if u.path == "/api/job":

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.60):** 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.61):** 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** (the images you have used before, 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".
 
@@ -68,7 +68,7 @@ It prints one JSON line — `url`, `base`, `token`, `session`, `job`, `result`,
 
 > **What this does** — it computes the perspective between your photo and your screenshot, so the screenshot lands on the glass exactly. Geometry, not AI: nothing is invented and your pixels are unchanged.
 >
-> **1 · Choose a photo, then a screenshot — or a screen recording.** Recent images from Desktop and Downloads are listed for you — or drag a file in, browse, paste a path, or paste a Figma frame link and I'll export it. A video source (mp4/mov/webm) works the same way; you'll pick which frame to match the edges on.
+> **1 · Choose a photo, then a screenshot — or a screen recording.** The images you have used before are listed for you — or drag a file in, browse, paste a path, or paste a Figma frame link and I'll export it. A video source (mp4/mov/webm) works the same way; you'll pick which frame to match the edges on.
 >
 > **2 · Match the four edges to the screen.** Drag an edge's middle to slide it, or near an end to pivot — only that edge moves. The magnified strip below shows the boundary straightened, so aligned reads as flat. Arrow keys nudge 1px, Shift+arrow 10px, Tab moves to the next edge.
 >
@@ -148,7 +148,8 @@ The server is a detached daemon with no window. **Stop it with `scripts/stop.sh`
 | `scripts/ui.py` | Local server + browser UI; calls the two below |
 | `scripts/detect.py` | Advisory screen-quad + corner-radius detection (no ML) |
 | `scripts/warp.py` | The engine: `compose()` and a CLI for scripted use |
-| `scripts/scan.py` | Recent images on Desktop/Downloads, thumbnails |
+| `scripts/recents.py` | The images used before, per role (`~/.screengraft/recents.json`) |
+| `scripts/scan.py` | Desktop/Downloads scan and thumbnails (CLI; the picker no longer uses the scan) |
 | `ui/index.html` | The page |
 
 Design rationale and the roadmap live with the project's own notes, not in the plugin.

package/ui/index.html

@@ -1020,24 +1020,34 @@
   }
   .pop h3{margin:0 0 4px;font-size:14px;font-weight:600}
   .pop .sub{color:var(--mute);font-size:12px;margin:0 0 16px;line-height:1.5}
-  .picker{display:grid;grid-template-columns:180px minmax(0,1fr);gap:12px;align-items:start}
-  .rail2{display:flex;flex-direction:column;gap:4px;max-height:300px;overflow:auto;padding:2px}
-  .th{display:flex;align-items:center;gap:10px;padding:6px;border-radius:var(--r-md);cursor:pointer;
-      border:1px solid transparent;background:var(--sunk);
+  /* The preview slot is as tall as the list beside it (stretch, not start),
+     and the list has a floor so an empty or short list still leaves a slot
+     worth previewing into. 14 Sep 2026, on request. */
+  .picker{display:grid;grid-template-columns:200px minmax(0,1fr);gap:12px;align-items:stretch}
+  .rail2{display:flex;flex-direction:column;gap:2px;min-height:240px;max-height:300px;overflow:auto;padding:2px}
+  /* A list item at rest is the picture and its name on the popover's own
+     surface -- no fill, no stroke. Hover raises it; the chosen one is the
+     raised neutral every selected thing on this page uses (not the accent:
+     the accent is for the next action). */
+  .th{display:flex;align-items:center;gap:10px;padding:4px 6px;border-radius:var(--r-sm);cursor:pointer;
+      border:var(--bw) solid transparent;background:transparent;min-width:0;
       transition:var(--t-all)}
-  .th:hover{border-color:var(--edge-hi);background:var(--raise)}
-  .th img{width:40px;height:40px;object-fit:cover;border-radius:6px;flex:none;background:var(--card)}
-  .th .cap{font-size:11.5px;color:var(--mute);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-  .th.sel{border-color:var(--acc);background:var(--acc-soft)}
+  .th:hover{background:var(--raise);border-color:var(--edge)}
+  .th img{width:40px;height:40px;object-fit:cover;border-radius:4px;flex:none;background:var(--sunk)}
+  .th .cap{min-width:0;display:grid;gap:1px}
+  .th .nm{font-size:12px;color:var(--ink);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+  .th .when{font-size:11px;color:var(--mute);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+  .th.sel{background:var(--raise-hi);border-color:var(--edge-hi)}
   /* The preview frame sits INSIDE the popover, so --well (#0a0a0b, the canvas
      tone) read as a hole punched in it. --sunk is the system's recessed surface:
      lighter than the well, still clearly below --float, and it matches the
      thumbnail rail beside it. The stroke moves to --edge so the frame still has
      an edge now that its fill is closer to the surface behind it. */
-  .pv{border-radius:var(--r-md);background:var(--sunk);min-height:210px;
-      display:grid;place-items:center;overflow:hidden;box-shadow:inset 0 0 0 1px var(--edge)}
+  /* No stroke (14 Sep 2026): the recessed surface alone marks the slot. */
+  .pv{border-radius:var(--r-md);background:var(--sunk);min-height:0;
+      display:grid;place-items:center;overflow:hidden}
   .pv img{max-width:100%;max-height:300px;object-fit:contain;display:block}
-  .drop{border:1px dashed var(--edge);border-radius:var(--r-md);padding:14px;text-align:center;
+  .drop{border:var(--bw) dashed var(--edge);border-radius:var(--r-md);padding:30px 14px;text-align:center;
         color:var(--mute);cursor:pointer;margin-top:12px;font-size:12px;
         transition:var(--t-all)}
   .drop:hover{border-color:var(--edge-hi);color:var(--ink)}
@@ -1313,7 +1323,7 @@
 
 <div class="pop" id="pop1">
   <h3>Photo of the device</h3>
-  <p class="sub">Recent images from Desktop and Downloads — click one. Or browse, drop a file, or paste a path.</p>
+  <p class="sub">Photos you have used before — click one. Or browse, drop a file, or paste a path.</p>
   <div class="picker">
     <div class="rail2" id="recent1"></div>
     <div class="pv" id="pv1"><span class="empty">Select a recent image</span></div>
@@ -1693,17 +1703,29 @@ addEventListener('drop', e => {
 }, true);
 
 /* ===== pickers (popovers over the canvas) ===== */
+// "Used 3 h ago", "used yesterday" -- when a source was last chosen.
+function agoText(t){
+  const s = Math.max(0, Date.now()/1000 - t);
+  if (s < 90) return 'just now';
+  if (s < 3600) return Math.round(s/60) + ' min ago';
+  if (s < 86400) return Math.round(s/3600) + ' h ago';
+  if (s < 172800) return 'yesterday';
+  return Math.round(s/86400) + ' days ago';
+}
+const esc = t => String(t).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
 async function loadRecent(){
-  const {items} = await api('/api/recent?days=14&limit=40');
-  for (const id of ['recent1','recent2']){
+  // What was USED before, per role -- the photo list and the screenshot list
+  // are different populations (a device photo is never a screenshot).
+  for (const [id, role] of [['recent1','photo'],['recent2','screenshot']]){
+    const {items} = await api('/api/recent?role=' + role + '&limit=40');
     const g = $('#'+id); g.innerHTML='';
     for (const it of items){
       const d = document.createElement('div'); d.className='th'; d.title = it.path;
-      d.innerHTML = `<img src="${it.thumb ? fileURL(it.thumb) : ''}" alt=""><div class="cap">${it.name}</div>`;
-      d.onclick = () => choose(id==='recent1'?'photo':'screenshot', it.path, d);
+      d.innerHTML = `<img src="${it.thumb ? fileURL(it.thumb) : ''}" alt=""><div class="cap"><div class="nm">${esc(it.name)}</div><div class="when">${agoText(it.used)} · ${esc(it.folder)}</div></div>`;
+      d.onclick = () => choose(role, it.path, d);
       g.appendChild(d);
     }
-    if (!items.length) g.innerHTML = '<span class="sm" style="color:var(--mute)">No recent images on Desktop/Downloads (last 14 days).</span>';
+    if (!items.length) g.innerHTML = '<span class="sm" style="color:var(--mute);padding:6px">Nothing used yet — drop a file below, browse, or paste a path.</span>';
   }
 }
 /* Un-choose a source. The mirror of setChosen(): every visual the fill put up