@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/components/android/android-coords.ts

@@ -0,0 +1,99 @@
+/**
+ * Where a pointer landed, in the terms the emulator wants.
+ *
+ * Three coordinate spaces, and mixing any two of them looks like "taps land slightly off" rather
+ * than like a bug:
+ *
+ *  1. **Element space** — CSS pixels inside the canvas's bounding box, which is what a
+ *     `PointerEvent` gives. The canvas is drawn `object-contain`, so unless the aspect ratios
+ *     match exactly there are letterbox bars that belong to no pixel at all.
+ *  2. **Frame space** — the H.264 picture's own pixels. This is what the canvas holds.
+ *  3. **Device space** — the guest's physical display. `Touch.x` is documented as "the physical
+ *     location on the screen", so a scaled frame's coordinates are NOT what the emulator wants,
+ *     and sending them makes every tap land proportionally short on a downscaled rung.
+ *
+ * Pure, so the arithmetic is testable without a canvas or a WebSocket.
+ */
+import type { AndroidGeometry } from "../../../shared/android-protocol";
+
+export interface ElementBox {
+  width: number;
+  height: number;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** Where the picture actually sits inside an `object-contain` box, letterbox bars excluded. */
+export function containedRect(box: ElementBox, frameWidth: number, frameHeight: number): {
+  left: number; top: number; width: number; height: number; scale: number;
+} {
+  if (frameWidth <= 0 || frameHeight <= 0 || box.width <= 0 || box.height <= 0) {
+    return { left: 0, top: 0, width: 0, height: 0, scale: 0 };
+  }
+  const scale = Math.min(box.width / frameWidth, box.height / frameHeight);
+  const width = frameWidth * scale;
+  const height = frameHeight * scale;
+  return { left: (box.width - width) / 2, top: (box.height - height) / 2, width, height, scale };
+}
+
+/**
+ * Element-space offset -> frame pixels, or null when the point is on a letterbox bar.
+ *
+ * Null rather than a clamp: a tap on the bar beside a phone-shaped picture is not a tap on the
+ * phone's edge, and clamping would make the guest's leftmost column absurdly easy to hit.
+ */
+export function pointerToFrame(
+  box: ElementBox, frameWidth: number, frameHeight: number, offsetX: number, offsetY: number,
+): Point | null {
+  const rect = containedRect(box, frameWidth, frameHeight);
+  if (rect.scale <= 0) return null;
+  const x = (offsetX - rect.left) / rect.scale;
+  const y = (offsetY - rect.top) / rect.scale;
+  if (x < 0 || y < 0 || x > frameWidth || y > frameHeight) return null;
+  // The far edge is inclusive in element space but exclusive in pixels.
+  return { x: Math.min(x, frameWidth - 1), y: Math.min(y, frameHeight - 1) };
+}
+
+/**
+ * Frame pixels -> the guest's own display pixels.
+ *
+ * Two measured facts decide this, and neither is derivable from the proto:
+ *
+ *  1. **`Touch.x/y` are always in the panel's own unrotated pixels** — `hw.lcd.width` by
+ *     `hw.lcd.height` — whatever the device's current rotation is. Verified with `getevent`:
+ *     the guest's touchscreen reports a 0..32767 absolute range, and sending x=2000 on a
+ *     1080-wide panel produced 60679, i.e. 2000/1080 of full scale, clamped past the edge. The
+ *     rotated display's coordinates are NOT what the emulator wants.
+ *  2. **The frame is the rotated display**, so it has to be rotated back. The direction was
+ *     measured per orientation by touching a known panel point with `show_touches` on and
+ *     finding the marker in the frame; each rotation's winner beat the runner-up by an order of
+ *     magnitude (90 deg: 0.040 against 0.449; 180: 0.003 against 0.433; 270: 0.080 against 0.420).
+ *
+ * Normalised coordinates throughout, so the frame being a scaled copy never enters into it.
+ */
+export function frameToDevice(point: Point, geometry: AndroidGeometry): Point {
+  const { width, height, deviceWidth, deviceHeight, rotation } = geometry;
+  if (width <= 0 || height <= 0) return { x: 0, y: 0 };
+  const u = point.x / width;
+  const v = point.y / height;
+  let pu: number;
+  let pv: number;
+  switch (rotation) {
+    case 90:  pu = 1 - v; pv = u; break;
+    case 180: pu = 1 - u; pv = 1 - v; break;
+    case 270: pu = v; pv = 1 - u; break;
+    default:  pu = u; pv = v; break;
+  }
+  return { x: Math.round(pu * deviceWidth), y: Math.round(pv * deviceHeight) };
+}
+
+/** The whole path, element offset to something `sendTouch` accepts. */
+export function pointerToDevice(
+  box: ElementBox, geometry: AndroidGeometry, offsetX: number, offsetY: number,
+): Point | null {
+  const frame = pointerToFrame(box, geometry.width, geometry.height, offsetX, offsetY);
+  return frame ? frameToDevice(frame, geometry) : null;
+}

package/src/web/components/android/android-device-list.tsx

@@ -0,0 +1,329 @@
+/**
+ * The device picker: what AVDs exist, which are running, and what is stopping the rest.
+ *
+ * Plan §6 is explicit that the empty state must say *which* thing is missing — no SDK, no
+ * emulator binary, no system image, no AVD, no usable acceleration — and never show an
+ * indefinite spinner. That is what `/capabilities` returns, one row per requirement with the
+ * command that fixes it, so the answer is the same one the user would get from a terminal.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+import { api } from "@/lib/api-client";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Loader2, Play, Square, RefreshCw, TriangleAlert, Smartphone, Check, Plus, Trash2, RotateCcw,
+  MoreVertical,
+} from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { AndroidAvdCreateDialog } from "./android-avd-create-dialog";
+import { AndroidAvdDestroyDialog, type DestructiveAction } from "./android-avd-destroy-dialog";
+
+interface Requirement { id: string; label: string; met: boolean; detail: string; fix: string | null }
+interface Capabilities {
+  enabled: boolean;
+  ready: boolean;
+  avdCount: number;
+  accelerationOk: boolean;
+  accelerationDetail: string;
+  requirements: Requirement[];
+  encoders: string[];
+  /** False when the SDK command-line tools are missing — there is no `avdmanager` to call. */
+  canCreateAvd: boolean;
+}
+interface Runtime { deviceId: string; generation: number; adbSerial: string | null; ownedByPpm: boolean }
+export interface DeviceRow {
+  avdId: string;
+  name: string;
+  apiLevel: number | null;
+  abi: string | null;
+  displayWidth: number | null;
+  displayHeight: number | null;
+  hardwareKeyboard: boolean;
+  lockedByAnotherProcess: boolean;
+  state: string;
+  runtime: Runtime | null;
+}
+
+export interface AndroidDeviceListProps {
+  onOpen: (device: DeviceRow) => void;
+}
+
+/** A cold boot is minutes, not seconds, so the start route answers with an operation id and this
+ *  polls it. Slow enough not to be chatty, fast enough that "Ready" is not stale. */
+const POLL_MS = 1_500;
+
+export function AndroidDeviceList({ onOpen }: AndroidDeviceListProps) {
+  const [caps, setCaps] = useState<Capabilities | null>(null);
+  const [devices, setDevices] = useState<DeviceRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<Record<string, string>>({});
+  const [creating, setCreating] = useState(false);
+  const [destroy, setDestroy] = useState<{ action: DestructiveAction; device: DeviceRow } | null>(null);
+  const mounted = useRef(true);
+
+  const refresh = useCallback(async () => {
+    try {
+      const c = await api.get<Capabilities>("/api/android/capabilities");
+      if (!mounted.current) return;
+      setCaps(c);
+      if (!c.enabled) return;
+      const d = await api.get<{ devices: DeviceRow[] }>("/api/android/devices");
+      if (!mounted.current) return;
+      setDevices(d.devices);
+      setError(null);
+    } catch (e) {
+      if (mounted.current) setError((e as Error).message);
+    }
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    void refresh();
+    const timer = setInterval(() => void refresh(), POLL_MS * 4);
+    return () => { mounted.current = false; clearInterval(timer); };
+  }, [refresh]);
+
+  const start = useCallback(async (device: DeviceRow) => {
+    setBusy((b) => ({ ...b, [device.avdId]: "Starting…" }));
+    try {
+      const { operationId } = await api.post<{ operationId: string }>(
+        `/api/android/avds/${encodeURIComponent(device.avdId)}/start`, {},
+      );
+      // Poll to completion. A boot is long enough that the user needs to see it progressing,
+      // which is what `detail` carries.
+      for (;;) {
+        await new Promise((r) => setTimeout(r, POLL_MS));
+        if (!mounted.current) return;
+        const op = await api.get<{ state: string; detail?: string; error?: string }>(
+          `/api/android/operations/${operationId}`,
+        );
+        setBusy((b) => ({ ...b, [device.avdId]: op.detail ?? "Starting…" }));
+        if (op.state === "succeeded") break;
+        if (op.state === "failed" || op.state === "cancelled") {
+          setError(op.error ?? "the emulator failed to start");
+          break;
+        }
+      }
+    } catch (e) {
+      if (mounted.current) setError((e as Error).message);
+    } finally {
+      if (mounted.current) {
+        setBusy((b) => { const next = { ...b }; delete next[device.avdId]; return next; });
+        void refresh();
+      }
+    }
+  }, [refresh]);
+
+  const stop = useCallback(async (device: DeviceRow) => {
+    if (!device.runtime) return;
+    setBusy((b) => ({ ...b, [device.avdId]: "Stopping…" }));
+    try {
+      // The generation the client last saw: a stop must not take down a run that has since
+      // restarted under the same name.
+      await api.post(
+        `/api/android/devices/${encodeURIComponent(device.runtime.deviceId)}/stop?generation=${device.runtime.generation}`,
+        {},
+      );
+    } catch (e) {
+      if (mounted.current) setError((e as Error).message);
+    } finally {
+      if (mounted.current) {
+        setBusy((b) => { const next = { ...b }; delete next[device.avdId]; return next; });
+        void refresh();
+      }
+    }
+  }, [refresh]);
+
+  if (!caps) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
+        <Loader2 className="mr-2 size-4 animate-spin" /> Checking this host…
+      </div>
+    );
+  }
+
+  const unmet = caps.requirements.filter((r) => !r.met);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <div className="flex items-center gap-2 border-b px-4 py-3">
+        <Smartphone className="size-4 shrink-0 text-muted-foreground" />
+        <h2 className="min-w-0 flex-1 truncate text-sm font-medium">Android devices</h2>
+        {caps.canCreateAvd && (
+          <Button size="sm" className="h-10" onClick={() => setCreating(true)}>
+            <Plus /> New device
+          </Button>
+        )}
+        <Button variant="ghost" size="icon" className="size-10" onClick={() => void refresh()}
+          title="Refresh" aria-label="Refresh">
+          <RefreshCw />
+        </Button>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto p-4">
+        {error && (
+          <div className="mb-4 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 leading-relaxed">{error}</span>
+          </div>
+        )}
+
+        {unmet.length > 0 && (
+          <div className="mb-4 rounded-md border p-4">
+            <p className="text-sm font-medium">This host is not ready yet</p>
+            <ul className="mt-3 space-y-3">
+              {caps.requirements.map((r) => (
+                <li key={r.id} className="flex items-start gap-2 text-sm leading-relaxed">
+                  {r.met
+                    ? <Check className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
+                    : <TriangleAlert className="mt-0.5 size-4 shrink-0 text-destructive" />}
+                  <span className="min-w-0 flex-1">
+                    <span className={cn(!r.met && "font-medium")}>{r.label}</span>
+                    <span className="block text-muted-foreground">{r.detail}</span>
+                    {!r.met && r.fix && (
+                      // A command to run, not a button: PPM never installs an SDK on the user's
+                      // behalf, and the plan's §6 empty state is meant to be actionable in a
+                      // terminal.
+                      <code className="mt-1 block overflow-x-auto rounded bg-muted px-2 py-1 text-xs">
+                        {r.fix}
+                      </code>
+                    )}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {devices.length === 0 && unmet.length === 0 && (
+          <div className="py-8 text-center">
+            <p className="text-sm leading-relaxed text-muted-foreground">
+              No AVDs on this host yet.
+            </p>
+            {caps.canCreateAvd ? (
+              <Button className="mt-4 min-h-11" onClick={() => setCreating(true)}>
+                <Plus /> New device
+              </Button>
+            ) : (
+              <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+                Create one in Android Studio, or with{" "}
+                <code className="rounded bg-muted px-1 py-0.5 text-xs">avdmanager create avd</code>.
+              </p>
+            )}
+          </div>
+        )}
+
+        <ul className="space-y-2">
+          {devices.map((device) => {
+            const running = device.runtime !== null;
+            const label = busy[device.avdId];
+            return (
+              <li key={device.avdId}
+                className="flex flex-col gap-3 rounded-md border p-4 sm:flex-row sm:items-center">
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium">{device.name}</p>
+                  <p className="mt-0.5 text-xs leading-relaxed text-muted-foreground">
+                    {[
+                      device.apiLevel ? `API ${device.apiLevel}` : null,
+                      device.abi,
+                      device.displayWidth && device.displayHeight
+                        ? `${device.displayWidth}x${device.displayHeight}` : null,
+                      running ? (device.runtime!.ownedByPpm ? "running (PPM)" : "running (external)") : null,
+                    ].filter(Boolean).join(" · ")}
+                  </p>
+                  {device.lockedByAnotherProcess && (
+                    <p className="mt-1 text-xs leading-relaxed text-destructive">
+                      Locked by another process — it is probably open in Android Studio.
+                    </p>
+                  )}
+                  {!device.hardwareKeyboard && (
+                    // Measured in Phase 0: with `hw.keyboard=no` the gRPC `sendKey` call returns
+                    // OK and does nothing at all, so this has to be said rather than debugged.
+                    <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+                      This AVD has no hardware keyboard, so typing will not reach it. Set{" "}
+                      <code className="rounded bg-muted px-1 text-[11px]">hw.keyboard=yes</code> in its config.ini.
+                    </p>
+                  )}
+                </div>
+
+                <div className="flex shrink-0 items-center gap-2">
+                  {label && (
+                    <span className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                      <Loader2 className="size-3.5 animate-spin" /> {label}
+                    </span>
+                  )}
+                  {running ? (
+                    <>
+                      <Button size="sm" className="h-10" onClick={() => onOpen(device)}>View</Button>
+                      {device.runtime!.ownedByPpm && (
+                        <Button size="sm" variant="outline" className="h-10"
+                          disabled={!!label} onClick={() => void stop(device)}>
+                          <Square /> Stop
+                        </Button>
+                      )}
+                    </>
+                  ) : (
+                    <Button size="sm" className="h-10"
+                      disabled={!!label || device.lockedByAnotherProcess || !caps.ready}
+                      onClick={() => void start(device)}>
+                      <Play /> Start
+                    </Button>
+                  )}
+
+                  {/* A visible button rather than a right-click or a long press: wipe and delete
+                      have no other route to them, and a hidden gesture is not a route. It is its
+                      own control, so it never takes the row's own tap away. */}
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <Button variant="ghost" size="icon" className="size-11 md:size-10"
+                        title={`More for ${device.name}`} aria-label={`More for ${device.name}`}>
+                        <MoreVertical />
+                      </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end">
+                      {/* Destructive items are offered only while the AVD is stopped and nothing
+                          else holds its lock — the same rule the host enforces, said up front
+                          rather than as a refusal after the name has been typed. */}
+                      <DropdownMenuItem
+                        className="min-h-11 md:min-h-0"
+                        disabled={running || device.lockedByAnotherProcess || !!label}
+                        onSelect={() => setDestroy({ action: "wipe", device })}
+                      >
+                        <RotateCcw /> Wipe data
+                      </DropdownMenuItem>
+                      <DropdownMenuItem
+                        variant="destructive"
+                        className="min-h-11 md:min-h-0"
+                        disabled={running || device.lockedByAnotherProcess || !!label || !caps.canCreateAvd}
+                        onSelect={() => setDestroy({ action: "delete", device })}
+                      >
+                        <Trash2 /> Delete device
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </div>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+
+      <AndroidAvdCreateDialog
+        open={creating}
+        onClose={() => setCreating(false)}
+        existingNames={devices.map((d) => d.name)}
+        onCreated={(name) => { toast.success(`Created ${name}`); void refresh(); }}
+      />
+      <AndroidAvdDestroyDialog
+        action={destroy?.action ?? null}
+        avdId={destroy?.device.avdId ?? ""}
+        deviceName={destroy?.device.name ?? ""}
+        onCancel={() => setDestroy(null)}
+        onDone={(_action, message) => { setDestroy(null); toast.success(message); void refresh(); }}
+      />
+    </div>
+  );
+}