@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/components/android/android-install-panel.tsx

@@ -0,0 +1,280 @@
+/**
+ * Install an APK on this device: either one the browser uploads, or one already on the host.
+ *
+ * Both paths end in the same typed endpoint and the same operation poll, and neither of them
+ * ever names an adb argument — the browser says "this device, this file" and nothing more.
+ *
+ * The project path exists because the common case is not a download: it is an APK Gradle just
+ * wrote into the project PPM already has open, and making the user find it on disk, upload it
+ * back to the machine it is already on, and wait for 80 MB to cross the LAN twice would be
+ * absurd.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { api, getAuthToken } from "@/lib/api-client";
+import { Button } from "@/components/ui/button";
+import { Loader2, TriangleAlert, Check, Upload, X, RefreshCw } from "@/lib/icons";
+import { useProjectStore } from "@/stores/project-store";
+import { cn } from "@/lib/utils";
+import { uploadApk, type ApkUploadHandle } from "./android-apk-upload";
+
+const POLL_MS = 800;
+
+interface ProjectApk { path: string; bytes: number; modifiedAt: number }
+interface OperationView { state: string; detail: string; error: string | null }
+
+export interface AndroidInstallPanelProps {
+  deviceId: string;
+  deviceName: string;
+}
+
+type Phase =
+  | { kind: "idle" }
+  | { kind: "uploading"; fraction: number; filename: string }
+  | { kind: "installing"; operationId: string; detail: string; filename: string }
+  | { kind: "done"; filename: string }
+  | { kind: "failed"; message: string };
+
+export function AndroidInstallPanel({ deviceId, deviceName }: AndroidInstallPanelProps) {
+  const projects = useProjectStore((s) => s.projects);
+  const [projectName, setProjectName] = useState<string>("");
+  const [apks, setApks] = useState<ProjectApk[] | null>(null);
+  const [scanning, setScanning] = useState(false);
+  const [allowDowngrade, setAllowDowngrade] = useState(false);
+  const [phase, setPhase] = useState<Phase>({ kind: "idle" });
+
+  const fileRef = useRef<HTMLInputElement | null>(null);
+  const uploadRef = useRef<ApkUploadHandle | null>(null);
+  // Read by the poll loop, which is created once and would otherwise see the phase from the
+  // render that started it.
+  const phaseRef = useRef<Phase>(phase);
+  phaseRef.current = phase;
+
+  const busy = phase.kind === "uploading" || phase.kind === "installing";
+
+  /** Poll one install to its end. Cancel is a separate typed call, not an abort of this. */
+  const watchOperation = useCallback(async (operationId: string, filename: string) => {
+    for (;;) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      // Stop if this install is no longer the one on screen — cancelled, or replaced by a second
+      // one the user started. Checking only the *kind* would let two loops write over each other.
+      const now = phaseRef.current;
+      if (now.kind !== "installing" || now.operationId !== operationId) return;
+      let op: OperationView;
+      try {
+        op = await api.get<OperationView>(`/api/android/operations/${encodeURIComponent(operationId)}`);
+      } catch (e) {
+        setPhase({ kind: "failed", message: (e as Error).message });
+        return;
+      }
+      if (op.state === "succeeded") { setPhase({ kind: "done", filename }); return; }
+      if (op.state === "failed") { setPhase({ kind: "failed", message: op.error ?? "the install failed" }); return; }
+      if (op.state === "cancelled") { setPhase({ kind: "idle" }); return; }
+      setPhase({ kind: "installing", operationId, detail: op.detail, filename });
+    }
+  }, []);
+
+  const onFile = useCallback((file: File) => {
+    setPhase({ kind: "uploading", fraction: 0, filename: file.name });
+    const handle = uploadApk({
+      deviceId, file, allowDowngrade, token: getAuthToken(),
+      onProgress: (fraction) => setPhase({ kind: "uploading", fraction, filename: file.name }),
+    });
+    uploadRef.current = handle;
+    void handle.done
+      .then((operationId) => {
+        uploadRef.current = null;
+        setPhase({ kind: "installing", operationId, detail: "installing…", filename: file.name });
+        void watchOperation(operationId, file.name);
+      })
+      .catch((e: Error) => {
+        uploadRef.current = null;
+        // A cancel is the user's own doing and needs no red box.
+        setPhase(e.message === "cancelled" ? { kind: "idle" } : { kind: "failed", message: e.message });
+      });
+  }, [deviceId, allowDowngrade, watchOperation]);
+
+  const installFromProject = useCallback(async (path: string) => {
+    const filename = path.split("/").pop() ?? path;
+    setPhase({ kind: "installing", operationId: "", detail: "starting…", filename });
+    try {
+      const { operationId } = await api.post<{ operationId: string }>(
+        `/api/android/devices/${encodeURIComponent(deviceId)}/apk/project`,
+        { project: projectName, path, downgrade: allowDowngrade },
+      );
+      setPhase({ kind: "installing", operationId, detail: "installing…", filename });
+      void watchOperation(operationId, filename);
+    } catch (e) {
+      setPhase({ kind: "failed", message: (e as Error).message });
+    }
+  }, [deviceId, projectName, allowDowngrade, watchOperation]);
+
+  const cancel = useCallback(() => {
+    if (phase.kind === "uploading") { uploadRef.current?.cancel(); return; }
+    if (phase.kind === "installing" && phase.operationId) {
+      void api.post(`/api/android/operations/${encodeURIComponent(phase.operationId)}/cancel`, {})
+        .catch(() => { /* it finished first; the poll will say so */ });
+      setPhase({ kind: "idle" });
+    }
+  }, [phase]);
+
+  const scan = useCallback(async (name: string) => {
+    if (!name) { setApks(null); return; }
+    setScanning(true);
+    try {
+      const res = await api.get<{ apks: ProjectApk[] }>(`/api/android/projects/${encodeURIComponent(name)}/apks`);
+      setApks(res.apks);
+    } catch {
+      setApks([]);
+    } finally {
+      setScanning(false);
+    }
+  }, []);
+
+  useEffect(() => { void scan(projectName); }, [projectName, scan]);
+  useEffect(() => () => uploadRef.current?.cancel(), []);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-3 overflow-auto p-3">
+      <p className="text-xs text-muted-foreground">Installing on {deviceName}.</p>
+
+      {/* --- upload ------------------------------------------------------------------------ */}
+      <div className="flex flex-wrap items-center gap-2">
+        <input
+          ref={fileRef}
+          type="file"
+          accept=".apk,application/vnd.android.package-archive"
+          className="hidden"
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            e.target.value = "";                 // so choosing the same file twice fires again
+            if (file) onFile(file);
+          }}
+        />
+        <Button className="h-11 md:h-9" disabled={busy} onClick={() => fileRef.current?.click()}>
+          <Upload /> Choose an APK
+        </Button>
+        <label className="flex min-h-11 cursor-pointer items-center gap-2 text-sm md:min-h-9">
+          <input
+            type="checkbox"
+            className="size-4"
+            checked={allowDowngrade}
+            disabled={busy}
+            onChange={(e) => setAllowDowngrade(e.target.checked)}
+          />
+          Allow downgrade
+        </label>
+      </div>
+
+      <PhaseView phase={phase} onCancel={cancel} onDismiss={() => setPhase({ kind: "idle" })} />
+
+      {/* --- from a project ---------------------------------------------------------------- */}
+      <div className="flex flex-col gap-2 border-t pt-3">
+        <div className="flex items-center gap-2">
+          <label className="text-sm" htmlFor="android-apk-project">From a project</label>
+          <select
+            id="android-apk-project"
+            className="h-11 min-w-0 flex-1 rounded-md border bg-background px-2 text-sm md:h-9"
+            value={projectName}
+            onChange={(e) => setProjectName(e.target.value)}
+          >
+            <option value="">Choose a project…</option>
+            {projects.map((p) => <option key={p.name} value={p.name}>{p.name}</option>)}
+          </select>
+          {projectName && (
+            <Button variant="ghost" size="icon" className="size-11 md:size-9" disabled={scanning}
+              onClick={() => void scan(projectName)} title="Rescan" aria-label="Rescan">
+              {scanning ? <Loader2 className="animate-spin" /> : <RefreshCw />}
+            </Button>
+          )}
+        </div>
+
+        {scanning && <p className="text-sm text-muted-foreground">Looking for APKs…</p>}
+        {!scanning && apks?.length === 0 && (
+          <p className="text-sm text-muted-foreground">
+            No .apk files in that project yet — build one and press rescan.
+          </p>
+        )}
+        {!scanning && apks && apks.length > 0 && (
+          <ul className="flex flex-col gap-1">
+            {apks.map((apk) => (
+              <li key={apk.path}>
+                <button
+                  type="button"
+                  disabled={busy}
+                  onClick={() => void installFromProject(apk.path)}
+                  className={cn(
+                    "flex min-h-11 w-full flex-col items-start rounded-md border px-3 py-2 text-left text-sm md:min-h-9",
+                    busy ? "opacity-50" : "hover:bg-accent",
+                  )}
+                >
+                  {/* Filenames differ at the end, so the head is what gets cut (CLAUDE.md). */}
+                  <span dir="rtl" className="w-full truncate"><bdi>{apk.path}</bdi></span>
+                  <span className="text-xs text-muted-foreground">
+                    {formatBytes(apk.bytes)} · {new Date(apk.modifiedAt).toLocaleString()}
+                  </span>
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function PhaseView({ phase, onCancel, onDismiss }: { phase: Phase; onCancel: () => void; onDismiss: () => void }) {
+  if (phase.kind === "idle") return null;
+
+  if (phase.kind === "uploading" || phase.kind === "installing") {
+    const percent = phase.kind === "uploading" ? Math.round(phase.fraction * 100) : null;
+    const detail = phase.kind === "installing" ? phase.detail : "";
+    return (
+      <div className="flex flex-col gap-2 rounded-md border p-3">
+        <div className="flex items-center gap-2 text-sm">
+          <Loader2 className="size-4 shrink-0 animate-spin" />
+          <span dir="rtl" className="min-w-0 flex-1 truncate"><bdi>{phase.filename}</bdi></span>
+          <Button variant="ghost" size="icon" className="size-9" onClick={onCancel}
+            title="Cancel" aria-label="Cancel">
+            <X />
+          </Button>
+        </div>
+        {percent !== null ? (
+          <>
+            <div className="h-1.5 overflow-hidden rounded-full bg-muted">
+              <div className="h-full bg-primary transition-[width]" style={{ width: `${percent}%` }} />
+            </div>
+            <p className="text-xs text-muted-foreground">Uploading — {percent}%</p>
+          </>
+        ) : (
+          // adb has no percentage to report, so the panel does not invent one.
+          <p className="text-xs text-muted-foreground">{detail}</p>
+        )}
+      </div>
+    );
+  }
+
+  if (phase.kind === "done") {
+    return (
+      <div className="flex items-center gap-2 rounded-md border border-emerald-600/40 bg-emerald-600/10 p-3 text-sm">
+        <Check className="size-4 shrink-0 text-emerald-600 dark:text-emerald-400" />
+        <span dir="rtl" className="min-w-0 flex-1 truncate"><bdi>{phase.filename}</bdi></span>
+        <span className="shrink-0 text-muted-foreground">installed</span>
+        <Button variant="ghost" size="icon" className="size-9" onClick={onDismiss} aria-label="Dismiss"><X /></Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm">
+      <TriangleAlert className="mt-0.5 size-4 shrink-0 text-destructive" />
+      <span className="min-w-0 flex-1">{phase.message}</span>
+      <Button variant="ghost" size="icon" className="size-9" onClick={onDismiss} aria-label="Dismiss"><X /></Button>
+    </div>
+  );
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/src/web/components/android/android-log-filter.ts

@@ -0,0 +1,75 @@
+/**
+ * What the log panel shows, as pure functions.
+ *
+ * Separate from the component because a zustand-touching or DOM-touching module cannot be loaded
+ * under `bun:test` (the stores read `localStorage` at import time), and these three decisions —
+ * which level counts, what the search matches, how the ring is bounded — are exactly the ones
+ * worth pinning.
+ */
+import type { AndroidLogEntry, AndroidLogLevel } from "../../../shared/android-protocol";
+
+/** Ascending severity. The panel's picker is a *minimum*, so the order is the whole mechanism. */
+export const LOG_LEVELS: AndroidLogLevel[] = ["verbose", "debug", "info", "warn", "error", "fatal"];
+
+const RANK = new Map(LOG_LEVELS.map((l, i) => [l, i]));
+
+export function meetsLevel(level: AndroidLogLevel, minimum: AndroidLogLevel): boolean {
+  return (RANK.get(level) ?? 0) >= (RANK.get(minimum) ?? 0);
+}
+
+export interface LogFilter {
+  minimum: AndroidLogLevel;
+  /** Matched case-insensitively against the tag and the message, never against the pid. */
+  text: string;
+  /** Only entries from this pid. 0 means every process. */
+  pid: number;
+}
+
+export const EMPTY_FILTER: LogFilter = { minimum: "verbose", text: "", pid: 0 };
+
+export function matchesFilter(entry: AndroidLogEntry, filter: LogFilter): boolean {
+  if (!meetsLevel(entry.level, filter.minimum)) return false;
+  if (filter.pid !== 0 && entry.pid !== filter.pid) return false;
+  const needle = filter.text.trim().toLowerCase();
+  if (needle.length === 0) return true;
+  return entry.tag.toLowerCase().includes(needle) || entry.message.toLowerCase().includes(needle);
+}
+
+/**
+ * Append a batch and keep the newest `max`.
+ *
+ * Returns the same array reference when nothing arrived, so a React state setter given this can
+ * bail out instead of re-rendering — a device logging nothing must not cost a render a tick.
+ */
+export function appendBounded(
+  existing: AndroidLogEntry[],
+  incoming: AndroidLogEntry[],
+  max: number,
+): AndroidLogEntry[] {
+  if (incoming.length === 0) return existing;
+  // A reconnection replays the server's whole ring, so the same ids arrive twice. Dropping by id
+  // is cheaper than it looks: the overlap is always at the head, and ids are monotonic per
+  // device, so a single comparison against the last id we hold answers it for the common case.
+  const lastId = existing.length > 0 ? existing[existing.length - 1]!.id : 0;
+  const fresh = incoming[0]!.id > lastId ? incoming : incoming.filter((e) => e.id > lastId);
+  if (fresh.length === 0) return existing;
+  const merged = existing.concat(fresh);
+  return merged.length > max ? merged.slice(merged.length - max) : merged;
+}
+
+/** `13:09:42.640`, local time — the date is in the header, and a log row has no room for it. */
+export function formatLogTime(timestamp: number): string {
+  const d = new Date(timestamp);
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+}
+
+/** One line per entry, in logcat's own `threadtime` shape, for copy and for a saved file. */
+export function formatLogText(entries: AndroidLogEntry[]): string {
+  const letter: Record<AndroidLogLevel, string> = {
+    verbose: "V", debug: "D", info: "I", warn: "W", error: "E", fatal: "F",
+  };
+  return entries
+    .map((e) => `${formatLogTime(e.timestamp)} ${String(e.pid).padStart(5)} ${String(e.tid).padStart(5)} ${letter[e.level]} ${e.tag}: ${e.message}`)
+    .join("\n");
+}

package/src/web/components/android/android-logcat-panel.tsx

@@ -0,0 +1,214 @@
+/**
+ * The device's log, live.
+ *
+ * Three decisions in here are about cost rather than looks:
+ *
+ *  - **Nothing is stored.** The plan is explicit that logcat never reaches the database. The
+ *    ring lives in this component's state and dies with it; the server holds a second, larger
+ *    one so reopening the panel is not an empty box.
+ *  - **The subscription follows the panel.** Mounting turns the device's log stream on and
+ *    unmounting turns it off, which is the plan's gate ("logs hidden ngừng subscription") — so
+ *    a viewer left open overnight is not also running a logcat nobody is reading.
+ *  - **Following is suspended the moment you scroll up.** Auto-scrolling a list somebody is
+ *    reading is the one behaviour that makes a log viewer useless, and a "follow" checkbox they
+ *    have to find first is not much better.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { ArrowDown, Copy, Check, Pause, Play, Search, Trash2 } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import {
+  appendBounded, EMPTY_FILTER, formatLogText, formatLogTime, LOG_LEVELS, matchesFilter,
+  type LogFilter,
+} from "./android-log-filter";
+import type { AndroidLogEntry, AndroidLogLevel } from "../../../shared/android-protocol";
+
+/** The client keeps fewer than the server's 2000: this is what one person scrolls, not storage. */
+const CLIENT_RING = 1_000;
+/** Rendering every row of a busy log is what makes the panel stutter, not receiving them. */
+const MAX_ROWS = 400;
+
+export interface AndroidLogcatPanelProps {
+  setLogcat: (on: boolean) => void;
+  onLog: (listener: (entries: AndroidLogEntry[]) => void) => () => void;
+}
+
+const LEVEL_CLASS: Record<AndroidLogLevel, string> = {
+  verbose: "text-muted-foreground",
+  debug: "text-muted-foreground",
+  info: "text-foreground",
+  warn: "text-amber-600 dark:text-amber-400",
+  error: "text-destructive",
+  fatal: "text-destructive font-semibold",
+};
+
+const LEVEL_LETTER: Record<AndroidLogLevel, string> = {
+  verbose: "V", debug: "D", info: "I", warn: "W", error: "E", fatal: "F",
+};
+
+export function AndroidLogcatPanel({ setLogcat, onLog }: AndroidLogcatPanelProps) {
+  const [entries, setEntries] = useState<AndroidLogEntry[]>([]);
+  const [filter, setFilter] = useState<LogFilter>(EMPTY_FILTER);
+  const [paused, setPaused] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const [following, setFollowing] = useState(true);
+
+  const listRef = useRef<HTMLDivElement | null>(null);
+  const pausedRef = useRef(false);
+  pausedRef.current = paused;
+
+  // Turning the feed on is this panel existing, and turning it off is it going away. The gate
+  // asks for exactly that, and a separate toggle would let the two disagree.
+  useEffect(() => {
+    setLogcat(true);
+    return () => setLogcat(false);
+  }, [setLogcat]);
+
+  useEffect(() => onLog((batch) => {
+    // Pause freezes the *view*: the stream keeps running on the host so nothing is missed, but
+    // a log that scrolls while you are reading it is the thing pause exists to stop.
+    if (pausedRef.current) return;
+    setEntries((current) => appendBounded(current, batch, CLIENT_RING));
+  }), [onLog]);
+
+  const visible = useMemo(() => {
+    const matched = entries.filter((e) => matchesFilter(e, filter));
+    return matched.length > MAX_ROWS ? matched.slice(matched.length - MAX_ROWS) : matched;
+  }, [entries, filter]);
+
+  // Scroll after the rows are in the DOM, and only while the reader has not scrolled away.
+  useEffect(() => {
+    if (!following) return;
+    const el = listRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [visible, following]);
+
+  const onScroll = useCallback(() => {
+    const el = listRef.current;
+    if (!el) return;
+    // 24px of slack: a list that is one subpixel off the bottom must not read as "scrolled up".
+    setFollowing(el.scrollHeight - el.scrollTop - el.clientHeight < 24);
+  }, []);
+
+  const copyAll = useCallback(async () => {
+    const text = formatLogText(visible);
+    try {
+      // `navigator.clipboard` does not exist on an insecure origin, which is PPM's usual LAN
+      // deployment — the textarea fallback is the only thing that works there.
+      if (navigator.clipboard?.writeText) await navigator.clipboard.writeText(text);
+      else copyViaTextarea(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      copyViaTextarea(text);
+    }
+  }, [visible]);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      <div className="flex flex-wrap items-center gap-2 border-b p-2">
+        <div className="relative min-w-40 flex-1">
+          <Search className="pointer-events-none absolute left-2 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            className="h-11 pl-8 md:h-9"
+            placeholder="Filter tag or message"
+            value={filter.text}
+            onChange={(e) => setFilter((f) => ({ ...f, text: e.target.value }))}
+          />
+        </div>
+
+        {/* A native select so a phone gets its own picker (design guidelines §8). */}
+        <label className="sr-only" htmlFor="android-log-level">Minimum level</label>
+        <select
+          id="android-log-level"
+          className="h-11 rounded-md border bg-background px-2 text-sm md:h-9"
+          value={filter.minimum}
+          onChange={(e) => setFilter((f) => ({ ...f, minimum: e.target.value as AndroidLogLevel }))}
+        >
+          {LOG_LEVELS.map((l) => (
+            <option key={l} value={l}>{l[0]!.toUpperCase() + l.slice(1)}</option>
+          ))}
+        </select>
+
+        <Button variant={paused ? "default" : "ghost"} size="icon" className="size-11 md:size-9"
+          onClick={() => setPaused((p) => !p)}
+          title={paused ? "Resume" : "Pause the view"} aria-label={paused ? "Resume" : "Pause the view"}
+          aria-pressed={paused}>
+          {paused ? <Play /> : <Pause />}
+        </Button>
+        <Button variant="ghost" size="icon" className="size-11 md:size-9"
+          onClick={() => setEntries([])} title="Clear the view" aria-label="Clear the view">
+          <Trash2 />
+        </Button>
+        <Button variant="ghost" size="icon" className="size-11 md:size-9"
+          onClick={() => void copyAll()} title="Copy what is shown" aria-label="Copy what is shown">
+          {copied ? <Check /> : <Copy />}
+        </Button>
+      </div>
+
+      <div
+        ref={listRef}
+        onScroll={onScroll}
+        className="min-h-0 flex-1 overflow-auto px-2 py-1 font-mono text-[11px] leading-[1.45]"
+      >
+        {visible.length === 0 ? (
+          <p className="px-2 py-6 text-center text-sm text-muted-foreground">
+            {entries.length === 0 ? "Waiting for the device to log something…" : "Nothing matches that filter."}
+          </p>
+        ) : visible.map((e) => (
+          <div key={e.id} className="flex gap-2 whitespace-pre-wrap break-words">
+            <span className="shrink-0 tabular-nums text-muted-foreground">{formatLogTime(e.timestamp)}</span>
+            <span className={cn("w-3 shrink-0 text-center font-semibold", LEVEL_CLASS[e.level])}>
+              {LEVEL_LETTER[e.level]}
+            </span>
+            {e.tag && (
+              <button
+                type="button"
+                className="shrink-0 max-w-40 truncate text-left text-muted-foreground hover:underline"
+                title={`Filter by ${e.tag}`}
+                onClick={() => setFilter((f) => ({ ...f, text: e.tag }))}
+              >
+                {e.tag}
+              </button>
+            )}
+            <span className={cn("min-w-0", LEVEL_CLASS[e.level])}>{e.message}</span>
+          </div>
+        ))}
+      </div>
+
+      <div className="flex items-center gap-2 border-t px-2 py-1 text-xs text-muted-foreground">
+        <span>{visible.length === entries.length ? `${entries.length} lines` : `${visible.length} of ${entries.length} lines`}</span>
+        {paused && <span className="text-amber-600 dark:text-amber-400">paused</span>}
+        <span className="flex-1" />
+        {!following && (
+          <Button variant="ghost" size="sm" className="h-8" onClick={() => setFollowing(true)}>
+            <ArrowDown /> Follow
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The insecure-origin copy fallback.
+ *
+ * The textarea must be rendered — `display:none` and `visibility:hidden` both give an empty
+ * selection, and `execCommand` then copies nothing while still returning true (CLAUDE.md, remote
+ * desktop clipboard).
+ */
+function copyViaTextarea(text: string): void {
+  const area = document.createElement("textarea");
+  area.value = text;
+  area.style.position = "fixed";
+  area.style.left = "-9999px";
+  area.setAttribute("readonly", "");
+  document.body.appendChild(area);
+  try {
+    area.select();
+    document.execCommand("copy");
+  } finally {
+    area.remove();
+  }
+}

package/src/web/components/android/android-screenshot-download.ts

@@ -0,0 +1,56 @@
+/**
+ * Saving a screenshot to the browser's downloads.
+ *
+ * The route needs the `Authorization` header, so a plain `<a href>` cannot fetch it — the bytes
+ * come back through `fetch` and are handed to an anchor as a blob URL. Kept out of the component
+ * so the two easy things to get wrong are testable: reading the server's filename out of
+ * `Content-Disposition`, and revoking the URL (a blob URL revoked too early gives the browser a
+ * broken download with no error, CLAUDE.md).
+ */
+
+/** The server names the file; this only has to survive a header it did not write. */
+export function filenameFromDisposition(header: string | null, fallback: string): string {
+  if (!header) return fallback;
+  // RFC 5987 `filename*=UTF-8''...` wins over the plain form when both are present.
+  const extended = header.match(/filename\*\s*=\s*UTF-8''([^;]+)/i);
+  if (extended?.[1]) {
+    try { return decodeURIComponent(extended[1].trim()) || fallback; } catch { /* malformed */ }
+  }
+  const quoted = header.match(/filename\s*=\s*"([^"]*)"/i) ?? header.match(/filename\s*=\s*([^;]+)/i);
+  const name = quoted?.[1]?.trim();
+  return name && name.length > 0 ? name : fallback;
+}
+
+export function screenshotUrl(deviceId: string): string {
+  return `/api/android/devices/${encodeURIComponent(deviceId)}/screenshot`;
+}
+
+/** Hand a blob to the browser as a download. Exported so the save can be tested without a fetch. */
+export function saveBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  // Revoking synchronously races the download in Safari and Firefox; a tick is enough and the
+  // page holds nothing else on it.
+  setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}
+
+export async function downloadScreenshot(deviceId: string, token: string | null, fallbackName: string): Promise<void> {
+  const res = await fetch(screenshotUrl(deviceId), {
+    headers: token ? { Authorization: `Bearer ${token}`, "x-ppm-client": "web" } : { "x-ppm-client": "web" },
+  });
+  if (!res.ok) {
+    // The route answers PPM's envelope on failure and raw PNG on success.
+    let message = `the screenshot failed with HTTP ${res.status}`;
+    try {
+      const body = await res.json() as { error?: string };
+      if (body?.error) message = body.error;
+    } catch { /* not JSON */ }
+    throw new Error(message);
+  }
+  saveBlob(await res.blob(), filenameFromDisposition(res.headers.get("content-disposition"), fallbackName));
+}