screengraft 0.21.0 → 0.24.1

package/README.md

@@ -130,6 +130,25 @@ outside the screen mask. It never touches the pixels you designed.
    crawl. Frame 0 of a render is byte-identical to the still composite — the
    test suite asserts it, because that is what stops the two paths drifting.
 
+## Where screengraft keeps things
+
+**Your output** goes to the folder you launched with (`--out-dir`), which the
+Claude skill points at your project. That is the only place anything is kept for
+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.
+
+
 ## Roadmap
 
 Done: manual warp, advisory detectors, the fitting workbench, the realism pass,
@@ -146,6 +165,22 @@ the background is itself neutral (a pale tiled floor, a plain wall) — you plac
 the edges by hand there. And a prototype recording has no motion blur, so a very
 fast scroll will strobe; that is a property of the source, not of the composite.
 
+## Changelog
+
+Every release is described in [CHANGELOG.md](CHANGELOG.md), with the
+measurements that drove it.
+
+## Support
+
+Bugs and photographs that defeat the detector belong in
+[Issues](https://github.com/seq000/screengraft/issues) — the bug template asks
+first for the `result.json` sidecar, because it reproduces any composite
+exactly. Ideas and "can it do X" go in
+[Discussions](https://github.com/seq000/screengraft/discussions).
+
+If the photograph or the UI is confidential — a client shot, something
+unreleased — email **screengraft@fraczyk.design** instead of posting it.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: there are tests, they

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "screengraft",
-  "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.",
+  "version": "0.24.1",
+  "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",
     "device-frame",
@@ -17,7 +17,10 @@
     "figma"
   ],
   "homepage": "https://github.com/seq000/screengraft#readme",
-  "bugs": "https://github.com/seq000/screengraft/issues",
+  "bugs": {
+    "url": "https://github.com/seq000/screengraft/issues",
+    "email": "screengraft@fraczyk.design"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/seq000/screengraft.git"
@@ -25,7 +28,8 @@
   "license": "MIT",
   "author": {
     "name": "Dariusz Fraczyk",
-    "url": "https://fraczyk.design"
+    "url": "https://fraczyk.design",
+    "email": "screengraft@fraczyk.design"
   },
   "type": "commonjs",
   "bin": {

package/scripts/detect.py

@@ -490,7 +490,22 @@ def validate_quad(corners: np.ndarray, contour, img_area: float, img_shape=None)
     return True, ""
 
 
-def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None):
+def contains(quad, point) -> bool:
+    """Is `point` inside this quad? The whole of the click feature, in one line.
+
+    A click cannot make a bad candidate good, and it is not asked to. It answers
+    the one question the pixels cannot: WHICH of the regions we already found is
+    the screen. Measured on the two photos that defeated every detector, the
+    correct quad was already in the candidate list both times -- 23 of 93
+    candidates contained the click on one, 16 of 118 on the other -- so the
+    failure was never detection, it was selection.
+    """
+    return cv2.pointPolygonTest(np.asarray(quad, np.float32),
+                                (float(point[0]), float(point[1])), False) >= 0
+
+
+def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None,
+              click=None):
     """Best candidate that survives refinement AND validation.
 
     Walks candidates best-score-first rather than trusting the top one: a
@@ -506,6 +521,12 @@ def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None):
     78px off an otherwise correct quad . The polygon approximation of a
     Canny boundary is already on the edge, so there is nothing to recover.
     """
+    if click is not None:
+        # Before ranking, not after: the point of the click is to shrink the
+        # field to the things the user actually pointed at, and let the existing
+        # score decide among those. Ranking first and filtering after would just
+        # re-confirm whichever candidate already won.
+        candidates = [c for c in candidates if contains(c[1], click)]
     rejected = []
     for cand in sorted(candidates, key=lambda c: c[0], reverse=True):
         score, quad, contour, tag = pick_innermost(candidates, cand)
@@ -529,7 +550,7 @@ def _finalize(candidates, img_area: float, refine: bool = True, img_shape=None):
     return None
 
 
-def detect_tone(gray: np.ndarray, tone=None):
+def detect_tone(gray: np.ndarray, tone=None, click=None):
     """Tone-band segmentation. Assumes the screen sits in a narrow tone band."""
     h, w = gray.shape[:2]
     img_area = float(h * w)
@@ -560,7 +581,7 @@ def detect_tone(gray: np.ndarray, tone=None):
             score *= (16.0 / (hi - lo + 1)) ** 0.25
             candidates.append((score, order_quad(quad), contour, (lo, hi)))
 
-    res = _finalize(candidates, img_area, img_shape=gray.shape[:2])
+    res = _finalize(candidates, img_area, img_shape=gray.shape[:2], click=click)
     if res is None:
         return None
     band = res.pop("_tag")
@@ -569,7 +590,7 @@ def detect_tone(gray: np.ndarray, tone=None):
     return res
 
 
-def detect_edges(gray: np.ndarray):
+def detect_edges(gray: np.ndarray, click=None):
     """Canny-and-quad detection — the document-scanner path.
 
     Tone banding assumes a near-uniform screen, which breaks the moment the
@@ -608,7 +629,7 @@ def detect_edges(gray: np.ndarray):
             if score > 0 and quad is not None:
                 candidates.append((score, order_quad(quad), c, (lo, hi)))
 
-    res = _finalize(candidates, img_area, refine=False, img_shape=gray.shape[:2])
+    res = _finalize(candidates, img_area, refine=False, img_shape=gray.shape[:2], click=click)
     if res is None:
         return None
     thr = res.pop("_tag")
@@ -617,7 +638,7 @@ def detect_edges(gray: np.ndarray):
     return res
 
 
-def detect_saturation(bgr: np.ndarray):
+def detect_saturation(bgr: np.ndarray, click=None):
     """Neutral-region segmentation — the third detector, and the only one that
     looks at colour.
 
@@ -654,7 +675,7 @@ def detect_saturation(bgr: np.ndarray):
                 candidates.append((score * (32.0 / max(thr, 1)) ** 0.25,
                                    order_quad(quad), contour, thr))
 
-    res = _finalize(candidates, img_area, img_shape=sat.shape[:2])
+    res = _finalize(candidates, img_area, img_shape=sat.shape[:2], click=click)
     if res is None:
         return None
     res.pop("_tag")
@@ -681,7 +702,7 @@ def has_rounded_corners(result) -> bool:
     return spread <= MAX_RADIUS_SPREAD
 
 
-def detect(gray: np.ndarray, tone=None, method="auto", color=None):
+def detect(gray: np.ndarray, tone=None, method="auto", color=None, click=None):
     """Run both detectors; arbitrate on how the two quads nest.
 
     The two fail on opposite things. Tone banding needs a tonally uniform
@@ -707,15 +728,15 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None):
     """
     results = []
     if method in ("auto", "tone"):
-        r = detect_tone(gray, tone)
+        r = detect_tone(gray, tone, click=click)
         if r:
             results.append(r)
     if method in ("auto", "edge") and tone is None:
-        r = detect_edges(gray)
+        r = detect_edges(gray, click=click)
         if r:
             results.append(r)
     if method in ("auto", "saturation") and tone is None and color is not None:
-        r = detect_saturation(color)
+        r = detect_saturation(color, click=click)
         if r:
             results.append(r)
 
@@ -842,7 +863,14 @@ def detect(gray: np.ndarray, tone=None, method="auto", color=None):
     # the thing found is shaped like a screen, which is what abstention exists
     # to doubt. Without this a good saturation result on a hard photo would be
     # thrown away for want of a second opinion.
-    uncorroborated = bool(not ag.get("agree")
+    # A click IS corroboration, and the strongest kind available: a person
+    # looked at the photograph and said "the screen is here". Abstaining for
+    # want of a second algorithm after that would be refusing the only evidence
+    # that outranks the algorithms. Gross disagreement between two credible
+    # peers still counts -- that says the click landed somewhere ambiguous, and
+    # is worth reporting -- but being alone no longer does.
+    uncorroborated = bool(click is None
+                          and not ag.get("agree")
                           and not best["corner_radius"]["confident"]
                           and not has_rounded_corners(best))
     if gross or uncorroborated:

package/scripts/ui.py

@@ -144,6 +144,159 @@ class Session:
 SESSION: Session = None
 
 
+# Media a session COPIES rather than produces for keeps. Everything here is
+# either a duplicate of a file the user already has, or something regenerable
+# from the sidecar in seconds. The sidecar and state are not in the list: they
+# are a few hundred bytes and they are the record of what was fitted, with the
+# ORIGINAL paths in them. Keep the recipe, stop keeping the ingredients.
+_RESIDUE_PREFIXES = ("photo-", "screenshot-", "poster-", "frame-")
+# figma-export.png is a copy too -- the agent fetches the frame and drops it
+# here -- and re-exporting is one MCP round trip, so it is residue like the rest.
+_RESIDUE_NAMES = ("preview.png", "figma-export.png")
+
+
+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.
+    """
+    freed = 0
+    thumbs = os.path.join(d, "thumbs")
+    for base, _, files in os.walk(d):
+        for f in files:
+            keep = f.endswith(".json")
+            residue = (f.startswith(_RESIDUE_PREFIXES) or f in _RESIDUE_NAMES
+                       or base == thumbs)
+            if keep or not residue:
+                continue
+            fp = os.path.join(base, f)
+            try:
+                freed += os.path.getsize(fp)
+                os.remove(fp)
+            except OSError:
+                pass
+    return freed
+
+
+def _prune_sessions(keep):
+    """Sweep every session but the live one, at launch.
+
+    Sessions are per-run scratch that nothing reads back, and a session keeps a
+    full copy of every uploaded input -- a 21s clip is ~80 MB. Measured before
+    this existed: 492 MB across 90 directories in six days, 64% of it duplicates
+    of files the user already had, and nothing ever deleted any of it.
+
+    A file chosen by PATH (the recent list, or typing one) was never copied --
+    /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.
+    """
+    root = os.path.dirname(keep)
+    freed = 0
+    try:
+        names = os.listdir(root)
+    except OSError:
+        return 0
+    for n in names:
+        d = os.path.join(root, n)
+        if d == keep or not os.path.isdir(d):
+            continue
+        freed += _sweep_session(d)
+    return freed
+
+
+def _version() -> str:
+    """The shipped version, read from plugin.json rather than restated here.
+
+    A second place to write a version is a second place for it to go stale --
+    which is why check_package.py exists at all, after SKILL.md claimed the
+    wrong one for three releases. The page asks the server; the server reads the
+    manifest it was packaged with. Falls back to package.json, then to empty,
+    because a missing badge is a far better failure than a confidently wrong
+    one: a wrong version in a bug report costs more than no version.
+    """
+    here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    for rel in (os.path.join(".claude-plugin", "plugin.json"), "package.json"):
+        try:
+            with open(os.path.join(here, rel)) as f:
+                v = json.load(f).get("version")
+            if v:
+                return str(v)
+        except (OSError, ValueError, AttributeError):
+            continue
+    return ""
+
+
+def _build_label() -> str:
+    """Where this code came from: "" when installed, "dev <sha>[+]" from a tree.
+
+    The distinction the badge exists for. A session materialises its own private
+    copy of every installed plugin at start and keeps that snapshot for its whole
+    life, so the installed copy and the tree you are editing drift apart within
+    minutes -- and the symptom is a feature that is "not there", which reads
+    exactly like a bug in the feature. That has cost two debugging sessions.
+
+    `.git` is the discriminator because the packager excludes it: a tree has one,
+    an unpacked .plugin never does. The commit and the dirty marker are here
+    because on a day with four releases a bare "dev" is not enough to say WHICH
+    dev, and a sha without a `+` when the tree is dirty would be a confident lie
+    -- the failure mode this badge is supposed to prevent.
+    """
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    if not os.path.isdir(os.path.join(root, ".git")):
+        return ""                              # an unpacked .plugin: just the version
+    def git(*a):
+        return subprocess.run(("git", "-C", root) + a, capture_output=True,
+                              text=True, timeout=5)
+    try:
+        r = git("rev-parse", "--short", "HEAD")
+        sha = r.stdout.strip() if r.returncode == 0 else ""
+        d = git("status", "--porcelain")
+        dirty = "+" if (d.returncode == 0 and d.stdout.strip()) else ""
+    except (OSError, subprocess.SubprocessError):
+        return "dev"                           # a tree, and that is the part that matters
+    return f"dev {sha}{dirty}".strip() if sha else "dev"
+
+
+VERSION = None                                 # resolved once, in main()
+BUILD = ""                                     # ditto -- no per-request subprocess
+
+
+def _quad(raw):
+    """Four corners of two finite numbers, or a ValueError naming the problem.
+
+    The compositing routes used to hand whatever arrived straight to the engine,
+    so a malformed quad became a failure deep inside a worker thread -- or, on
+    the render path, a job that was accepted, started, and then died somewhere
+    the user could not see. The shape of the request is the route's business.
+    """
+    try:
+        pts = [[float(x), float(y)] for x, y in raw]
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"corners must be four [x, y] pairs ({e})") from e
+    if len(pts) != 4:
+        raise ValueError(f"corners must be four points, got {len(pts)}")
+    if not all(v == v and abs(v) != float("inf") for pt in pts for v in pt):
+        raise ValueError("corners contain a non-finite value")
+    return pts
+
+
+def _need_sources():
+    """Both sources chosen, or a clean 400 saying which one is missing.
+
+    Without this the compositing routes indexed straight into the session and
+    handed `None` to `os.path.expanduser`, which raises TypeError -- a type the
+    handler does not catch, so the worker thread died and the browser saw the
+    connection drop with no status and no message at all. A request that cannot
+    be served should be answered, not hung up on.
+    """
+    missing = [k for k in ("photo", "screenshot") if not SESSION.state.get(k)]
+    if missing:
+        raise ValueError("choose a " + " and a ".join(missing) + " first")
+
+
 def _safe_local_path(p: str) -> str:
     """Only serve files under the user's home (the UI is local, but still)."""
     p = os.path.realpath(os.path.expanduser(p))
@@ -183,6 +336,13 @@ def _is_video(path: str) -> bool:
     return str(path).lower().endswith(VIDEO_EXT)
 
 
+def _fit_frame() -> int:
+    try:
+        return int(SESSION.state.get("fit_frame") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
 def _read_source(path: str):
     """Read the screen source, which may be a still OR a video.
 
@@ -197,13 +357,27 @@ def _read_source(path: str):
         im, rp = _read_image(real)
         return im, rp, {"video": False}
     n, fps, vw, vh = W.probe_video(real)
-    frame = W.read_frame_at(real, 0)
+    # The frame the designer scrubbed to, NOT frame 0. Preview and Save read the
+    # source through here, so reading frame 0 unconditionally made the scrubber
+    # look decorative: it moved the thumbnail and the composite never changed
+    # (reported 9 Sep 2026). The fitted frame is session state for exactly this
+    # reason — more than one route needs it.
+    frame = W.read_frame_at(real, _fit_frame())
     # Report the encoder's absence HERE, when the clip is chosen, rather than
     # letting the render fail at the end of the job. Someone who installed
     # screengraft before video existed has a working venv with no ffmpeg in it,
     # and nothing else would tell them until they had done all the fitting.
+    # A poster for the chip. The chip used to be handed the .mov path directly,
+    # and an <img> cannot render a video, so the thumbnail was silently blank for
+    # every clip. It is always FRAME 0 and never follows the scrubber: at chip
+    # size one frame looks like any other, so redrawing it would be movement
+    # without information.
+    poster = os.path.join(SESSION.dir,
+                          "poster-" + os.path.splitext(os.path.basename(real))[0] + ".jpg")
+    if not os.path.exists(poster):
+        cv2.imwrite(poster, W.read_frame_at(real, 0), [cv2.IMWRITE_JPEG_QUALITY, 82])
     return frame, real, {"video": True, "frames": n, "fps": fps, "size": [vw, vh],
-                         "ffmpeg": _have_ffmpeg()}
+                         "ffmpeg": _have_ffmpeg(), "poster": poster}
 
 
 # Render progress, read by /api/render_status. A ten-second clip is a few
@@ -216,7 +390,20 @@ RENDER_LOCK = threading.Lock()
 
 
 def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame,
-                   blend="replace", reflection=None):
+                   blend="replace", reflection=None, result=None):
+    """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
+    rather than written by the route, because a sidecar written before the
+    encode asserts `saved` for a file that may never exist -- and the sidecar is
+    the first thing the bug template asks for, so a misleading one sends the
+    next investigation the wrong way.
+
+    Publication order matters: the sidecar and the session output are written
+    BEFORE the state flips to "done". The page polls for "done" and may ask to
+    send the file to Claude the moment it sees it, so the artefacts have to be
+    in place first or that request races the worker.
+    """
     def progress(done, total):
         with RENDER_LOCK:
             RENDER["done"], RENDER["total"] = done, total
@@ -227,6 +414,13 @@ def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, prese
                                blend=blend,
                                reflection=(W.DEFAULT_REFLECTION if reflection is None
                                            else reflection))
+        if result is not None:
+            _write_json_atomic(SESSION.result_path, {**result, "saved": time.time()})
+        # The still path has always done this (see /api/save); the render path
+        # never did, so /api/import -- which reads SESSION.state["output"] --
+        # either found nothing or, worse, silently handed over the PREVIOUS
+        # still image after a successful render.
+        SESSION.update(output=dest)
         with RENDER_LOCK:
             RENDER.update(state="done", output=dest, info=info,
                           done=info["frames"], total=info["frames"], message=None)
@@ -311,7 +505,8 @@ class Handler(BaseHTTPRequestHandler):
                 return self._file(UI_HTML, "text/html; charset=utf-8")
             if u.path == "/api/state":
                 return self._json({**SESSION.state, "session": SESSION.dir, "out_dir": OUT_DIR,
-                                   "home": HOME, "presets": PRESETS})
+                                   "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]))
                 for it in items:
@@ -350,6 +545,14 @@ class Handler(BaseHTTPRequestHandler):
             return self._json({"error": "no such route"}, 404)
         except (PermissionError, FileNotFoundError, KeyError, ValueError) as e:
             return self._json({"error": str(e)}, 400)
+        except Exception as e:                 # noqa: BLE001 - the last resort
+            # A type nobody enumerated must still produce a RESPONSE. Without
+            # this the handler thread dies and the browser sees the connection
+            # drop with no status and no message -- indistinguishable from the
+            # server being gone, and impossible to report usefully. Twice in one
+            # afternoon a bad input did exactly that: a None photo path reaching
+            # expanduser, and a truncated clip whose frame read came back empty.
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
 
     # ---- POST ----
     def do_POST(self):
@@ -364,6 +567,7 @@ class Handler(BaseHTTPRequestHandler):
                     f.write(self._body())
                 # A video is only ever a screen source; a photo must be a still.
                 if role == "screenshot":
+                    SESSION.update(fit_frame=0)
                     im, real, meta = _read_source(dest)
                 else:
                     im, real = _read_image(dest)
@@ -376,6 +580,7 @@ class Handler(BaseHTTPRequestHandler):
             if u.path == "/api/use":
                 role = b["role"]
                 if role == "screenshot":
+                    SESSION.update(fit_frame=0)
                     im, real, meta = _read_source(b["path"])
                 else:
                     im, real = _read_image(b["path"])
@@ -417,16 +622,36 @@ class Handler(BaseHTTPRequestHandler):
                 return self._json({"path": real, "size": [im.shape[1], im.shape[0]]})
 
             if u.path == "/api/detect":
+                if not SESSION.state.get("photo"):
+                    raise ValueError("choose a photo first")
                 photo, _ = _read_image(SESSION.state["photo"])
                 gray = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
+                # An optional seed point, in PHOTO pixels. The detectors already
+                # find the screen on these photographs -- 23 of 93 candidates
+                # contained the click on the iPad that used to abstain -- they
+                # just cannot tell which region is a screen. That is the one
+                # question a person answers instantly, so the click filters the
+                # candidate list and the existing score ranks what is left.
+                click = b.get("click") if isinstance(b, dict) else None
+                if click is not None:
+                    try:
+                        click = (float(click[0]), float(click[1]))
+                    except (TypeError, ValueError, IndexError) as e:
+                        raise ValueError(f"click must be [x, y] in photo pixels ({e})") from e
+                    h, w = photo.shape[:2]
+                    if not (0 <= click[0] < w and 0 <= click[1] < h):
+                        raise ValueError("the click is outside the photograph")
                 # `color` gives detect() the saturation detector — devices are
                 # neutral, furniture is not, and grayscale throws that away.
-                res = D.detect(gray, None, color=photo)
+                res = D.detect(gray, None, color=photo, click=click)
                 if res is None:
-                    return self._json({"found": False,
-                                       "message": "Neither detector could find a screen here "
-                                                  "(nothing separable by tone, no screen-shaped "
-                                                  "boundary). Place the four corners by hand."})
+                    return self._json({"found": False, "clicked": click is not None,
+                                       "message": ("Nothing screen-shaped was found around that "
+                                                   "point — try clicking nearer the middle of the "
+                                                   "screen." if click is not None else
+                                                   "Neither detector could find a screen here "
+                                                   "(nothing separable by tone, no screen-shaped "
+                                                   "boundary). Place the four corners by hand.")})
                 # An abstention is a miss, and must reach the page as one. On
                 # 7 Sep 2026 a quad on a table was shown as a checkable guess
                 # with two corners off the canvas, which cannot be dragged back
@@ -456,15 +681,17 @@ class Handler(BaseHTTPRequestHandler):
                 spath = _safe_local_path(SESSION.state["screenshot"])
                 if not _is_video(spath):
                     return self._json({"error": "the screen source is not a video"}, 400)
+                # Records which frame the fit is judged on. Nothing is written:
+                # the page re-renders the COMPOSITE from it, and the chip stays
+                # on frame 0 deliberately, so a per-step PNG would be disk churn
+                # nobody looks at.
                 idx = int(b.get("index") or 0)
-                frame = W.read_frame_at(spath, idx)
-                dest = os.path.join(SESSION.dir, f"frame-{idx:06d}.png")
-                cv2.imwrite(dest, frame, [cv2.IMWRITE_PNG_COMPRESSION, 1])
-                return self._json({"path": dest, "index": idx,
-                                   "size": [frame.shape[1], frame.shape[0]]})
+                SESSION.update(fit_frame=idx)
+                return self._json({"index": idx})
 
             if u.path == "/api/render":
                 # Video: same fit, same geometry, N frames instead of one.
+                _need_sources()
                 photo, ppath = _read_image(SESSION.state["photo"])
                 spath = _safe_local_path(SESSION.state["screenshot"])
                 if not _is_video(spath):
@@ -472,14 +699,15 @@ class Handler(BaseHTTPRequestHandler):
                 if not _have_ffmpeg():
                     return self._json({"error": "ffmpeg is not installed",
                                        "needs_ffmpeg": True}, 400)
+                # Cheap early out. The flag that actually reserves the render
+                # is set further down, once nothing is left that can throw.
                 with RENDER_LOCK:
                     if RENDER["state"] == "running":
                         return self._json({"error": "a render is already running"}, 409)
-                    RENDER.update(state="running", done=0, total=0,
-                                  output=None, message=None)
-                corners = b["corners"]
+                corners = _quad(b["corners"])
                 frac = float(b.get("radius_frac") or 0.0)
-                fit_frame = int(b.get("fit_frame") or 0)
+                fit_frame = int(b.get("fit_frame") if b.get("fit_frame") is not None
+                                else _fit_frame())
                 first = W.read_frame_at(spath, fit_frame)
                 radius_px = frac * first.shape[1]
                 gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
@@ -504,19 +732,38 @@ 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,
-                                       blend, reflection)).start()
+                          "blend": blend, "reflection": reflection}
+                # `state="running"` means "a thread is running", so it is set
+                # here -- after every line that can raise, immediately before the
+                # thread exists. It used to be set at the top of this route, so a
+                # KeyError on corners, a bad radius, an unreadable frame or an
+                # unwritable out_dir left the flag stuck ON with no worker to
+                # clear it, and every later render answered 409 for the rest of
+                # the session. The only recovery was restarting the server, and
+                # nothing said so.
+                with RENDER_LOCK:
+                    if RENDER["state"] == "running":
+                        return self._json({"error": "a render is already running"}, 409)
+                    RENDER.update(state="running", done=0, total=0,
+                                  output=None, message=None)
+                try:
+                    threading.Thread(target=_render_worker, daemon=True,
+                                     args=(photo, spath, corners, dest, radius_px,
+                                           gr, grain, preset, fit_frame,
+                                           blend, reflection, result)).start()
+                except BaseException:
+                    # If the thread cannot even be created, the flag must not
+                    # outlive the request.
+                    with RENDER_LOCK:
+                        RENDER.update(state="error", message="could not start the render")
+                    raise
                 return self._json({"started": True, "output": dest, "preset": preset})
 
             if u.path in ("/api/preview", "/api/save"):
+                _need_sources()
                 photo, ppath = _read_image(SESSION.state["photo"])
                 shot, spath, _meta = _read_source(SESSION.state["screenshot"])
-                corners = b["corners"]
+                corners = _quad(b["corners"])
                 frac = float(b.get("radius_frac") or 0.0)
                 radius_px = frac * shot.shape[1]
                 # M2 realism pass. Off is a real option, not a fallback: a flat
@@ -572,6 +819,14 @@ class Handler(BaseHTTPRequestHandler):
             return self._json({"error": str(e)}, 409)
         except (PermissionError, FileNotFoundError, KeyError, ValueError) as e:
             return self._json({"error": str(e)}, 400)
+        except Exception as e:                 # noqa: BLE001 - the last resort
+            # A type nobody enumerated must still produce a RESPONSE. Without
+            # this the handler thread dies and the browser sees the connection
+            # drop with no status and no message -- indistinguishable from the
+            # server being gone, and impossible to report usefully. Twice in one
+            # afternoon a bad input did exactly that: a None photo path reaching
+            # expanduser, and a truncated clip whose frame read came back empty.
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
 
 
 def free_port():
@@ -639,7 +894,7 @@ def _publish_current(payload):
 
 
 def main():
-    global SESSION, OUT_DIR
+    global SESSION, OUT_DIR, VERSION, BUILD
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--port", type=int, default=0, help="0 = pick a free port")
     ap.add_argument("--no-open", action="store_true", help="Don't open the browser")
@@ -657,6 +912,8 @@ def main():
     if args.daemon:
         _daemonise(args.log)
 
+    VERSION = _version()
+    BUILD = _build_label()
     if args.out_dir:
         OUT_DIR = os.path.abspath(os.path.expanduser(args.out_dir))
     sdir = args.session or os.path.join(HOME, ".screengraft", "sessions", time.strftime("%Y%m%d-%H%M%S"))
@@ -664,10 +921,17 @@ def main():
     port = args.port or free_port()
     url = f"http://127.0.0.1:{port}/"
     srv = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    freed = _prune_sessions(sdir)
+    # The live session's own copies go when this process does. Registered before
+    # serve_forever, and the SIGTERM handler exits via sys.exit so atexit runs --
+    # scripts/stop.sh sends SIGTERM for exactly this reason. A kill -9 cannot be
+    # caught, which is what the launch-time sweep above is for.
+    atexit.register(lambda: _sweep_session(sdir))
     _publish_current({"session": sdir, "url": url, "pid": os.getpid(),
                       "out_dir": OUT_DIR, "started": time.time()})
     print(json.dumps({"url": url, "session": sdir, "job": SESSION.job_path,
-                      "result": SESSION.result_path, "out_dir": OUT_DIR}), flush=True)
+                      "result": SESSION.result_path, "out_dir": OUT_DIR,
+                      "reclaimed_mb": round(freed / 1e6, 1)}), flush=True)
     if not args.no_open:
         opener = "open" if sys.platform == "darwin" else "xdg-open"
         threading.Timer(0.3, lambda: subprocess.Popen([opener, url])).start()

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.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.
+**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.
 
 The geometry is exact (`warp.py`); the detection is advisory (`detect.py`) and the human corrects it.
 

package/ui/index.html

@@ -221,6 +221,12 @@
      buttons beside them. Only the corner radii and the shared middle border
      are special. */
   .stepper{display:inline-flex;align-items:center}
+  /* A segmented control has to show which segment is on. `.sel` was only ever
+     styled for the thumbnail picker (.th.sel), so the web/ProRes pair rendered
+     with no selected state at all — reported 9 Sep 2026. Same step as the
+     device chips: selected sits on --raise-hi with the brighter border. */
+  .stepper button.sel{background:var(--raise-hi);border-color:var(--edge-hi);color:var(--ink)}
+  .stepper button.sel:hover{background:var(--raise-highest);border-color:var(--edge-hi)}
   .stepper button{border-radius:0}
   .stepper button:first-child{border-top-left-radius:var(--r-sm);border-bottom-left-radius:var(--r-sm)}
   .stepper button:last-child{border-top-right-radius:var(--r-sm);border-bottom-right-radius:var(--r-sm)}
@@ -322,7 +328,11 @@
   .scroller{overflow:auto;background:var(--well);display:grid;
             min-height:0;min-width:0;
             box-shadow:inset 0 1px 3px rgba(0,0,0,.5)}
-  canvas#c{display:block;touch-action:none;cursor:crosshair;margin:auto}
+  /* tabindex -1, not 0: the canvas is not a tab stop — it takes focus only when
+     you actually click it, which is what makes space mean PAN rather than
+     re-pressing whichever rail button you last used. No ring, because the
+     focus is a side effect of clicking, never of tabbing. */
+  canvas#c{display:block;touch-action:none;cursor:crosshair;margin:auto;outline:none}
 
   /* Corner-jump bar floating over the canvas (Figma 16:121). position:sticky
      inside the scroller would drift with pan; fixed-to-the-pane absolute
@@ -555,6 +565,34 @@
            pixel to the band's height: 16+28+8+130+16 = 198 exactly. */
         box-shadow:inset 0 1px 0 var(--line), inset 0 2px 0 rgba(255,255,255,.04)}
   .dock.hidden{display:none}
+  /* Version badge. Bottom-right, fixed, and deliberately the quietest thing on
+     screen: --faint is the captions token (measured 3.50:1, the 1.4.3 floor for
+     incidental text), 11px with the same tracking as every other label.
+     pointer-events:none so it can never eat a click meant for what is under it,
+     and it is under no circumstances the accent -- that means "the next action"
+     and this is not an action at all.
+     Sits in the dock's own 16px padding band rather than over the rectified
+     strip: the work surface keeps zero decoration, which is the one rule the
+     canvas has. */
+  .ver{position:fixed;right:var(--s3);bottom:2px;z-index:5;pointer-events:none;
+       font-size:11px;letter-spacing:.06em;color:var(--faint);
+       font-variant-numeric:tabular-nums}
+  /* A dev build steps up from --faint to --mute (5.86:1). Not the accent, which
+     means "the next action" -- this is a fact about what you are running, not
+     something to do. Brighter than the plain version because "you are not
+     testing what you think you are testing" is worth noticing. */
+  .ver.dev{color:var(--mute)}
+  /* Armed: the canvas is waiting for one click. The button holds the accent
+     because it IS the next action while armed, which is the accent's one job. */
+  /* Suggested (detection just failed) and armed (waiting for your click).
+     Deliberately NOT the accent: Save carries that, and the visual language
+     allows exactly one accent-filled control on screen — measured and violated
+     by a first version of this, which put a second one here while Save was
+     already live. Emphasis without colour is what the raise ladder is for, and
+     it is the same treatment a selected chip gets. */
+  #pointat.suggest{background:var(--raise-hi);border-color:var(--edge-hi);color:var(--ink)}
+  #pointat.armed{background:var(--raise-highest);border-color:var(--edge-hi);color:var(--ink)}
+  .scroller.pointing canvas#c{cursor:crosshair}
   /* Figma 8:29 is a 28px header holding 24px buttons — the header does not
      shrink to hug them. */
   .striphead{display:flex;align-items:center;gap:8px;font-size:12px;min-height:28px}
@@ -713,6 +751,7 @@
             <span class="lbl">Fit</span>
             <span class="stepper"><button id="czOut">&minus;</button><button id="czIn">+</button></span>
             <span id="czSt" class="zoomval"></span>
+            <button class="info" type="button" aria-label="About canvas navigation"><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">Hold ⌘ and scroll to zoom to the pointer — the pixel under the cursor stays under the cursor, which is how you keep a corner in view while you magnify it. Hold space and drag to pan. Scrolling on its own pans too; the Result pane follows either way.</span></button>
           </div>
           <div class="ph-left-2">
             <button id="czFit">Fit</button>
@@ -722,7 +761,7 @@
         <span class="status" id="detSt"></span>
       </div>
       <div class="scroller" id="scroller">
-        <canvas id="c"></canvas>
+        <canvas id="c" tabindex="-1"></canvas>
       </div>
       <!-- Corner jump. It is a SIBLING of the scroller, not a child: anything
            positioned inside a scroll container scrolls with the content, so
@@ -734,6 +773,7 @@
         <span class="cvbar-actions">
           <span class="stepper"><button class="sm" data-jump="0">TL</button><button class="sm" data-jump="1">TR</button><button class="sm" data-jump="2">BR</button><button class="sm" data-jump="3">BL</button></span>
           <button class="sm" id="redetect">Re-detect</button>
+          <button class="sm" id="pointat" title="Click once inside the screen and the detector will use that point. The detectors usually do find the screen — they just cannot tell which region IS one, and that is the part you can answer instantly.">Point at screen</button>
           <button class="sm" id="resetquad" title="Put the four edges back to a rectangle in the middle of the photo. Use this if a corner has ended up off the picture where you cannot grab it.">Reset</button>
         </span>
       </div>
@@ -758,8 +798,8 @@
           <input type="range" id="vframe" min="0" max="0" value="0" step="1"
                  aria-label="Which frame of the clip to match the edges on">
           <span class="sm" id="vframeLbl" style="color:var(--mute);min-width:9ch">0</span>
-          <span class="stepper" role="group" aria-label="Output format">
-            <button class="sm sel" data-preset="web" title="H.264 at CRF 16 — near-visually-lossless, plays anywhere.">Web</button><button class="sm" data-preset="prores" title="ProRes 422 HQ — bigger file, no chroma subsampling. For a case study or further editing.">ProRes</button>
+          <span class="stepper" role="radiogroup" aria-label="Output format">
+            <button class="sm sel" data-preset="web" role="radio" aria-checked="true" title="H.264 at CRF 16 — near-visually-lossless, plays anywhere.">Web</button><button class="sm" data-preset="prores" role="radio" aria-checked="false" title="ProRes 422 HQ — bigger file, no chroma subsampling. For a case study or further editing.">ProRes</button>
           </span>
         </span>
       </div>
@@ -790,7 +830,7 @@
         <div class="sect-top">
           <div class="sect-left">
             <h4>Realism</h4>
-            <button class="info" type="button" aria-label="About realism"><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">Matches the screen's white balance and grain to the light around it, so it stops reading as pasted. Off keeps the screenshot's colour exactly — right when the UI's own colour is what you're reviewing.</span></button>
+            <button class="info" type="button" aria-label="About realism"><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">Matches the screen's white balance and grain to the light around it, so it stops reading as pasted. Off keeps the screenshot's colour exactly — right when the UI's own colour is what you're reviewing. Grain is judged here at the preview's scale: the save carries about twice as much, which is what you get if you view the file at 100%.</span></button>
           </div>
           <button class="switch" id="gradeBtn" role="switch" aria-checked="true" aria-label="Realism">
             <span class="sw-track"><span class="sw-handle"></span><span class="sw-grip"></span></span>
@@ -833,7 +873,12 @@
       </div>
       <div class="sect" id="secKeys" data-on="1">
         <div class="sect-top"><div class="sect-left"><h4>Keys</h4></div></div>
+        <!-- Two lines, split by what they act on: the QUAD you are fitting, and
+             the VIEW you are fitting it in. Grouping them by that rather than
+             by modifier is what makes the list scannable while you are mid-fit
+             and looking for one of them. -->
         <p class="hint"><kbd>&larr;&uarr;&rarr;&darr;</kbd> nudge 1px · <kbd>&#8679;</kbd>+arrow 10px · <kbd>Tab</kbd> next edge</p>
+        <p class="hint"><kbd>&#8984;</kbd>+scroll zoom to pointer · <kbd>Space</kbd>+drag pan · scroll pans</p>
       </div>
     </aside>
   </div>
@@ -850,6 +895,8 @@
   </footer>
 </div>
 
+<div class="ver" id="ver"></div>
+
 <div class="floatloupe" id="floatLoupe">
   <canvas id="stripF" width="680" height="208"></canvas>
   <div class="cap" id="stripFCap"></div>
@@ -1147,12 +1194,14 @@ function setChosen(role, path, size, el, meta){
   const n = role==='photo'?1:2;
   document.querySelectorAll('#recent'+n+' .th').forEach(x=>x.classList.remove('sel'));
   if (el) el.classList.add('sel');
-  $('#pv'+n).innerHTML = `<img src="${fileURL(path)}" alt="">`;
+  // A video cannot be shown by <img>, so a clip gets its poster frame instead.
+  const thumb = (meta && meta.poster) ? meta.poster : path;
+  $('#pv'+n).innerHTML = `<img src="${fileURL(thumb)}" alt="">`;
   const chip = $('#chip'+n);
   chip.classList.remove('is-empty');
   chip.querySelector('.nm').textContent = `${path.split('/').pop()} · ${size[0]}×${size[1]}`
     + (meta && meta.video ? ` · ${meta.frames} frames @ ${Math.round(meta.fps)}fps` : '');
-  $('#sw'+n).style.background = `center/cover no-repeat url("${fileURL(path)}")`;
+  $('#sw'+n).style.background = `center/cover no-repeat url("${fileURL(thumb)}")`;
   if (role==='photo'){ st.photo = path; st.corners = null; }
   else { st.shot = path; st.video = meta && meta.video ? meta : null; syncVideoUI(); }
   closePop();
@@ -1356,6 +1405,163 @@ $('#czFit').onclick = () => { computeFit(); setCanvasZoom(fitScale); };
 $('#cz100').onclick = () => setCanvasZoom(1);
 $('#czIn').onclick  = () => setCanvasZoom(scale*1.5);
 $('#czOut').onclick = () => setCanvasZoom(scale/1.5);
+/* ===== canvas navigation: zoom to the pointer, space-drag to pan ==========
+   The conventions every graphics tool already uses, so not having them means
+   the muscle memory misfires against a canvas that otherwise behaves like one.
+
+   Panning IS scrolling here — the canvas is sized in real pixels inside
+   #scroller — which is why the Result pane keeps up for free: it already
+   mirrors this element's scroll. */
+
+/* Zoom about a screen point rather than the canvas centre.
+
+   Measured rather than computed: after the resize, ask the DOM where the
+   pinned image point actually landed and scroll by the difference. The canvas
+   is `margin:auto` in a grid, so while it is smaller than the pane it sits
+   centred with a margin that changes as it grows — arithmetic that predicts
+   the scroll offset has to model that margin, and measuring does not. When the
+   whole image fits there is nothing to scroll and the pin cannot hold, which
+   is correct: nothing is moving off screen. */
+function zoomAt(z, clientX, clientY){
+  if (!img.naturalWidth) return;
+  const before = pos({clientX, clientY});
+  setCanvasZoom(z);
+  const sc = $('#scroller'), r = cv.getBoundingClientRect();
+  sc.scrollLeft += r.left + before[0] * scale * (r.width / cv.width) - clientX;
+  sc.scrollTop  += r.top  + before[1] * scale * (r.height / cv.height) - clientY;
+}
+
+/* A trackpad pinch arrives as a wheel event with ctrlKey synthesised true, and
+   a real cmd+scroll arrives with metaKey — both mean "zoom", so both are taken.
+   The listener MUST be {passive:false} or preventDefault is ignored and the
+   browser zooms the whole page instead of the picture. deltaMode is normalised
+   because a wheel mouse reports lines (1) or pages (2), not pixels. */
+$('#scroller').addEventListener('wheel', e => {
+  if (!(e.metaKey || e.ctrlKey)) return;          // plain scroll still pans
+  e.preventDefault();
+  const dy = e.deltaY * (e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? 400 : 1);
+  zoomAt(scale * Math.exp(-dy * 0.0025), e.clientX, e.clientY);
+}, {passive: false});
+
+/* Space-drag. Space is ALSO how a keyboard user activates the focused button
+   or switch, so it is only a pan modifier when focus is not on a control —
+   otherwise adding this gesture would quietly break every rail control for
+   anyone not using a mouse. */
+let spaceHeld = false, panning = null;
+const onAControl = () => {
+  const a = document.activeElement;
+  return !!a && a !== document.body && a !== cv &&
+         a.matches('input, textarea, select, button, [role="switch"], [contenteditable]');
+};
+function setPanCursor(){
+  cv.style.cursor = panning ? 'grabbing' : (spaceHeld ? 'grab' : '');
+}
+addEventListener('keydown', e => {
+  if (e.code !== 'Space' || e.repeat || spaceHeld || onAControl()) return;
+  e.preventDefault();                              // or the page scrolls
+  spaceHeld = true; setPanCursor();
+});
+addEventListener('keyup', e => {
+  if (e.code !== 'Space') return;
+  spaceHeld = false; endPan();
+});
+// Held space survives a cmd-tab away and would come back stuck on.
+addEventListener('blur', () => { spaceHeld = false; endPan(); });
+
+function endPan(){
+  if (panning && cv.hasPointerCapture && panning.id != null){
+    try { $('#scroller').releasePointerCapture(panning.id); } catch (err) {}
+  }
+  panning = null; setPanCursor();
+}
+
+/* Capture phase on the SCROLLER, which is an ancestor of the canvas: it runs
+   before the canvas's own handlers, so stopPropagation keeps a pan from ever
+   reaching hitTest and grabbing a corner. Registering capture on the canvas
+   itself would race its onpointerdown property handler instead. */
+const sc0 = $('#scroller');
+/* Touching the canvas moves focus to it. Space is both "pan" and "activate the
+   focused control", and after clicking any rail button focus STAYS on that
+   button — so without this, holding space over the picture re-presses Fit or
+   toggles Realism instead of panning. Focus follows the thing you last used,
+   which is also what a keyboard user expects: they never clicked the canvas, so
+   space keeps activating their focused control. */
+sc0.addEventListener('pointerdown', () => {
+  if (document.activeElement && document.activeElement !== cv) cv.focus({preventScroll: true});
+}, true);
+sc0.addEventListener('pointerdown', e => {
+  if (!spaceHeld || e.button !== 0) return;
+  e.preventDefault(); e.stopPropagation();
+  panning = {id: e.pointerId, x: e.clientX, y: e.clientY,
+             sl: sc0.scrollLeft, st: sc0.scrollTop};
+  try { sc0.setPointerCapture(e.pointerId); } catch (err) {}
+  setPanCursor();
+}, true);
+sc0.addEventListener('pointermove', e => {
+  if (!panning) { if (spaceHeld) e.stopPropagation(); return; }
+  e.preventDefault(); e.stopPropagation();
+  sc0.scrollLeft = panning.sl - (e.clientX - panning.x);
+  sc0.scrollTop  = panning.st - (e.clientY - panning.y);
+}, true);
+const stopPan = e => { if (!panning) return; e.stopPropagation(); endPan(); };
+sc0.addEventListener('pointerup', stopPan, true);
+sc0.addEventListener('pointercancel', stopPan, true);
+
+/* ===== point at the screen =====================================================
+   The detectors nearly always FIND the screen; what they cannot do is tell
+   which of the regions they found is one. Measured on the two photographs that
+   defeated every detector: the correct quad was already among the candidates
+   both times. So this sends a single point and the server filters the candidate
+   list by it — no new segmentation, and every existing guard (validation,
+   corner refinement, the radius measurement) still applies to whatever wins. */
+let pointing = false;
+function setPointing(on){
+  pointing = on;
+  if (on) suggestPointing(false);      // taken up; stop nagging
+  $('#pointat').classList.toggle('armed', on);
+  $('#scroller').classList.toggle('pointing', on);
+  $('#pointat').textContent = on ? 'Click the screen…' : 'Point at screen';
+  if (on){
+    const s = $('#detSt'); s.className = 'status'; s.textContent = 'Click once inside the screen';
+  }
+}
+function suggestPointing(on){ $('#pointat').classList.toggle('suggest', !!on); }
+$('#pointat').onclick = () => setPointing(!pointing);
+// Capture phase on the scroller, exactly as the space-pan is, and for the same
+// reason: this must never reach hitTest and start dragging a corner.
+$('#scroller').addEventListener('pointerdown', e => {
+  if (!pointing || e.button !== 0 || spaceHeld) return;
+  e.preventDefault(); e.stopPropagation();
+  const p = pos(e);
+  setPointing(false);
+  pointAt(p[0], p[1]);
+}, true);
+async function pointAt(x, y){
+  const s = $('#detSt'); s.className = 'status busy'; s.textContent = 'Reading that point…';
+  try {
+    const r = await api('/api/detect', {click: [x, y]});
+    if (r.found){
+      st.corners = r.corners; st.measured = r.corner_radius;
+      s.className = 'status ok';
+      s.textContent = `Screen found from your click (${r.method})`;
+      if (!st.type) setType(r.type_guess || 'phone');
+      if (r.corner_radius && r.corner_radius.confident) setFrac(r.corner_radius.frac_of_width, 'measured from the photo');
+      else { applyPreset(); $('#radSt').textContent = 'Radius not measurable here — using the device preset.'; }
+      markStale();
+    } else {
+      s.className = 'status warn';
+      s.textContent = 'Nothing screen-shaped at that point — try again or place the edges by hand';
+      s.title = r.message || '';
+    }
+  } catch (err) {
+    s.className = 'status warn'; s.textContent = 'Could not read that point: ' + err.message;
+  }
+  pick = {kind:'edge', i:0};
+  draw(); drawStrip(); autoPreview();
+}
+// Escape disarms, like every other transient mode on this page.
+addEventListener('keydown', e => { if (e.key === 'Escape' && pointing) setPointing(false); });
+
 document.querySelectorAll('[data-jump]').forEach(b => {
   b.onclick = () => { if (!st.corners) return; const i=+b.dataset.jump;
     pick = {kind:'corner', i}; setCanvasZoom(Math.max(1, scale), st.corners[i]); drawStrip(); };
@@ -1376,8 +1582,13 @@ async function detect(){
   } else {
     st.corners = defaultQuad();
     s.className='status warn';
-    s.textContent = r.abstained ? 'Detector abstained — place the edges by hand'
-                                : 'No screen found — place the edges by hand';
+    // Naming the control is the whole fix. The page knows the detector just
+    // failed, which is exactly the moment "Point at screen" is worth doing —
+    // and the old wording sent people to the slowest remaining option without
+    // mentioning the fast one. Reported 10 Sep: "I haven't noticed new button".
+    s.textContent = r.abstained ? 'Detector abstained — try Point at screen, or place the edges by hand'
+                                : 'No screen found — try Point at screen, or place the edges by hand';
+    suggestPointing(true);
     // The full reason is long and belongs on hover, not in a 40-character chip.
     s.title = r.message || '';
     if (!st.type) setType('phone'); applyPreset();
@@ -1519,6 +1730,8 @@ function moveEdge(C, i, mode, delta){
 
 cv.onpointerdown = e => {
   const p = pos(e), h = hitTest(p);
+  // You have started placing edges by hand, so stop advertising the shortcut.
+  if (h) suggestPointing(false);
   if (!h){ pick = null; draw(); drawStrip(); return; }
   drag = {...h, grab: p, start: st.corners.map(c => c.slice())};
   pick = {kind:h.kind, i:h.i};
@@ -1790,6 +2003,21 @@ function syncSlider(){ const r=$('#radius'); r.style.setProperty('--p', (r.value
 
 /* ===== preview / compare / save ===== */
 let outNat = 0, autoTimer = null;
+/* What the primary action is CALLED, derived from the source rather than
+   patched. Six places used to set this label and they did not agree: one
+   computed it from st.video, one upgraded 'Save' to 'Render' with no inverse,
+   and the save handler reset it to 'Save' unconditionally -- so a video source
+   could leave the button reading either word regardless of what clicking it
+   would do. On a tool whose whole pitch is that the output is exact, a label
+   that disagrees with its action is not a small thing. */
+function saveLabel(){ return st.video ? 'Render' : 'Save'; }
+/* The labels that mean "there is something to do". markStale's 'Preview first'
+   and the in-flight 'Saving…' / progress text must survive a source change, so
+   relabelling only touches a button that is currently offering the action. */
+function relabelSave(){
+  const b = $('#save');
+  if (b.textContent === 'Save' || b.textContent === 'Render') b.textContent = saveLabel();
+}
 function markStale(){
   const b = $('#save'); b.disabled = true; b.textContent = 'Preview first';
   // Exactly one lit action at a time — the Figma Button component says the
@@ -1826,7 +2054,7 @@ async function renderPreview(){
     im.onload = () => { outNat = im.naturalWidth; im.hidden = false; $('#outEmpty').style.display='none'; syncOut(); };
     im.src = `${fileURL(r.path)}&t=${Date.now()}`;
     s.textContent = `radius ${r.radius_px}px on the screenshot`;
-    const b = $('#save'); b.disabled = false; b.textContent = st.video ? 'Render' : 'Save';
+    const b = $('#save'); b.disabled = false; b.textContent = saveLabel();
     b.classList.add('primary');            // Save is now the next action
     if (!previewHinted){ previewHinted = true;
       toast('info', 'Check the corners in Result, then <b>Save</b> — Save renders at full resolution.');
@@ -1846,7 +2074,11 @@ let preset = 'web';
 document.querySelectorAll('[data-preset]').forEach(btn => {
   btn.onclick = () => {
     preset = btn.dataset.preset;
-    document.querySelectorAll('[data-preset]').forEach(o => o.classList.toggle('sel', o === btn));
+    document.querySelectorAll('[data-preset]').forEach(o => {
+      const on = o === btn;
+      o.classList.toggle('sel', on);
+      o.setAttribute('aria-checked', on ? 'true' : 'false');
+    });
   };
 });
 
@@ -1871,18 +2103,21 @@ function syncVideoUI(){
     sl.max = Math.max(0, (v.frames || 1) - 1);
     sl.value = 0;
     $('#vframeLbl').textContent = `0 / ${Math.max(0,(v.frames||1)-1)}`;
-    if (b.textContent === 'Save') b.textContent = 'Render';
   }
+  // Outside the `if (v)`: switching a video source back to a still has to put
+  // the label back, and the one-way version above is why it did not.
+  relabelSave();
 }
 $('#vframe').oninput = () => { $('#vframeLbl').textContent = `${$('#vframe').value} / ${$('#vframe').max}`; };
 $('#vframe').onchange = async () => {
   // Swapping the poster frame re-runs preview through the same path a still
   // uses, so what you match the edges against is the frame you chose.
   try{
-    const r = await api('/api/frame', {index: +$('#vframe').value});
-    $('#pv2').innerHTML = `<img src="${fileURL(r.path)}" alt="">`;
-    $('#sw2').style.background = `center/cover no-repeat url("${fileURL(r.path)}")`;
-    autoPreview();
+    await api('/api/frame', {index: +$('#vframe').value});
+    // Only the composite changes. The chip keeps frame 0 on purpose — at that
+    // size one frame looks like any other, so updating it would be movement
+    // without meaning.
+    if (st.corners) renderPreview();
   }catch(e){ toast('err', 'Could not read that frame: ' + e.message); }
 };
 
@@ -1893,7 +2128,7 @@ async function renderVideo(){
   try{
     await api('/api/render', {corners: st.corners, radius_frac: radiusValue(), device: st.type,
                               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; }
+  }catch(e){ toast('err','Could not start the render: '+e.message); b.disabled=false; b.textContent = saveLabel(); 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.
   const tick = setInterval(async () => {
@@ -1906,13 +2141,13 @@ async function renderVideo(){
       if (d.total) $('#vframeLbl').textContent = `${d.done} / ${d.total} frames`;
     } else if (d.state === 'done'){
       clearInterval(tick);
-      b.textContent = 'Render'; b.disabled = false; b.classList.remove('primary');
+      b.textContent = saveLabel(); b.disabled = false; b.classList.remove('primary');
       $('#vframeLbl').textContent = `${$('#vframe').value} / ${$('#vframe').max}`;
       toast('ok', `Rendered <code>${(d.output||'').split('/').pop()}</code> · ${d.done} frames to <code>${prettyDir(st.outDir||'')}</code>`);
       const imp = $('#imp'); imp.disabled = false; imp.textContent = 'Send to Claude'; imp.classList.add('primary');
     } else if (d.state === 'error'){
       clearInterval(tick);
-      b.textContent = 'Render'; b.disabled = false;
+      b.textContent = saveLabel(); b.disabled = false;
       $('#vframeLbl').textContent = `${$('#vframe').value} / ${$('#vframe').max}`;
       toast('err', 'Render failed: ' + (d.message || 'unknown'));
     }
@@ -1924,7 +2159,7 @@ $('#save').onclick = async () => {
   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(), reflection: emisValue()});
-    b.textContent = 'Save';
+    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
     // they aren't there is how you lose a file.
@@ -1933,7 +2168,7 @@ $('#save').onclick = async () => {
     imp.disabled = false; imp.textContent = 'Send to Claude';
     // Hand the accent on: the file exists, so sending it is what is next.
     imp.classList.add('primary'); b.classList.remove('primary');
-  }catch(e){ toast('err', 'Could not save: ' + e.message); b.textContent='Save'; }
+  }catch(e){ toast('err', 'Could not save: ' + e.message); b.textContent = saveLabel(); }
   finally { b.disabled = false; }
 };
 
@@ -1972,6 +2207,18 @@ $('#imp').onclick = async () => {
   const s = await api('/api/state');
   st.presets = s.presets; $('#sess').textContent = s.session.split('/').pop();
   st.outDir = s.out_dir; st.home = s.home;
+  // Empty stays empty: the server returns "" if it could not read the manifest,
+  // and no badge is better than a wrong one in a bug report.
+  // "v1.2.3" from an installed plugin; "v1.2.3 · dev a1b2c3d+" from a working
+  // tree. (Deliberately a made-up number: a test asserts the CURRENT version
+  // string appears nowhere in this file, and an example using the real one
+  // would trip it -- as it just did.) The suffix is the whole point: a session snapshots its installed copy
+  // at start and keeps it for life, so "the feature is missing" is far more
+  // often the wrong build than a broken feature.
+  if (s.version){
+    $('#ver').textContent = 'v' + s.version + (s.build ? ' · ' + s.build : '');
+    $('#ver').classList.toggle('dev', !!s.build);
+  }
   // Say up front where Save will put things. With --out-dir this is usually the
   // project folder, and a designer should not have to press Save to find out.
   toast('info', `Fit the four edges, then Preview. Saves go to <code>${prettyDir(s.out_dir||'')}</code>.`,