screengraft 0.47.0 → 0.49.0

package/README.md

@@ -232,6 +232,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: there are tests, they
 run in CI, and a change to the compositing engine needs a measurement, not an
 opinion.
 
+
+**Testing a change without reinstalling.** The desktop app snapshots an installed plugin per session and only refreshes it after *Check for updates*, so release → check → new session is a slow loop. Instead, run `scripts/dev-root.sh` once in your checkout: it writes `~/.screengraft/dev-root`, and from then on every session's `launch.sh` — including the installed copy's — runs the UI from your tree. The badge reads `dev <sha>+` while it does. `scripts/dev-root.sh off` restores the installed copy. Only `SKILL.md` and `mcp/server.py` changes still need a real update, because the app loads those itself.
+
 ## Licence
 
 MIT. The bundled Mona Sans subset is SIL OFL — see `ui/fonts/OFL.txt`.

package/package.json

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

package/scripts/dev-root.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env zsh
+# Point the installed plugin at a checkout, or stop doing so.
+#
+#   scripts/dev-root.sh            -> use THIS checkout (the one the script is in)
+#   scripts/dev-root.sh /some/tree -> use that one
+#   scripts/dev-root.sh off        -> back to the installed copy
+#   scripts/dev-root.sh status     -> say which
+#
+# Writes ~/.screengraft/dev-root, which launch.sh reads. See launch.sh for why.
+set -euo pipefail
+FILE="$HOME/.screengraft/dev-root"
+case "${1:-}" in
+  off)    rm -f "$FILE"; echo "dev root off — launch.sh uses the installed copy" ;;
+  status) if [ -s "$FILE" ]; then echo "dev root: $(head -n1 "$FILE")"; else echo "dev root off"; fi ;;
+  *)
+    TREE="${1:-$(cd "$(dirname "$0")/.." && pwd)}"
+    TREE="$(cd "$TREE" && pwd)"
+    [ -f "$TREE/scripts/ui.py" ] || { echo "error: $TREE has no scripts/ui.py" >&2; exit 2; }
+    mkdir -p "$(dirname "$FILE")"
+    printf '%s\n' "$TREE" > "$FILE"
+    echo "dev root: $TREE — every session's launch.sh now runs this tree; the badge will read 'dev <sha>'"
+    ;;
+esac

package/scripts/launch.sh

@@ -18,6 +18,26 @@
 # the same reason a Terminal window did, and there is no window to clean up.
 set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# Dev root: run the UI from a checkout instead of the installed copy.
+# `~/.screengraft/dev-root` holds one line, the path to a screengraft tree.
+# The desktop app snapshots every installed plugin per session and only
+# refreshes that snapshot after "Check for updates", so testing a change used
+# to mean release -> check -> new session. With the file in place any session,
+# including one already open, runs whatever is in the tree right now; the
+# badge reads "dev <sha>+" so it can never pass for a release. Opt-in by the
+# file's existence; a path that is not a tree is ignored with a warning, so
+# a stale file cannot silently break a launch. `scripts/dev-root.sh` writes it.
+DEV_ROOT_FILE="$HOME/.screengraft/dev-root"
+if [ -s "$DEV_ROOT_FILE" ]; then
+  DEV_ROOT="$(head -n1 "$DEV_ROOT_FILE")"
+  DEV_ROOT="${DEV_ROOT/#\~/$HOME}"
+  if [ -f "$DEV_ROOT/scripts/ui.py" ]; then
+    ROOT="$DEV_ROOT"
+    echo "dev root: running from $ROOT (remove $DEV_ROOT_FILE to use the installed copy)" >&2
+  else
+    echo "warning: $DEV_ROOT_FILE points at $DEV_ROOT, which has no scripts/ui.py — using the installed copy" >&2
+  fi
+fi
 PORT=0
 OUT_DIR=""
 

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.47):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
+**What ships (v0.49):** a local browser UI (`scripts/ui.py`) that walks the designer through the whole job — pick the photo and the screen source, which may be an image **or a video** (recent Desktop/Downloads images, drag-drop, browse, path, or a **Figma frame link**), auto-detect the screen as a starting position — and when detection cannot tell which region is a screen, **Point at screen**: one click inside it and the detector uses that point — or, if this photograph has been fitted before, **the fit it was saved with comes back** as the starting position instead of a detection, recognised by the photo's own pixels so a rename or a drag-drop still match — and every save also writes a **portable `.fit.json` beside the mockup** that can be dropped back onto the page later, which is how a fit survives a re-export, another machine, or someone else's hands — then **match the four edges** (drag an edge's middle to slide it, near an end to pivot; corners still draggable) with canvas navigation that follows the usual conventions — **hold ⌘ and scroll to zoom to the pointer, hold space and drag to pan** — and a rectified strip loupe. The fit and the composite sit **side by side and always have** — the result pane re-renders as you drag, which is how a corner gets judged, so it is the layout rather than a mode you can switch off. Then an on-by-default realism pass that colour-matches the source to the photo's light, **Save** (or **Render**, for a video) into the project folder (`--out-dir`), and a **Send to Claude** button that reaches you through the plugin's own MCP server. The UI is a hand port of the project's Figma design file — dark only.
 
 The geometry is exact (`warp.py`); the detection is advisory (`detect.py`) and the human corrects it. **When a detection is wrong and you want to know why**, ask for the candidate list: `POST /api/detect {"trace": true}` writes `<session>/candidates.json`, or run `python3 scripts/detect.py --photo P --out-corners /tmp/c.json --trace /tmp/t.json` (add `--click X,Y`). Every candidate quad is in there with its score and whether it was accepted, rejected, never reached, or filtered out by the click — which is what separates "the screen was never proposed" from "it was proposed and something else won".
 
@@ -54,6 +54,8 @@ scripts/launch.sh --out-dir "<the user's current project folder>/mockups"
 
 **Do not launch `ui.py` directly with `nohup ... &` from your own shell.** That was tried on 3 Sep 2026 and the server died silently between turns, twice, losing whatever the user had already entered — the shell session that launches it can be torn down out from under a merely-backgrounded child. `launch.sh` starts it with `--daemon`, which double-forks and calls `setsid`, putting the server in its own session with no controlling terminal; it survives the launching shell and opens no window. It self-checks (waits for startup output, then confirms the server responds) before returning.
 
+**If `launch.sh` prints `dev root: running from <path>`**, the UI is running from a source checkout, not from this installed copy — the developer has opted in with `~/.screengraft/dev-root` (see `scripts/dev-root.sh`). Say so in one line, and treat the badge's `dev <sha>+` as expected. Anything the user reports is then about that tree, not about the release.
+
 A Terminal.app window was the previous fix for the same problem. It worked but left a dead "[Process completed]" window behind after every session, and closing those from AppleScript proved unreliable — Terminal reports stale ttys for dead windows and leaves zero-tab husks that `close` reports success on. The daemon removes the window entirely, so there is nothing to clean up.
 
 It prints one JSON line — `url`, `session`, `job`, `result`, `out_dir` — and opens the browser tab itself. If it exits non-zero, read the error and the log path it names before telling the user anything is ready.
@@ -140,6 +142,7 @@ The server is a detached daemon with no window. **Stop it with `scripts/stop.sh`
 | `scripts/preflight.py` | Dependency report; `--install` builds the venv |
 | `scripts/launch.sh` | Starts `ui.py` as a detached daemon (no window) and verifies it's alive — use this, not `ui.py` directly |
 | `scripts/stop.sh` | Stops the UI with SIGTERM so the session pointer is cleared — use this instead of `pkill` |
+| `scripts/dev-root.sh` | Developer opt-in: point every session's `launch.sh` at a checkout (`on` by default, `off`, `status`). Testing a change then needs no release and no plugin update. |
 | `scripts/ui.py` | Local server + browser UI; calls the two below |
 | `scripts/detect.py` | Advisory screen-quad + corner-radius detection (no ML) |
 | `scripts/warp.py` | The engine: `compose()` and a CLI for scripted use |

package/ui/index.html

@@ -366,7 +366,16 @@
      until it is selected: no border, no shadow, no lift on press. */
   .seg button{height:22px;padding:0 11px;font-size:12px;border-radius:var(--r-sm);
               background:transparent;border:0;box-shadow:none;color:var(--mute);
-              font-weight:400}
+              font-weight:400;display:inline-flex;flex-direction:column;
+              align-items:center;justify-content:center}
+  /* Each segment is as wide as its label at the SELECTED weight, whichever
+     weight it is showing. Without this the control reflowed on every switch:
+     600 is wider than 400, so selecting "ProRes" grew that segment, and the
+     whole control — left edge included — moved (reported 12 Sep 2026).
+     A zero-height ghost of the label at 600 sits under the visible one and
+     sets the width; `data-label` carries the text. Not padding. */
+  .seg button::after{content:attr(data-label);font-weight:600;height:0;
+                     overflow:hidden;visibility:hidden;pointer-events:none}
   .seg button:hover{background:transparent;color:var(--ink)}
   .seg button:active{background:transparent;transform:none}
   /* The thumb. Its three surfaces are the Default button's own, which is the
@@ -406,8 +415,15 @@
   .chipwrap .inputchip:not(.is-empty){padding-right:30px}
   .chipclear{position:absolute;right:5px;top:50%;transform:translateY(-50%);
              width:22px;height:22px;padding:0;border-radius:999px;flex:none;
-             font-size:15px;line-height:1;color:var(--ink);
-             background:var(--raise-hi);border:1px solid var(--edge)}
+             display:inline-flex;align-items:center;justify-content:center;
+             color:var(--ink);background:var(--raise-hi);border:1px solid var(--edge)}
+  /* The cross is drawn, not typed. As the × character at 15px it sat
+     above centre in its disc -- a glyph carries its own ascent and side
+     bearings and no line-height setting centres it in a 22px circle ("X icon
+     is not fully centered", 12 Sep 2026). A 10px SVG in a flex
+     centre is centred by construction, and it is the same route the toast
+     glyphs took in v0.42.0. */
+  .chipclear svg{display:block;width:10px;height:10px}
   .chipclear:hover{background:var(--raise-highest);border-color:var(--edge-hi)}
   .chipclear:active{background:var(--raise-mid);transform:translateY(-50%)}
 
@@ -928,9 +944,9 @@
     <div class="tb-left">
       <span class="brand">Screengraft</span><span id="sess" hidden></span>
       <div class="tb-chips">
-        <span class="chipwrap"><button class="inputchip is-empty" id="chip1"><span class="sw" id="sw1"></span><span class="nm">Choose a photo…</span></button><button class="chipclear" id="clear1" data-role="photo" aria-label="Remove photo" title="Remove the photo and start over. A fit you saved for it comes back when you pick it again." hidden>&times;</button></span>
+        <span class="chipwrap"><button class="inputchip is-empty" id="chip1"><span class="sw" id="sw1"></span><span class="nm">Choose a photo…</span></button><button class="chipclear" id="clear1" data-role="photo" aria-label="Remove photo" title="Remove the photo and start over. A fit you saved for it comes back when you pick it again." hidden><svg aria-hidden="true" viewBox="0 0 10 10"><path d="M1.5 1.5l7 7M8.5 1.5l-7 7" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button></span>
         <span class="tb-arrow">&rarr;</span>
-        <span class="chipwrap"><button class="inputchip is-empty" id="chip2"><span class="sw" id="sw2"></span><span class="nm">Choose a screenshot…</span></button><button class="chipclear" id="clear2" data-role="screenshot" aria-label="Remove screenshot" title="Remove the screenshot. The fit on the photo is kept." hidden>&times;</button></span>
+        <span class="chipwrap"><button class="inputchip is-empty" id="chip2"><span class="sw" id="sw2"></span><span class="nm">Choose a screenshot…</span></button><button class="chipclear" id="clear2" data-role="screenshot" aria-label="Remove screenshot" title="Remove the screenshot. The fit on the photo is kept." hidden><svg aria-hidden="true" viewBox="0 0 10 10"><path d="M1.5 1.5l7 7M8.5 1.5l-7 7" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button></span>
       </div>
     </div>
     <span class="spacer"></span>
@@ -945,7 +961,7 @@
          the one-accent-on-screen rule is untouched. -->
     <div class="tb-actions">
       <span class="seg" id="fmt" role="radiogroup" aria-label="Output format" hidden>
-        <button class="sel" data-preset="web" role="radio" aria-checked="true" title="H.264 at CRF 16 — near-visually-lossless, plays anywhere.">Web</button><button 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>
+        <button class="sel" data-preset="web" data-label="Web" role="radio" aria-checked="true" title="H.264 at CRF 16 — near-visually-lossless, plays anywhere.">Web</button><button data-preset="prores" data-label="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>
       <button id="save" class="accent" disabled>Preview first</button>
       <button id="imp" class="accent" disabled title="Send the saved file to Claude so it appears in the chat">Send to Claude</button>
@@ -988,7 +1004,7 @@
           <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="rotatequad" title="Turn the screenshot a quarter turn inside the same four edges. The edges stay where they are; only which one is the top changes. Use this when the phone lies on its side and the screenshot lands sideways.">Rotate 90°</button>
+          <button class="sm" id="rotatequad" title="Turn the screenshot inside the same four edges. The edges stay where they are; only which one is the top changes. A portrait screenshot fits a phone only two ways, so on a phone this is a half turn; a quarter turn where the screen is near-square or the screenshot fits the other way.">Rotate</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>
@@ -1521,8 +1537,7 @@ async function clearSource(role){
   $('#pv'+n).innerHTML = '<span class="empty">Select a recent image</span>';
   $('#clear'+n).hidden = true;
   document.querySelectorAll('#recent'+n+' .th').forEach(x=>x.classList.remove('sel'));
-  stopLive();
-  showResult('empty');
+  dropResult();
   if (role==='photo'){
     st.photo = null; st.corners = null; st.remembered = null; st.quadFrom = null;
     st.measured = null;
@@ -1544,13 +1559,27 @@ async function clearSource(role){
       ? 'Screenshot removed — the fit on the photo is kept. Choose another screenshot.'
       : 'Screenshot removed.';
   }
-  markStale();
   // The control that had focus has just hidden itself; without this, focus
   // drops to <body> and a keyboard user is nowhere. The empty chip is the
   // natural next action.
   chip.focus();
 }
 document.querySelectorAll('.chipclear').forEach(b => { b.onclick = () => clearSource(b.dataset.role); });
+/* A source has changed, so whatever the Result pane shows was made from
+   something that is no longer chosen. One place for the three things that
+   must happen together: stop the live clip (its <video> still holds the OLD
+   file and would keep playing it), empty the pane, and un-light Save. Before
+   this, swapping a clip for a screenshot — or one photo for another with a
+   fit already in hand — left the previous composite on screen, and the live
+   layer kept the previous clip running, because setChosen() only redrew the
+   canvas and renderPreview() will not take the pane away from a playing clip
+   (reported 12 Sep 2026: "the preview is not being updated"). */
+function dropResult(){
+  stopLive();
+  showResult('empty');
+  $('#outSt').textContent = '';
+  markStale();
+}
 
 async function choose(role, path, el){
   try{ const r = await api('/api/use', {role, path}); setChosen(role, r.path, r.size, el, r); }
@@ -1572,6 +1601,10 @@ function setChosen(role, path, size, el, meta){
   // server sends the original name back as `name`.
   const shown = (meta && meta.name) || path.split('/').pop();
   chip.querySelector('.nm').textContent = shown;
+  // A different file in either role: the composite on screen is of the old
+  // one. Dropped here, before the state changes, so nothing downstream can
+  // narrate over it; maybeStart() re-renders once the fit is ready.
+  if ((role==='photo' ? st.photo : st.shot) !== path) dropResult();
   chip.title = `${homePath(path)}\n${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(thumb)}")`;
@@ -1760,7 +1793,7 @@ async function maybeStart(){
     }
     $('#cvbar').hidden = false;
     if (st.corners){
-      draw(); drawStrip();
+      draw(); drawStrip(); autoPreview();
       // A reload arrives here with the session's corners already in hand, and
       // the only thing on the status line is the "now choose the screenshot"
       // text from the photo-only step above — a message about a step already
@@ -2061,10 +2094,22 @@ function turnQuad(){
   if (pick && pick.kind === 'corner') pick = {kind: 'corner', i: (pick.i + 3) % 4};
   else if (pick && pick.kind === 'edge') pick = {kind: 'edge', i: (pick.i + 3) % 4};
 }
+// A quarter turn is only offered where the screenshot still FITS. A portrait
+// screenshot on a phone fits two ways, top on either short edge; turned onto a
+// long edge it is mapped anyway — 804px across a 890px edge and 1748px down a
+// 441px one — and the 4:1 squash also flattens the corner rounding into an
+// ellipse, which is what "the corners rotate too and no longer fit the frame"
+// looked like (reported 12 Sep 2026). So Rotate steps to the NEXT
+// orientation the screenshot fits: a half turn on a phone, a quarter turn on a
+// near-square screen or when the screenshot's aspect suits the other edges.
 function rotateQuad(){
   if (!st.corners) return;
   turnQuad();
+  let turns = 1;
+  if (!orientationFits()){ turnQuad(); turns = 2; }
   draw(); drawStrip(); autoPreview();
+  toast('info', turns === 1 ? 'Turned the screenshot a quarter turn.'
+                            : 'Turned the screenshot a half turn — a portrait screenshot fits this screen only two ways.');
 }
 $('#rotatequad').onclick = rotateQuad;
 // The automatic half. Detection orders corners geometrically and cannot know
@@ -2078,16 +2123,24 @@ $('#rotatequad').onclick = rotateQuad;
 // this page has it. Near-square quads (under 1.25) are left alone — perspective
 // can make either kind of edge the longer one. Returns whether it turned.
 const ORIENT_ASPECT = 1.25;
-function orientQuad(){
-  if (!st.corners || !st.shotSize) return false;
+// Does the screenshot fit the quad the way it is ordered now? True when the
+// quad is near-square (either kind of edge can be the top), when there is no
+// screenshot yet, or when the top edge is the kind the screenshot's aspect
+// wants — short for portrait, long for landscape. Shared by the automatic
+// orientation below and by the Rotate button.
+function orientationFits(){
+  if (!st.corners || !st.shotSize) return true;
   const C = st.corners;
   const len = i => Math.hypot(C[(i+1)%4][0]-C[i][0], C[(i+1)%4][1]-C[i][1]);
   const a = (len(0) + len(2)) / 2, b = (len(1) + len(3)) / 2;   // edges 0/2 vs 1/3
-  if (Math.max(a, b) < ORIENT_ASPECT * Math.max(Math.min(a, b), 1e-6)) return false;
+  if (Math.max(a, b) < ORIENT_ASPECT * Math.max(Math.min(a, b), 1e-6)) return true;
   const shotPortrait = st.shotSize[1] > st.shotSize[0];
-  const topShouldBeShort = shotPortrait;
-  const topIsShort = a < b;
-  if (topIsShort === topShouldBeShort) return false;
+  return (a < b) === shotPortrait;
+}
+function orientQuad(){
+  if (!st.corners || !st.shotSize) return false;
+  if (orientationFits()) return false;
+  const C = st.corners;
   // Two candidate top edges (1 and 3, the other pair); the higher one in the
   // image is the top. Turn once to make edge 1 the top, twice more for edge 3.
   const midY = i => (C[i][1] + C[(i+1)%4][1]) / 2;