Screenshots: Refresh retries every failed preview, even if a background check lands meanwhile

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

README.md

@@ -222,7 +222,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Frame Control for iPhone](docs/iphone.md) | The iPhone and iPad app, how it runs the server on the Frame, pairing |
 | [Recovery and OS images](docs/recovery-and-images.md) | Where to download the Frame's OS, what's inside, testing without the headset |
 | [AI agents and assistant](docs/agents.md) | Key-free MCP tools, human approvals, and an opt-in assistant panel |
-| [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, the headset smoke test and a Windows test VM |
+| [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, and the headset smoke test |
 | [Open questions](docs/open-questions.md) | What's still unchecked |
 
 <details>

app/main.js

@@ -1,7 +1,7 @@
 // Frame Control as a desktop app (macOS, Windows, Linux): starts ui/server.py on
 // a free loopback port and shows it in a native window. The server does all the
 // work over the `frame` SSH alias; this file only hosts it.
-const { app, BrowserWindow, Menu, Notification, clipboard, dialog, ipcMain, shell } = require("electron");
+const { app, BrowserWindow, Menu, Notification, clipboard, dialog, ipcMain, nativeImage, shell } = require("electron");
 const { execFile, spawn } = require("child_process");
 const { promisify } = require("util");
 const fs = require("fs");
@@ -264,6 +264,14 @@ function fromUi(e) {
 }
 
 ipcMain.handle("clipboard:read", (e) => fromUi(e) ? clipboard.readText() : "");
+// A PNG or JPEG (a screenshot) onto the clipboard as an image.
+ipcMain.handle("clipboard:writeImage", (e, bytes) => {
+  if (!fromUi(e) || !(bytes instanceof Uint8Array)) return false;
+  const img = nativeImage.createFromBuffer(Buffer.from(bytes));
+  if (img.isEmpty()) throw new Error("not an image");
+  clipboard.writeImage(img);
+  return true;
+});
 ipcMain.handle("connection:setup", (e) => { if (fromUi(e)) setUpConnection(); });
 ipcMain.on("keys:capture", (e, on) => { if (fromUi(e)) win.webContents.setIgnoreMenuShortcuts(on === true); });
 ipcMain.handle("update:get", (e) => fromUi(e) ? publicUpdate() : null);

app/preload.js

@@ -2,8 +2,8 @@
 // to the Frame needs no pbpaste, PowerShell, xclip or wl-clipboard. Also tells
 // the page where a dropped file or folder lives, so a folder can be sideloaded
 // as a title without zipping it (the local server reads it from there).
-// It can open Set Up Connection when the headset can't be reached, and keeps the
-// Frame menu's list of headsets up to date.
+// It can put a screenshot on the clipboard as an image, open Set Up Connection when
+// the headset can't be reached, and keeps the Frame menu's list of headsets up to date.
 // It also receives frame-control://install links (docs/web-install.md): only
 // what the link asked for, never an install; the page asks the user first.
 // And it passes update state both ways: see app/updater.js.
@@ -12,6 +12,7 @@ const { contextBridge, ipcRenderer, webUtils } = require("electron");
 contextBridge.exposeInMainWorld("frameApp", {
   notify: (message, request) => ipcRenderer.invoke("comfort:notify", message, request),
   readClipboard: () => ipcRenderer.invoke("clipboard:read"),
+  writeImage: (bytes) => ipcRenderer.invoke("clipboard:writeImage", bytes),
   setUpConnection: () => ipcRenderer.invoke("connection:setup"),
   // The Frame menu's headset switcher: the page tells it the headsets, and hears picks.
   devicesChanged: (list) => ipcRenderer.send("devices:changed", list),

docs/streaming.md

@@ -21,20 +21,6 @@ The confidence labels are the same as in [ssh.md](ssh.md).
 | **ADB + scrcpy (Lepton only)** | A mirror of the Android container | **Guess** | `brew install scrcpy android-platform-tools`, then `adb connect frame.local:5555` while Lepton Development is running ([adb_lepton](https://partner.steamgames.com/doc/steamhardware/steamframe/adb_lepton)), then `scrcpy`. This only shows Android apps, not SteamOS. |
 | VNC server on the Frame (krfb / wayvnc) | A mirror of the Plasma desktop | **Inferred (SteamOS)** | Deck users run krfb in Desktop Mode ([one.vg](https://one.vg/blog/remote-control-your-steam-deck)). On the Frame, the in-headset desktop is a virtual screen, and krfb isn't known to be preinstalled. RDP and Steam Link cover this case, so it's not recommended. |
 
-**RDP from Windows, verified 2026-09-30:** Windows 11 25H2's Remote Desktop
-(`mstsc`) against BUILD_ID 20260925.6191901. xrdp picks TLS, not NLA, so
-Remote Desktop never asks for a user or password. It warns that the certificate
-(`www.xrdp.org`) can't be verified. After **Yes**, xrdp shows its own "Login to
-frame" box with the username blank. Any user but `steamos` gets "User does not
-exist, or could not be authenticated". Signing in as `steamos` with the
-Developer Mode password opens a Plasma (X11) desktop within about 6 seconds.
-It's a new session on display `:10`, separate from what the headset shows,
-and it uses about 1.3 GB of the Frame's memory. Closing Remote Desktop leaves
-it running, and the next sign-in reconnects to it. To end it, find its
-session with `loginctl list-sessions` over SSH (its leader is `xrdp-sesexec`)
-and run `loginctl terminate-session <id>`; the headset's own session keeps
-running.
-
 **Recommendation for A:** start with Steam Link for macOS, because Valve
 documents it. Use Windows App (RDP) when you want a proper Linux desktop on the
 Mac with keyboard, mouse, and clipboard.

docs/testing.md

@@ -8,7 +8,6 @@ A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/ste
 | Unit tests (`tests/*.py`) | `python3 -m unittest discover -s tests` | Nothing | Parsing, validation, request guards; SSH and HTTP are mocked |
 | Fake Frame (`tests/e2e`) | `scripts/e2e.sh` | Linux with Docker | The real server and scripts against a container that behaves like a Frame |
 | Headset smoke test | `scripts/frame-smoke.sh` | A Frame on the `frame` alias | Install, launch and remove on the real device, recorded with its BUILD_ID |
-| [Windows test VM](#windows-test-vm) | `scripts/windows-vm.sh` | A Linux machine with KVM and Docker | The Windows build on a real Windows desktop, against a real Frame when needed |
 
 ## Unit tests
 
@@ -164,86 +163,6 @@ refuses ids with a hyphen (`missing/invalid arguments`), which the fake had
 accepted. The fake now refuses them the same way, and Frame Control makes ids
 Steam accepts.
 
-## Windows test VM
-
-The unit tests run on Windows in CI, but the app itself doesn't. Anything that
-depends on the Windows desktop (Remote Desktop, the installer, the bundled
-Python, file dialogs) needs a real Windows machine. This is a Windows 11 VM in a
-[dockur/windows](https://github.com/dockur/windows) container on a Linux machine
-with KVM, driven from the Mac with `scripts/windows-vm.sh`.
-
-Setting it up, once, on the Linux machine:
-
-- **Windows comes from Microsoft.** The container downloads the Windows 11
-  image from Microsoft on first start. Windows runs unactivated, which is fine
-  for testing. Don't use activation workarounds or third-party Windows images.
-- **Publish its ports on loopback only.** Map `127.0.0.1:2222:22` (SSH),
-  `127.0.0.1:8006:8006` (the web console) and, if you need it,
-  `127.0.0.1:13389:3389`. The Mac reaches them through `ssh -J`. Use
-  `restart: "no"` and `stop_grace_period: 2m` so it only runs when someone is
-  testing, and a `docker stop` shuts Windows down cleanly.
-- **Give it SSH on first sign-in.** The container runs `/oem/install.bat`
-  once. Have it add the OpenSSH Server capability, start `sshd`, set PowerShell
-  as its default shell, and put a dedicated public key (for example
-  `~/.ssh/id_ed25519_winvm` on the Mac) in
-  `C:\ProgramData\ssh\administrators_authorized_keys`.
-- Give it 4 cores, 8 GB of memory and a 32 GB disk. That's enough for the app
-  and the tests.
-
-Using it, with `WINVM_HOST` set to the Linux machine's ssh alias:
-
-```sh
-scripts/windows-vm.sh up                        # start it and wait for SSH (1-2 minutes)
-scripts/windows-vm.sh put Frame-Control-Setup-x64.exe
-scripts/windows-vm.sh ps 'Start-Process "$env:USERPROFILE\Downloads\Frame-Control-Setup-x64.exe" /S -Wait'
-scripts/windows-vm.sh shot screen.png            # what's on its screen
-scripts/windows-vm.sh click 723 359              # screen pixels, as in the screenshot
-scripts/windows-vm.sh keys s t e a m o s ret     # QEMU key names
-scripts/windows-vm.sh down                       # shut Windows down
-```
-
-- **Clicks go through a scheduled task.** Commands over SSH run in a
-  session with no desktop, so `click` and `scroll` write the position to a
-  file, and a scheduled task running as the signed-in user replays it. The
-  VM's screen must be signed in; it is after `up`. Clicks and scrolls sent at
-  the same time run one after another. QEMU's own `mouse_move` is relative
-  and drifts, so the script doesn't use it.
-- **Screenshots may not show the pointer.** Check the result of a click (a
-  menu that opens, a button that changes) rather than the pointer's position.
-- **Windows' `ssh` waits for stdin.** The script closes it for every command.
-  Do the same if you run `ssh` in the VM by hand.
-- **Starting the app.** Run Frame Control in the signed-in session, not over
-  SSH. Use its Start-menu shortcut via `click`, or a scheduled task like the
-  one `click` uses.
-
-**Testing against a real Frame.** The VM reaches the headset on the LAN like
-any other computer. Run **Set Up Connection** in the VM's Frame Control once;
-that makes the VM's keys. So the VM doesn't keep access between test runs,
-afterwards take the lines it added out of the headset's
-`~/.ssh/authorized_keys`: the ones matching the VM's
-`~/.ssh/id_ed25519_frame.pub` and, if pairing made one,
-`~/.ssh/id_rsa_frame_devkit.pub`. Check that `ssh -o BatchMode=yes frame true`
-in the VM now fails. Then, around each run:
-
-```sh
-scripts/windows-vm.sh frame-key add       # let the VM's key into the headset
-# ... test ...
-scripts/windows-vm.sh frame-key remove    # and take it out again
-```
-
-`add` appends the VM's key tagged `windows-vm-test`, unless the headset
-already trusts that key through another line. `remove` deletes only the exact
-line `add` wrote, so it doesn't undo what Set Up Connection did, and it leaves
-the file alone if it can't rewrite it. Follow the shared-device
-procedure in [Headset smoke test](#headset-smoke-test) before installing or
-launching anything on the headset.
-
-**Verified 2026-09-30:** Windows 11 Pro 25H2 (build 26200) against a Frame on
-BUILD_ID 20260925.6191901. The script was used to install Frame Control 0.4.0,
-connect it to the Frame and follow Remote Desktop through to the Frame's
-desktop ([what it does](streaming.md#a-see-and-control-the-frame-from-the-mac)).
-`frame-key` left `authorized_keys` byte-for-byte as it was.
-
 ## Owned media player
 
 `tests/test_media.py` covers layout evidence and overrides, OU eye ordering,

scripts/windows-vm.sh

@@ -1,161 +0,0 @@
-#!/usr/bin/env zsh
-# Mac or Linux: drive a Windows 11 test VM for Frame Control's Windows build.
-# The VM is a dockur/windows container on another machine; this reaches it over
-# SSH through that machine. See docs/testing.md#windows-test-vm.
-#
-# Usage: scripts/windows-vm.sh <command> [args]
-#   up | down | status      start it (waits for SSH), shut Windows down cleanly, show state
-#   ps '<PowerShell>'       run PowerShell as the VM's user
-#   put <file> [<dir>]      copy a file in (default: the user's Downloads)
-#   shot <out.png>          save the VM's screen
-#   click <x> <y>           click screen pixel x,y in the signed-in session
-#   scroll <x> <y> <n>      turn the wheel n notches at x,y (negative scrolls down)
-#   keys <key>...           type QEMU key names: a, shift-a, ret, tab, esc, spc ...
-#   frame-key add|remove    let the VM's Frame Control key into the headset (`frame`
-#                           alias) for a test run, then take it out again
-#
-# Set WINVM_HOST to the ssh alias of the machine running the container. Optional:
-# WINVM_CONTAINER (frame-winvm), WINVM_USER (frame), WINVM_PORT (2222: the VM's
-# sshd, published on that machine's loopback), WINVM_KEY (~/.ssh/id_ed25519_winvm).
-set -euo pipefail
-setopt extendedglob
-
-host=${WINVM_HOST:?set WINVM_HOST to the ssh alias of the machine running the VM}
-ctr=${WINVM_CONTAINER:-frame-winvm}
-user=${WINVM_USER:-frame}
-port=${WINVM_PORT:-2222}
-key=${WINVM_KEY:-$HOME/.ssh/id_ed25519_winvm}
-opts=(-o ConnectTimeout=20 -o StrictHostKeyChecking=accept-new
-      -o UserKnownHostsFile=${TMPDIR:-/tmp}/windows-vm-known_hosts -i $key -J $host)
-TAG=windows-vm-test  # comment on the VM's key in the headset's authorized_keys
-
-die() { print -u2 "windows-vm: $*"; exit 1 }
-int() { [[ $1 == (-|)<-99999> ]] || die "not a whole number (up to 99999): $1" }
-# These go into commands run by a shell on the other machine, so keep them plain.
-for v in $host $ctr $user; do [[ $v == [A-Za-z0-9_.]##[A-Za-z0-9_.-]# ]] || die "not a plain name: $v"; done
-[[ $port == <1-65535> ]] || die "WINVM_PORT isn't a port: $port"
-
-# Windows' OpenSSH waits for stdin to close, so it always gets /dev/null. The
-# script travels UTF-16 base64-encoded, so no quoting survives two shells.
-vm_ps() {
-  local b64=$(print -rn -- "\$ProgressPreference = 'SilentlyContinue'"$'\n'"$1" |
-              iconv -f UTF-8 -t UTF-16LE | base64 | tr -d '\n')
-  ssh $opts -p $port $user@127.0.0.1 "powershell -NoProfile -NonInteractive -OutputFormat Text -EncodedCommand $b64" </dev/null
-}
-
-# QEMU's monitor inside the container: one command per line on stdin.
-monitor() { ssh $host "docker exec -i $ctr nc -q 1 -U /run/shm/monitor.sock" >/dev/null }
-
-# Input has to come from the signed-in desktop session, not SSH's session 0, so
-# a scheduled task running as the user replays one click or wheel turn written
-# to input.txt, then deletes the file to say it's done. Any error stops it
-# before that, so the caller times out instead of reporting a click.
-INPUT_PS1='$ErrorActionPreference = "Stop"
-$a = (Get-Content "$PSScriptRoot\input.txt").Trim() -split "\s+"
-Add-Type -Namespace WinVm -Name Input -MemberDefinition @"
-[DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
-[DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
-[DllImport("user32.dll")] public static extern void mouse_event(uint flags, int dx, int dy, int data, System.IntPtr extra);
-"@
-[WinVm.Input]::SetProcessDPIAware() | Out-Null
-if (-not [WinVm.Input]::SetCursorPos([int]$a[0], [int]$a[1])) { throw "SetCursorPos failed" }
-Start-Sleep -Milliseconds 150
-if ($a[2] -eq "click") {
-  [WinVm.Input]::mouse_event(0x2, 0, 0, 0, [IntPtr]::Zero); Start-Sleep -Milliseconds 60
-  [WinVm.Input]::mouse_event(0x4, 0, 0, 0, [IntPtr]::Zero)
-} else { [WinVm.Input]::mouse_event(0x800, 0, 0, 120 * [int]$a[3], [IntPtr]::Zero) }
-Remove-Item "$PSScriptRoot\input.txt"'
-
-pointer() {  # x y click|wheel [notches]
-  local b64=$(print -rn -- $INPUT_PS1 | base64 | tr -d '\n')
-  vm_ps '$ErrorActionPreference = "Stop"
-$d = Join-Path $env:LOCALAPPDATA "windows-vm"; $req = "$d\input.txt"; $mine = $false
-# Giving up: end the helper first, or it could wake up and act in a later request.
-function Abandon {
-  Stop-ScheduledTask -TaskName WindowsVmInput -ErrorAction SilentlyContinue
-  foreach ($i in 1..25) {
-    if ((Get-ScheduledTask -TaskName WindowsVmInput -ErrorAction SilentlyContinue).State -ne "Running") { break }
-    Start-Sleep -Milliseconds 200
-  }
-  Remove-Item $req -ErrorAction SilentlyContinue
-}
-trap { [Console]::Error.WriteLine("windows-vm: $_"); if ($mine) { Abandon }; exit 1 }
-# One request at a time: the helper, the task and input.txt are shared. Windows
-# frees the mutex when this process ends, however it ends.
-$lock = New-Object Threading.Mutex($false, "windows-vm-input")
-try { $mine = $lock.WaitOne(15000) } catch [Threading.AbandonedMutexException] { $mine = $true }
-if (-not $mine) { [Console]::Error.WriteLine("windows-vm: another click or scroll is still in progress"); exit 1 }
-New-Item -ItemType Directory -Force $d | Out-Null
-[IO.File]::WriteAllText($req, "'"$*"'")
-[IO.File]::WriteAllText("$d\input.ps1", [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("'$b64'")))
-$act = New-ScheduledTaskAction -Execute powershell.exe -Argument "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$d\input.ps1`""
-$who = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive
-Register-ScheduledTask -TaskName WindowsVmInput -Action $act -Principal $who -Force | Out-Null
-Start-ScheduledTask -TaskName WindowsVmInput
-foreach ($i in 1..50) { if (-not (Test-Path $req)) { exit 0 }; Start-Sleep -Milliseconds 200 }
-Abandon
-[Console]::Error.WriteLine("windows-vm: no input after 10 s: is $env:USERNAME signed in on the VM screen, and is x,y on it?"); exit 1'
-}
-
-(( $# )) || die "usage: see the top of $0"
-cmd=$1; shift
-case $cmd in
-  up)
-    ssh $host "docker start $ctr" >/dev/null
-    for i in {1..60}; do
-      vm_ps 'exit 0' 2>/dev/null && { print "up"; exit 0 }
-      sleep 5
-    done
-    die "Windows didn't answer on SSH within 5 minutes" ;;
-  down)   # the container turns SIGTERM into an ACPI shutdown and waits for Windows
-    ssh $host "docker stop -t 150 $ctr" >/dev/null && print "down" ;;
-  status) ssh $host "docker ps -a --filter 'name=^$ctr\$' --format '{{.Names}}: {{.Status}}'" ;;
-  ps)     (( $# == 1 )) || die "usage: ps '<PowerShell>'"; vm_ps "$1" ;;
-  put)
-    [[ -f ${1:-} ]] || die "usage: put <file> [<dir>]"
-    scp -q $opts -P $port $1 "$user@127.0.0.1:${2:-C:/Users/$user/Downloads}/${1:t}" </dev/null ;;
-  shot)
-    (( $# == 1 )) || die "usage: shot <out.png>"
-    print "screendump /tmp/windows-vm-shot.ppm" | monitor
-    sleep 1
-    ssh $host "docker exec $ctr sh -c 'cat /tmp/windows-vm-shot.ppm && rm /tmp/windows-vm-shot.ppm'" | python3 -c '
-import re, struct, sys, zlib
-d = sys.stdin.buffer.read()
-m = re.match(rb"P6\s+(\d+)\s+(\d+)\s+255\s", d) or sys.exit("windows-vm: no screen dump")
-w, h = int(m[1]), int(m[2]); px = d[m.end():]
-raw = b"".join(b"\0" + px[y * w * 3:(y + 1) * w * 3] for y in range(h))
-chunk = lambda t, b: struct.pack(">I", len(b)) + t + b + struct.pack(">I", zlib.crc32(t + b))
-open(sys.argv[1], "wb").write(b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
-                              + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b""))
-' $1
-    print $1 ;;
-  click)  (( $# == 2 )) || die "usage: click <x> <y>"; int $1; int $2; pointer $1 $2 click ;;
-  scroll) (( $# == 3 )) || die "usage: scroll <x> <y> <n>"; int $1; int $2; int $3; pointer $1 $2 wheel $3 ;;
-  keys)
-    (( $# )) || die "usage: keys <key>..."
-    for k; do [[ $k == [a-z0-9_.,/=-]## ]] || die "not a QEMU key name: $k"; done
-    for k; do print "sendkey $k"; done | monitor ;;
-  frame-key)
-    [[ ${1:-} == (add|remove) ]] || die "usage: frame-key add|remove"
-    pub=(${=$(vm_ps 'Get-Content (Join-Path $env:USERPROFILE ".ssh\id_ed25519_frame.pub")' | tr -d '\r')})
-    [[ ${pub[1]:-} == ssh-ed25519 && ${pub[2]:-} == [A-Za-z0-9+/=]## ]] ||
-      die "the VM has no Frame Control key yet: run Set Up Connection in the app first"
-    # $1: add|remove, $2: the key's base64, $3: the exact line this script owns.
-    ssh frame "sh -s -- $1 '$pub[2]' '$pub[1] $pub[2] $TAG'" <<'EOF'
-f=~/.ssh/authorized_keys
-if [ "$1" = add ]; then
-  if grep -qxF "$3" "$f"; then exit 0; fi
-  if grep -qF "$2" "$f"; then echo "the headset already trusts this key through another entry; left as it is"; exit 0; fi
-  [ -z "$(tail -c 1 "$f")" ] || echo >> "$f"   # a last line without a newline would swallow ours
-  echo "$3" >> "$f"
-else
-  t=$(mktemp "$f.XXXXXX") || exit 1
-  grep -vxF "$3" "$f" > "$t"   # 0: lines left, 1: none left, more: couldn't read or write
-  if [ $? -gt 1 ] || ! chmod 600 "$t" || ! mv "$t" "$f"; then
-    rm -f "$t"; echo "couldn't rewrite $f; it's unchanged" >&2; exit 1
-  fi
-fi
-EOF
-    print "frame-key $1: done" ;;
-  *) die "unknown command: $cmd (see the top of $0)" ;;
-esac

tests/test_server.py

@@ -111,6 +111,8 @@ class ServerGuards(unittest.TestCase):
             ("/api/volume", {"level": 1.5}),
             ("/api/clipboard", {"text": ""}),
             ("/api/open", {"what": "anything-else"}),
+            ("/api/open", {"what": "shot", "id": "1/250820/../../.ssh/id_ed25519"}),
+            ("/api/open", {"what": "shot"}),
             ("/api/shots/save", {"ids": []}),
             ("/api/shots/save", {"ids": "1/250820/20260925225208_1.jpg"}),
             ("/api/shots/save", {"ids": [1]}),
@@ -121,6 +123,10 @@ class ServerGuards(unittest.TestCase):
             status, payload = self.post(path, body)
             self.assertEqual(status, 400, f"{path} {body} -> {payload}")
 
+    def test_showing_a_shot_needs_it_saved_here(self):
+        status, payload = self.post("/api/open", {"what": "shot", "id": "1/250820/19990101000000_1.jpg"})
+        self.assertEqual(status, 404, payload)
+
     def test_screenshot_ids_checked_before_ssh(self):
         for shot in ("../../etc/passwd", "1/250820/x.jpg", "1/2/20260925225208_1.jpg;id", "1/250820/20260925225208_1.gif"):
             status, _, _ = self.request("GET", f"/api/shots/image?id={quote(shot)}", headers={"X-Frame-UI": "1"})

ui/frame_host.py

@@ -153,6 +153,19 @@ def open_path(path):
                      stderr=subprocess.DEVNULL, **DETACHED)
 
 
+def reveal_path(path):
+    """Show a file selected in its folder (Linux file managers vary, so there the folder opens)."""
+    path = Path(path)
+    if MAC:
+        cmd = ["open", "-R", str(path)]
+    elif WINDOWS:
+        cmd = f'explorer /select,"{path}"'  # as one string: Explorer wants the quotes after the comma
+    else:
+        return open_path(path.parent)
+    subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                     stderr=subprocess.DEVNULL, **DETACHED)
+
+
 open_url = open_path  # the same openers hand URLs to the default browser
 
 

ui/index.html

@@ -258,7 +258,12 @@
   .shot-card .row { flex-wrap: nowrap; }
   .shot-card .grow { flex: 1; min-width: 0; }
   .shot-card .t { color: var(--bright); font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-  .shot-card .s { color: var(--muted); font-size: 12px; }
+  .shot-card .s { color: var(--muted); font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .ctx-menu { position: fixed; z-index: 1000; min-width: 200px; padding: 4px; border-radius: 4px; background: #232c38;
+              box-shadow: 0 10px 28px rgba(0,0,0,.6), 0 0 0 1px rgba(255,255,255,.08); }
+  .ctx-menu button { display: block; width: 100%; height: 30px; padding: 0 10px; text-align: left; background: none; }
+  .ctx-menu button:hover, .ctx-menu button:focus-visible { background: var(--blue); color: #fff; outline: none; }
+  .ctx-menu hr { border: 0; border-top: 1px solid rgba(255,255,255,.1); margin: 4px 2px; }
 
   /* ---- library shelf (portrait capsules, like Steam's library home) ---- */
   .shelf { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 16px; }
@@ -701,6 +706,7 @@
           <button class="action" id="shotBtn">Capture</button>
           <button id="liveBtn" title="Keep updating, as video">Live</button>
           <button id="ctrlBtn" title="Control the Frame by tapping or clicking on the view (C)">Control</button>
+          <button id="copyBtn" disabled title="Copy the image to the clipboard (or right-click it)">Copy</button>
           <button id="saveBtn" disabled>Save</button>
         </span>
       </div>
@@ -867,7 +873,7 @@
       <button class="action small" id="shotsSaveNew" disabled>Save new to this computer</button>
     </div>
     <div class="shot-grid" id="shotGrid"><div class="sub">Loading…</div></div>
-    <div class="hint">Screenshots you take in the headset with Steam's screenshot shortcut. Click one to open it in the viewer; Save copies it to <code>~/Pictures/SteamFrame</code>.</div>
+    <div class="hint">Screenshots you take in the headset with Steam's screenshot shortcut. New ones appear on their own. Click one to open it in the viewer, Copy puts it on the clipboard, and Save copies it to <code>~/Pictures/SteamFrame</code>. Right-click for more.</div>
   </section>
   </div>
 
@@ -1869,7 +1875,7 @@ async function capture() {
     if (source === "panel") $("srcBadge").textContent = `Desktop · ${shotPanel?.name || "panel"}`;
     ctrlShow();
     $("stamp").hidden = false; $("stamp").textContent = new Date().toLocaleTimeString();
-    $("saveBtn").disabled = false;
+    $("saveBtn").disabled = $("copyBtn").disabled = false;
     return true;
   } catch (e) {
     log("Capture failed: " + e.message, "e");
@@ -1951,7 +1957,7 @@ async function startVideo() {
         $("viewer").classList.remove("busy");
         c.hidden = false; $("viewerEmpty").hidden = true; $("zoombar").hidden = false; $("asleep").hidden = true;
         $("srcBadge").hidden = false; $("srcBadge").textContent = `${video.label} · video`;
-        $("stamp").hidden = false; $("saveBtn").disabled = false;
+        $("stamp").hidden = false; $("saveBtn").disabled = $("copyBtn").disabled = false;
       }
       frames++;
       const now = performance.now();
@@ -2020,6 +2026,35 @@ $("saveBtn").onclick = () => lastShot ? download(lastShot.blob, lastShot.file) :
   if (!b) return toast("Couldn't encode the image", true);
   download(b, `frame-${view}-${new Date().toISOString().replace(/[:.]/g, "-")}.png`);
 }, "image/png");
+const copyViewer = () => act("Copy image", () => copyImage(lastShot ? lastShot.blob
+  : new Promise((ok, bad) => $("canvas").toBlob(b => b ? ok(b) : bad(new Error("couldn't encode the image")), "image/png"))));
+$("copyBtn").onclick = copyViewer;
+// Right-click the viewer to copy or save what it shows (in Control, a right-click goes to the Frame).
+$("canvas").oncontextmenu = e => {
+  if (ctrl.on || $("saveBtn").disabled) return;
+  e.preventDefault();
+  showMenu(e, [["Copy image", copyViewer], ["Save image", () => $("saveBtn").click()]]);
+};
+// An image onto the clipboard. The app does it natively (JPEG too); a browser
+// takes PNG only, and the blob is handed over as a promise so the click still counts.
+async function copyImage(blob) {
+  if (window.frameApp?.writeImage) {
+    if (!await window.frameApp.writeImage(new Uint8Array(await (await blob).arrayBuffer()))) throw new Error("the app refused the image");
+    return { message: "Copied the image" };
+  }
+  if (!navigator.clipboard?.write || !window.ClipboardItem) throw new Error("This browser can't copy images here");
+  await navigator.clipboard.write([new ClipboardItem({ "image/png": Promise.resolve(blob).then(pngBlob) })]);
+  return { message: "Copied the image" };
+}
+async function pngBlob(blob) {
+  if (blob.type === "image/png") return blob;
+  const bmp = await createImageBitmap(blob);
+  const c = document.createElement("canvas");
+  c.width = bmp.width; c.height = bmp.height;
+  c.getContext("2d").drawImage(bmp, 0, 0);
+  bmp.close();
+  return new Promise((ok, bad) => c.toBlob(b => b ? ok(b) : bad(new Error("couldn't encode the image")), "image/png"));
+}
 function download(blob, name) {
   if (savesToDevice()) return act("Save image", () => saveToDevice([{ blob, name }]));
   const a = document.createElement("a");
@@ -3497,8 +3532,11 @@ loadReports();
 api("/api/host").then(applyHostWording).catch(() => {});
 
 // ---- Steam screenshots from the headset ----
-const shots = { list: [], urls: [] };
+// thumbs: id -> promise of an object URL, kept across reloads so a refresh
+// that finds a new shot fetches only that one's thumbnail.
+const shots = { list: [], sig: null, thumbs: new Map(), loading: null, gen: 0, fill: 0 };
 const STEAMVR_APPID = "250820";
+const SHOTS_POLL_MS = 8000;
 function shotApp(appid) {
   if (appid === STEAMVR_APPID) return "SteamVR";
   const g = state?.games?.find(x => x.appid === appid);
@@ -3510,35 +3548,85 @@ async function shotBlob(id, thumb) {
   if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error || `HTTP ${r.status}`);
   return r.blob();
 }
-async function loadShots() {
-  $("shotsRefresh").disabled = true;
+function shotThumb(id) {
+  const thumbs = shots.thumbs;  // this headset's: a late failure must not touch the next one's
+  if (!thumbs.has(id)) {
+    const p = shotBlob(id, true).then(b => URL.createObjectURL(b));
+    p.catch(() => { if (thumbs.get(id) === p) thumbs.delete(id); });  // try again next time
+    thumbs.set(id, p);
+  }
+  return thumbs.get(id);
+}
+// quiet: a background check. It keeps what's shown if the Frame can't be read,
+// and redraws only when the shots (or whether they're saved here) changed.
+function loadShots(quiet) {
+  if (shots.loading) {
+    // A check already on its way will do for another check; Refresh, or a save
+    // that just finished, reads again after it so the answer is a fresh one.
+    const again = () => loadShots();
+    return quiet === true ? shots.loading : shots.loading.then(again, again);
+  }
+  const p = readShots(quiet === true).finally(() => { if (shots.loading === p) shots.loading = null; });
+  return shots.loading = p;
+}
+// Forget the shots of a headset we've switched away from, and ignore its answers still on their way.
+function resetShots() {
+  closeMenu();  // its items were about the other headset's shot
+  shots.gen++; shots.fill++; shots.loading = null; shots.list = []; shots.sig = null;
+  for (const p of shots.thumbs.values()) p.then(URL.revokeObjectURL, () => {});
+  shots.thumbs = new Map();
+}
+async function readShots(quiet) {
+  const gen = shots.gen;
+  if (!quiet) $("shotsRefresh").disabled = true;
+  let got;
   try {
-    shots.list = (await api("/api/shots")).shots;
+    got = await api("/api/shots");
   } catch (e) {
-    return failed($("shotGrid"), e);
+    if (!quiet && gen === shots.gen) { shots.sig = null; failed($("shotGrid"), e); }
+    return;
   } finally { $("shotsRefresh").disabled = false; }
-  shots.urls.forEach(URL.revokeObjectURL); shots.urls = [];
+  if (gen !== shots.gen) return;
+  ({ shots: shots.list, folder: shots.folder } = got);
+  const sig = JSON.stringify(shots.list.map(s => [s.id, s.saved, shotApp(s.appid)]));
+  if (sig !== shots.sig) { shots.sig = sig; drawShots(); }
+  fillThumbs(quiet);  // not waited for: the next check, or a save, needn't sit behind the thumbnails
+}
+// Thumbnails one at a time over the shared SSH connection. One that failed is
+// tried again on Refresh, not by every background check.
+async function fillThumbs(quiet) {
+  const run = ++shots.fill;
+  // Refresh puts every failed one back in line first, so a background pass that takes over carries them all on.
+  if (!quiet) for (const img of document.querySelectorAll("#shotGrid img[data-failed]")) delete img.dataset.failed;
+  for (const img of document.querySelectorAll("#shotGrid img[data-shot]:not([src])" + (quiet ? ":not([data-failed])" : ""))) {
+    const s = shots.list[+img.dataset.shot];
+    let url;
+    try { url = await shotThumb(s.id); } catch (e) { img.alt = "Preview failed"; img.dataset.failed = 1; }
+    if (run !== shots.fill) return;  // a newer pass (after a check, a redraw or another headset) has taken over
+    if (url) img.src = url;
+  }
+}
+// "Sep 28, 10:37 PM": short enough to sit beside the card's buttons (the full date is its tooltip).
+function shotTime(t) {
+  return new Date(t * 1000).toLocaleString([], { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
+function drawShots() {
+  const ids = new Set(shots.list.map(s => s.id));
+  for (const [id, p] of shots.thumbs) {
+    if (!ids.has(id)) { shots.thumbs.delete(id); p.then(URL.revokeObjectURL, () => {}); }
+  }
   const unsaved = shots.list.filter(s => !s.saved).length;
   $("shotCount").textContent = shots.list.length ? `${shots.list.length} on the Frame` + (unsaved && !HOST.mobile ? ` · ${unsaved} not on this ${HOST.computer}` : "") : "";
   $("shotsSaveNew").disabled = HOST.mobile ? !shots.list.length : !unsaved;
-  $("shotGrid").innerHTML = shots.list.length ? shots.list.map((s, i) => `<div class="shot-card">
-      <img class="thumb" data-shot="${i}" alt="Screenshot from ${esc(shotApp(s.appid))}" title="Open in the viewer">
+  $("shotGrid").innerHTML = shots.list.length ? shots.list.map((s, i) => `<div class="shot-card" data-card="${i}">
+      <img class="thumb" data-shot="${i}" alt="Screenshot from ${esc(shotApp(s.appid))}" title="Open in the viewer (right-click for more)">
       <div class="row"><div class="grow">
           <div class="t">${esc(shotApp(s.appid))}</div>
-          <div class="s">${esc(new Date(s.time * 1000).toLocaleString())}</div></div>
+          <div class="s" title="${esc(new Date(s.time * 1000).toLocaleString())}">${esc(shotTime(s.time))}</div></div>
+        <button class="small" data-shot-copy="${i}" title="Copy the image to the clipboard">Copy</button>
         ${s.saved && !HOST.mobile ? `<span class="tag">On ${HOST.computer}</span>` : `<button class="small" data-shot-save="${i}">Save</button>`}
       </div></div>`).join("")
     : `<div class="sub">No screenshots on the Frame yet.</div>`;
-  // Thumbnails one at a time over the shared SSH connection.
-  for (const img of document.querySelectorAll("#shotGrid img[data-shot]")) {
-    const s = shots.list[+img.dataset.shot];
-    try {
-      const url = URL.createObjectURL(await shotBlob(s.id, true));
-      shots.urls.push(url);
-      img.src = url;
-    } catch (e) { img.alt = "Preview failed"; }
-    if (!img.isConnected) return;  // the list was reloaded meanwhile
-  }
 }
 async function openShot(s) {
   if (live) toggleLive(false);
@@ -3556,7 +3644,7 @@ async function openShot(s) {
     draw();
     $("srcBadge").textContent = `Screenshot · ${shotApp(s.appid)}`;
     $("stamp").hidden = false; $("stamp").textContent = new Date(s.time * 1000).toLocaleString();
-    $("saveBtn").disabled = false;
+    $("saveBtn").disabled = $("copyBtn").disabled = false;
     $("view").scrollIntoView({ behavior: "smooth" });
   } catch (e) {
     toast("Couldn't open the screenshot: " + e.message, true);
@@ -3575,15 +3663,95 @@ async function saveShots(list, btn) {
                         () => api("/api/shots/save", { ids: list.map(s => s.id) }), btn);
   if (res) loadShots();
 }
+const copyShot = (s, btn) => act("Copy screenshot", () => copyImage(shotBlob(s.id, false)), btn);
 $("shotGrid").onclick = e => {
   const img = e.target.closest("img[data-shot]");
   if (img) return openShot(shots.list[+img.dataset.shot]);
+  const c = e.target.closest("[data-shot-copy]");
+  if (c) return copyShot(shots.list[+c.dataset.shotCopy], c);
   const b = e.target.closest("[data-shot-save]");
   if (b) saveShots([shots.list[+b.dataset.shotSave]], b);
 };
-$("shotsRefresh").onclick = loadShots;
+// A small right-click menu. items: [label, fn] pairs, null for a divider.
+// back: the keyboard closed it, so focus returns to where it was.
+function closeMenu(back) {
+  const menu = document.querySelector(".ctx-menu");
+  if (!menu) return;
+  menu.remove();
+  if (back === true && menu.opener?.isConnected) menu.opener.focus();
+}
+function showMenu(e, items) {
+  closeMenu();
+  const menu = document.createElement("div");
+  menu.className = "ctx-menu";
+  menu.setAttribute("role", "menu");
+  menu.opener = document.activeElement;
+  for (const it of items) {
+    if (!it) { menu.append(document.createElement("hr")); continue; }
+    const b = document.createElement("button");
+    b.textContent = it[0];
+    b.setAttribute("role", "menuitem");
+    b.onclick = () => { closeMenu(); it[1](); };
+    menu.append(b);
+  }
+  (document.fullscreenElement || document.body).append(menu);  // in front of a fullscreen viewer
+  const r = menu.getBoundingClientRect();
+  menu.style.left = Math.max(4, Math.min(e.clientX, innerWidth - r.width - 4)) + "px";
+  menu.style.top = Math.max(4, Math.min(e.clientY, innerHeight - r.height - 4)) + "px";
+  menu.querySelector("button").focus();
+}
+document.addEventListener("pointerdown", e => { if (!e.target.closest(".ctx-menu")) closeMenu(); }, true);
+document.addEventListener("keydown", e => {
+  const menu = document.querySelector(".ctx-menu");
+  if (!menu) return;
+  if (e.key === "Escape" || e.key === "Tab") { e.preventDefault(); return closeMenu(true); }  // Tab doesn't wander off behind it
+  if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+  e.preventDefault();  // arrows move through the menu, not the page
+  const items = [...menu.querySelectorAll("button")];
+  const at = items.indexOf(document.activeElement), step = e.key === "ArrowDown" ? 1 : -1;
+  items[at < 0 ? (step > 0 ? 0 : items.length - 1) : (at + step + items.length) % items.length].focus();
+});
+addEventListener("blur", closeMenu);
+document.addEventListener("fullscreenchange", closeMenu);
+addEventListener("scroll", closeMenu, true);
+// Right-click a screenshot for everything it can do.
+$("shotGrid").oncontextmenu = e => {
+  const card = e.target.closest("[data-card]");
+  if (!card) return;
+  e.preventDefault();
+  const s = shots.list[+card.dataset.card];
+  const items = [
+    ["Open in viewer", () => openShot(s)],
+    ["Copy image", () => copyShot(s)],
+  ];
+  if (!s.saved || HOST.mobile) items.push(null, [`Save to ${HOST.computer}`, () => saveShots([s])]);
+  else {
+    const sep = shots.folder.includes("\\") ? "\\" : "/";
+    items.push(null);
+    items.push([`Show in ${!HOST.fileManager || HOST.fileManager === "your file manager" ? "folder" : HOST.fileManager}`,
+                () => act("Show screenshot", () => api("/api/open", { what: "shot", id: s.id }))]);
+    items.push(["Copy file path", () => act("Copy file path", async () => {
+      await copyText(shots.folder + sep + s.file);
+      return { message: "Copied the file path" };
+    })]);
+  }
+  items.push(null, ["Copy file name", () => act("Copy file name", async () => {
+    await copyText(s.file);
+    return { message: "Copied " + s.file };
+  })]);
+  showMenu(e, items);
+};
+function copyText(text) {
+  if (!navigator.clipboard?.writeText) throw new Error("This browser can't copy here");
+  return navigator.clipboard.writeText(text);
+}
+$("shotsRefresh").onclick = () => loadShots();
 $("shotsSaveNew").onclick = e => saveShots(shots.list.filter(s => !s.saved), e.currentTarget);
 $("shotsFolder").onclick = e => act($("shotsFolder").textContent, () => api("/api/open", { what: "shots" }), e.currentTarget);
+// Watch for new shots: a cheap listing over the shared SSH connection while the
+// window is visible and the Frame is reachable, and again on coming back to it.
+setInterval(() => { if (!document.hidden && online) loadShots(true); }, SHOTS_POLL_MS);
+document.addEventListener("visibilitychange", () => { if (!document.hidden && online) loadShots(true); });
 
 // ---- Panel switcher: our UI over SteamVR's panel API ----
 let panelSeq = 0;
@@ -4177,7 +4345,7 @@ if (window.frameApp && window.frameApp.onInstallLink) {
 }
 
 setView("headset");
-refresh().then(loadShots);  // after status, so app names resolve
+refresh().then(() => loadShots());  // after status, so app names resolve
 document.addEventListener("visibilitychange", () => { if (!document.hidden && online === false) refresh(); });
 </script>
 <script>
@@ -4298,7 +4466,7 @@ function onConnection(s) {
     lastImg = null; lastShot = null;
     $("canvas").hidden = true; $("viewerEmpty").hidden = false; $("zoombar").hidden = true;
     ["stamp", "srcBadge", "asleep"].forEach(id => $(id).hidden = true);
-    $("saveBtn").disabled = true;
+    $("saveBtn").disabled = $("copyBtn").disabled = true;
     // Lists and their buttons (Remove, Launch…) were the other headset's: clear them
     // before anyone clicks one, until the new headset's arrive.
     ["games", "titleList", "andApps", "flatpaks", "shotGrid", "gmGrid"].forEach(id => {
@@ -4307,7 +4475,7 @@ function onConnection(s) {
     disp.list = []; disp.port = null;
     // The lists behind those panels too, so filters can't bring the old ones back.
     gm.owned = null; gm.byId = new Map(); gm.results = []; gm.store = []; gm.storeQ = null; gm.shown = 0; gm.seq++;
-    androidApps = []; shots.list = [];
+    androidApps = []; resetShots();
     titlesSeq++; disp.seq++;  // answers to loads already on their way are ignored
     if (cat.apps) filterCatalog();  // "Installed" tags were the other headset's
     // Confirmations still open were checked against the other headset.

ui/server.py

@@ -1192,6 +1192,12 @@ def open_thing(body):
             SHOTS_DIR.mkdir(parents=True, exist_ok=True)
             frame_host.open_path(SHOTS_DIR)
             return {"message": f"Opened {SHOTS_DIR} in {frame_host.FILE_MANAGER}"}
+        if what == "shot":
+            saved = SHOTS_DIR / shot_path(body.get("id")).rsplit("/", 1)[-1]
+            if not saved.exists():
+                raise Failure("That screenshot isn't saved on this computer yet", 404)
+            frame_host.reveal_path(saved)
+            return {"message": f"Showed {saved.name} in {frame_host.FILE_MANAGER}"}
     except frame_host.HostError as e:
         raise Failure(str(e), 500)
     raise Failure("unknown target", 400)