screengraft 0.21.1 → 0.25.1

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.
 
@@ -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,

package/package.json

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

@@ -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))
@@ -237,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
@@ -248,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)
@@ -332,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:
@@ -371,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):
@@ -440,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
@@ -489,6 +691,7 @@ class Handler(BaseHTTPRequestHandler):
 
             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):
@@ -496,12 +699,12 @@ 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") if b.get("fit_frame") is not None
                                 else _fit_frame())
@@ -529,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
@@ -597,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():
@@ -664,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")
@@ -682,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"))
@@ -689,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.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);
@@ -328,7 +348,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
@@ -561,6 +585,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}
@@ -719,6 +771,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>
@@ -728,7 +781,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
@@ -740,6 +793,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>
@@ -796,7 +850,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>
@@ -839,7 +893,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>
@@ -856,6 +915,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>
@@ -1364,6 +1425,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(); };
@@ -1384,8 +1602,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();
@@ -1527,6 +1750,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};
@@ -1798,6 +2023,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
@@ -1834,7 +2074,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.');
@@ -1883,8 +2123,10 @@ 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 () => {
@@ -1906,7 +2148,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 () => {
@@ -1919,13 +2161,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'));
     }
@@ -1937,7 +2179,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.
@@ -1946,7 +2188,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; }
 };
 
@@ -1985,6 +2227,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>.`,