@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/components/android/android-tab.tsx

@@ -0,0 +1,66 @@
+/**
+ * The Android tab: a device picker until one is chosen, then that device's screen.
+ *
+ * The choice lives in the tab's metadata rather than in component state so it survives the tab
+ * pool unmounting and remounting the body, and so a reload reopens the same device. It is pinned
+ * to `avdId` — the stable identity — with `deviceId` alongside it as the *runtime* one: an
+ * emulator that restarts gets a new deviceId, and the tab then shows the picker again rather
+ * than pointing a session at a process that no longer exists.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { api } from "@/lib/api-client";
+import { useTabStore } from "@/stores/tab-store";
+import { AndroidDeviceList, type DeviceRow } from "./android-device-list";
+import { AndroidViewer } from "./android-viewer";
+
+export interface AndroidTabProps {
+  metadata?: Record<string, unknown>;
+  tabId?: string;
+}
+
+export function AndroidTab({ metadata, tabId }: AndroidTabProps) {
+  const updateTab = useTabStore((s) => s.updateTab);
+  const avdId = typeof metadata?.avdId === "string" ? metadata.avdId : null;
+
+  const [device, setDevice] = useState<DeviceRow | null>(null);
+  const [checking, setChecking] = useState(avdId !== null);
+
+  // Resolve the pinned AVD to a *running* device on mount. A deviceId from a previous session
+  // names a pid that may be long gone, so it is never trusted — only re-derived.
+  useEffect(() => {
+    if (!avdId) { setChecking(false); return; }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const { devices } = await api.get<{ devices: DeviceRow[] }>("/api/android/devices");
+        if (cancelled) return;
+        setDevice(devices.find((d) => d.avdId === avdId && d.runtime !== null) ?? null);
+      } catch {
+        if (!cancelled) setDevice(null);
+      } finally {
+        if (!cancelled) setChecking(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [avdId]);
+
+  const open = useCallback((row: DeviceRow) => {
+    setDevice(row);
+    if (tabId) updateTab(tabId, { title: row.name, metadata: { ...metadata, avdId: row.avdId } });
+  }, [tabId, updateTab, metadata]);
+
+  const back = useCallback(() => {
+    setDevice(null);
+    if (tabId) updateTab(tabId, { title: "Android", metadata: { ...metadata, avdId: undefined } });
+  }, [tabId, updateTab, metadata]);
+
+  if (checking) return <div className="h-full" />;
+
+  if (!device?.runtime) {
+    return <AndroidDeviceList onOpen={open} />;
+  }
+
+  // The header is the viewer's own: it carries the app tools beside the device name, and two
+  // header rows stacked would cost a phone a fifth of the picture.
+  return <AndroidViewer deviceId={device.runtime.deviceId} deviceName={device.name} onBack={back} />;
+}

package/src/web/components/android/android-tools-drawer.tsx

@@ -0,0 +1,76 @@
+/**
+ * The app tools, docked under the screen.
+ *
+ * One drawer with three tabs rather than a dialog per tool, and it is at the **bottom** on every
+ * size. That is not a mobile concession: a log you read while tapping through the guest has to
+ * be visible at the same time as the guest, which a modal cannot be — and the bottom is also the
+ * thumb zone the design guidelines ask for, so the phone layout comes out of the same decision
+ * instead of needing a second one.
+ *
+ * Each panel is mounted only while its tab is open, which is what makes the logcat subscription
+ * follow the panel: switching to Install really does stop the device's log stream.
+ */
+import { Button } from "@/components/ui/button";
+import { ChevronDown, ScrollText, Smartphone, Clipboard } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { AndroidClipboardPanel } from "./android-clipboard-panel";
+import { AndroidInstallPanel } from "./android-install-panel";
+import { AndroidLogcatPanel } from "./android-logcat-panel";
+import type { AndroidLogEntry } from "../../../shared/android-protocol";
+
+export type AndroidTool = "install" | "logs" | "clipboard";
+
+export const ANDROID_TOOLS: { id: AndroidTool; label: string; Icon: typeof ScrollText }[] = [
+  { id: "install", label: "Install", Icon: Smartphone },
+  { id: "logs", label: "Logs", Icon: ScrollText },
+  { id: "clipboard", label: "Clipboard", Icon: Clipboard },
+];
+
+export interface AndroidToolsDrawerProps {
+  tool: AndroidTool;
+  onToolChange: (tool: AndroidTool) => void;
+  onClose: () => void;
+  deviceId: string;
+  deviceName: string;
+  setLogcat: (on: boolean) => void;
+  onLog: (listener: (entries: AndroidLogEntry[]) => void) => () => void;
+}
+
+export function AndroidToolsDrawer(props: AndroidToolsDrawerProps) {
+  const { tool, onToolChange, onClose, deviceId, deviceName, setLogcat, onLog } = props;
+
+  return (
+    <div className="flex h-full min-h-0 flex-col border-t bg-background">
+      <div className="flex items-center gap-1 border-b px-1">
+        {ANDROID_TOOLS.map(({ id, label, Icon }) => (
+          <button
+            key={id}
+            type="button"
+            onClick={() => onToolChange(id)}
+            aria-current={tool === id}
+            className={cn(
+              "flex min-h-11 items-center gap-1.5 border-b-2 px-3 text-sm md:min-h-9",
+              tool === id
+                ? "border-primary font-medium text-foreground"
+                : "border-transparent text-muted-foreground hover:text-foreground",
+            )}
+          >
+            <Icon className="size-4" />
+            {label}
+          </button>
+        ))}
+        <span className="flex-1" />
+        <Button variant="ghost" size="icon" className="size-11 md:size-9" onClick={onClose}
+          title="Hide the tools" aria-label="Hide the tools">
+          <ChevronDown />
+        </Button>
+      </div>
+
+      <div className="min-h-0 flex-1">
+        {tool === "install" && <AndroidInstallPanel deviceId={deviceId} deviceName={deviceName} />}
+        {tool === "logs" && <AndroidLogcatPanel setLogcat={setLogcat} onLog={onLog} />}
+        {tool === "clipboard" && <AndroidClipboardPanel deviceId={deviceId} />}
+      </div>
+    </div>
+  );
+}

package/src/web/components/android/android-viewer.tsx

@@ -0,0 +1,200 @@
+/**
+ * One running emulator, on screen and under the finger.
+ *
+ * Layout notes that are decisions rather than styling:
+ *  - The canvas is `object-contain` inside a flex box, so the picture keeps the guest's aspect
+ *    ratio at any window size and the letterbox bars are real — `android-coords.ts` returns null
+ *    for a tap on one rather than clamping it onto the guest's edge.
+ *  - `touch-action: none` is what stops the browser reading a swipe as a scroll and handing the
+ *    guest a fraction of the gesture.
+ *  - The controls sit at the **bottom** on every size (design guidelines §9), not only on mobile:
+ *    an emulator's own navigation bar is at the bottom too, and putting PPM's copy anywhere else
+ *    makes the two disagree about which direction "back" is.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { getAuthToken } from "@/lib/api-client";
+import { Button } from "@/components/ui/button";
+import { ChevronLeft, Image, Loader2, RefreshCw, TriangleAlert, Hand } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { AndroidControls } from "./android-controls";
+import { ANDROID_TOOLS, AndroidToolsDrawer, type AndroidTool } from "./android-tools-drawer";
+import { downloadScreenshot } from "./android-screenshot-download";
+import { useAndroidKeyboard } from "./use-android-keyboard";
+import { useAndroidSession } from "./use-android-session";
+import { useAndroidTouch } from "./use-android-touch";
+import type { AndroidQuality } from "../../../shared/android-protocol";
+
+export interface AndroidViewerProps {
+  deviceId: string;
+  deviceName: string;
+  /** The tab is mounted but not visible — `tab-pool` keeps other tabs alive. */
+  hidden?: boolean;
+  /** Back to the device picker. Rendered here rather than by the tab so the header is one row. */
+  onBack?: () => void;
+}
+
+export function AndroidViewer({ deviceId, deviceName, hidden = false, onBack }: AndroidViewerProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [quality, setQuality] = useState<AndroidQuality>("balanced");
+  const [tool, setTool] = useState<AndroidTool | null>(null);
+  const [shooting, setShooting] = useState(false);
+  const [toolError, setToolError] = useState<string | null>(null);
+
+  const session = useAndroidSession({ deviceId, quality, canvasRef, paused: hidden });
+  const touch = useAndroidTouch({
+    canvasRef, geometry: session.geometry, enabled: session.controller, send: session.send,
+  });
+  const keyboard = useAndroidKeyboard({
+    geometry: session.geometry, enabled: session.controller, send: session.send,
+  });
+
+  // A viewer that has lost the lease must not keep a soft keyboard up over a screen it cannot
+  // type into.
+  useEffect(() => { if (!session.controller) keyboard.blur(); }, [session.controller, keyboard]);
+
+  const rotation = session.geometry?.rotation ?? 0;
+  const connecting = session.state === "connecting" || session.state === "reconnecting";
+
+  const screenshot = useCallback(async () => {
+    setShooting(true);
+    setToolError(null);
+    try {
+      await downloadScreenshot(deviceId, getAuthToken(), `${deviceName}.png`);
+    } catch (e) {
+      setToolError((e as Error).message);
+    } finally {
+      setShooting(false);
+    }
+  }, [deviceId, deviceName]);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-black">
+      {/* One header row for the whole tab: where you are, and what you can do to the device that
+          is not a key press. The tool buttons are here rather than in the bottom bar because that
+          bar mirrors the guest's own navigation and must not grow app tooling. */}
+      <div className="flex items-center gap-1 border-b bg-background px-1 py-1">
+        {onBack && (
+          <Button variant="ghost" size="icon" className="size-11 md:size-9" onClick={onBack}
+            title="All devices" aria-label="All devices">
+            <ChevronLeft />
+          </Button>
+        )}
+        <span className="min-w-0 flex-1 truncate px-1 text-sm font-medium">{deviceName}</span>
+
+        <Button variant="ghost" size="icon" className="size-11 md:size-9" disabled={shooting}
+          onClick={() => void screenshot()} title="Save a screenshot" aria-label="Save a screenshot">
+          {shooting ? <Loader2 className="animate-spin" /> : <Image />}
+        </Button>
+        {ANDROID_TOOLS.map(({ id, label, Icon }) => (
+          <Button
+            key={id}
+            variant={tool === id ? "secondary" : "ghost"}
+            size="icon"
+            className="size-11 md:size-9"
+            aria-pressed={tool === id}
+            onClick={() => setTool((current) => (current === id ? null : id))}
+            title={label}
+            aria-label={label}
+          >
+            <Icon />
+          </Button>
+        ))}
+      </div>
+
+      {toolError && (
+        <div className="bg-destructive/90 px-4 py-2 text-center text-sm text-white">{toolError}</div>
+      )}
+      {!session.controller && session.state === "live" && (
+        <div className="flex items-center gap-2 border-b bg-background px-4 py-2 text-sm">
+          <Hand className="size-4 shrink-0 text-muted-foreground" />
+          <span className="min-w-0 flex-1 truncate text-muted-foreground">
+            {session.controllerReason ?? "Someone else is controlling this device."}
+          </span>
+          <Button size="sm" onClick={session.takeControl}>Take control</Button>
+        </div>
+      )}
+
+      <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-hidden">
+        <canvas
+          ref={canvasRef}
+          // `touch-action: none` or the browser claims the gesture; `select-none` so a long press
+          // does not start a text selection over the picture.
+          className={cn(
+            "max-h-full max-w-full touch-none select-none object-contain",
+            session.controller ? "cursor-crosshair" : "cursor-default",
+          )}
+          onPointerDown={(e) => { touch.onPointerDown(e); keyboard.focus(); }}
+          onPointerMove={touch.onPointerMove}
+          onPointerUp={touch.onPointerUp}
+          onPointerCancel={touch.onPointerCancel}
+        />
+
+        {!session.hasPicture && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-3 text-sm text-white/70">
+            {session.state === "failed" ? (
+              <>
+                <TriangleAlert className="size-6" />
+                <p className="max-w-xs px-6 text-center">{session.errorMessage ?? "Could not connect."}</p>
+                <Button size="sm" variant="secondary" onClick={session.reconnect}>
+                  <RefreshCw /> Try again
+                </Button>
+              </>
+            ) : (
+              <>
+                <Loader2 className="size-6 animate-spin" />
+                <p>{connecting ? `Connecting to ${deviceName}…` : "Waiting for the first frame…"}</p>
+              </>
+            )}
+          </div>
+        )}
+
+        {session.hasPicture && session.errorMessage && (
+          <div className="absolute inset-x-0 top-0 bg-destructive/90 px-4 py-2 text-center text-sm text-white">
+            {session.errorMessage}
+          </div>
+        )}
+      </div>
+
+      {/* Off-screen but rendered: `display:none` or `visibility:hidden` cannot take focus, and a
+          textarea that cannot take focus receives no `beforeinput`, which is the whole text path. */}
+      <textarea
+        ref={keyboard.inputRef}
+        className="pointer-events-none absolute size-px opacity-0"
+        aria-hidden
+        tabIndex={-1}
+        autoCapitalize="off"
+        autoCorrect="off"
+        autoComplete="off"
+        spellCheck={false}
+        value=""
+        onChange={() => { /* every input is preventDefault'd; this only silences React */ }}
+      />
+
+      {tool && (
+        // A fixed share of the viewer rather than a draggable splitter: the picture has a fixed
+        // aspect ratio, so the space it does not use is letterbox either way.
+        <div className="h-[45%] min-h-0 shrink-0">
+          <AndroidToolsDrawer
+            tool={tool}
+            onToolChange={setTool}
+            onClose={() => setTool(null)}
+            deviceId={deviceId}
+            deviceName={deviceName}
+            setLogcat={session.setLogcat}
+            onLog={session.onLog}
+          />
+        </div>
+      )}
+
+      <AndroidControls
+        layout="bar"
+        send={session.send}
+        controller={session.controller}
+        rotation={rotation}
+        quality={quality}
+        onQualityChange={setQuality}
+        onKeyboard={keyboard.focus}
+      />
+    </div>
+  );
+}

package/src/web/components/android/android-ws-url.ts

@@ -0,0 +1,21 @@
+/** Pure URL builder — mirrors `remote-desktop-ws-url.ts`, including its dev-port bypass, so it
+ *  is unit-testable without a real WebSocket or `window.location`. */
+import { withWsAuth } from "@/lib/ws-auth";
+
+export interface LocationParts {
+  protocol: string;
+  hostname: string;
+  host: string;
+}
+
+export function resolveAndroidWsUrl(loc: LocationParts, isDev: boolean, devPort = "8081"): string {
+  // The device is NOT in this URL: it is named by the nonce, which the first WS message carries.
+  // A query string lands in proxy and tunnel access logs; which VM a socket drives should not.
+  const authed = withWsAuth("/ws/android");
+  const wsProtocol = loc.protocol === "https:" ? "wss:" : "ws:";
+  if (isDev && loc.protocol !== "https:") {
+    // Same bypass as ws-client.ts: Vite's dev proxy has unreliable WS upgrade handling.
+    return `ws://${loc.hostname}:${devPort}${authed}`;
+  }
+  return `${wsProtocol}//${loc.host}${authed}`;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Opens the Android tab — a tab rather than a floating window, unlike Remote Desktop.
+ *
+ * The difference is not cosmetic: there is exactly one host desktop to control, so a window that
+ * floats over the work is right for it, while a machine can have several AVDs and a developer
+ * looks at one *beside* the code they are changing. A second call focuses the tab that is
+ * already open rather than stacking duplicates on the same device.
+ */
+import { useCallback } from "react";
+import { useTabStore } from "@/stores/tab-store";
+
+export function useOpenAndroid(): () => void {
+  const openTab = useTabStore((s) => s.openTab);
+  const setActiveTab = useTabStore((s) => s.setActiveTab);
+
+  return useCallback(() => {
+    const existing = useTabStore.getState().tabs.find((t) => t.type === "android");
+    if (existing) { setActiveTab(existing.id); return; }
+    openTab({ type: "android", title: "Android", projectId: null, closable: true });
+  }, [openTab, setActiveTab]);
+}

package/src/web/components/android/use-android-available.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether the Android entry should surface at all.
+ *
+ * Hidden only when the host opted out — `ANDROID_EMULATOR_ENABLED` is unset, so `/capabilities`
+ * answers `enabled: false`. Everything the user can fix in place (no SDK, no AVD, no KVM) keeps
+ * the entry visible, because the device list is what explains which of those it is; hiding it
+ * would answer "why is there no Android?" with silence.
+ *
+ * Unlike Remote Desktop this feature is **off by default**: it spawns a VM, and a host that
+ * happens to have an Android SDK installed has not thereby asked PPM to run emulators on it.
+ */
+import { useEffect, useState } from "react";
+import { api } from "@/lib/api-client";
+
+interface Capabilities { enabled: boolean; authRequired: boolean }
+
+export function useAndroidAvailable(): { available: boolean; authRequired: boolean } {
+  const [caps, setCaps] = useState<Capabilities | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void api.get<Capabilities>("/api/android/capabilities")
+      .then((c) => { if (!cancelled) setCaps(c); })
+      .catch(() => { /* an older server has no such route; the entry stays hidden */ });
+    return () => { cancelled = true; };
+  }, []);
+
+  return { available: !!caps?.enabled, authRequired: !!caps?.authRequired };
+}

package/src/web/components/android/use-android-keyboard.ts

@@ -0,0 +1,111 @@
+/**
+ * Typing into the guest, from a physical keyboard or a phone's soft one.
+ *
+ * Everything goes through one hidden, always-mounted `<textarea>` rather than through `keydown`
+ * on the canvas, and that is not a mobile concession — it is the only source that carries what
+ * was actually typed:
+ *
+ *  - A host IME (Telex, pinyin, any of them) composes several keystrokes into one character. The
+ *    `keydown` events are the raw keys, so reading them types "Tieesng" where the user typed
+ *    "Tiếng". `beforeinput` reports the composed text.
+ *  - A phone's soft keyboard reports no useful key codes at all.
+ *  - Chromium delivers a paste into a hidden input as `beforeinput`/`insertFromPaste` with the
+ *    text in **`data`** and a null `dataTransfer` — the opposite of what the spec's
+ *    contenteditable case describes (CLAUDE.md). Taking `data` covers both.
+ *
+ * The server then decides how to deliver it: ASCII is typed, anything else goes via the guest's
+ * clipboard, because `sendKey.text` silently drops every non-ASCII character (measured, Phase 0).
+ * Non-text keys — Enter, Backspace, the arrows, Escape, Tab — have no `beforeinput` that carries
+ * them usefully, so those come from `keydown` and are the only thing that path is used for.
+ */
+import { useCallback, useEffect, useRef } from "react";
+import type { AndroidClientMessage, AndroidGeometry } from "../../../shared/android-protocol";
+
+/** `beforeinput` input types that mean "a key with no text", mapped to the w3c key name the
+ *  emulator's `sendKey` takes. */
+const INPUT_TYPE_KEYS: Record<string, string> = {
+  deleteContentBackward: "Backspace",
+  deleteContentForward: "Delete",
+  insertLineBreak: "Enter",
+  insertParagraph: "Enter",
+};
+
+/** Keys a `beforeinput` never reports, taken from `keydown` instead. */
+const PASSTHROUGH_KEYS = new Set([
+  "Enter", "Backspace", "Delete", "Tab", "Escape",
+  "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight",
+  "Home", "End", "PageUp", "PageDown",
+]);
+
+export interface UseAndroidKeyboardOptions {
+  geometry: AndroidGeometry | null;
+  enabled: boolean;
+  send: (message: AndroidClientMessage) => void;
+}
+
+export interface AndroidKeyboardHandle {
+  /** Attach to the hidden textarea the viewer renders. */
+  inputRef: React.RefObject<HTMLTextAreaElement | null>;
+  /** Give the guest the keystrokes — on desktop when the canvas is clicked, on mobile when the
+   *  keyboard button is tapped (which is what raises the soft keyboard). */
+  focus: () => void;
+  blur: () => void;
+}
+
+export function useAndroidKeyboard(opts: UseAndroidKeyboardOptions): AndroidKeyboardHandle {
+  const { geometry, enabled, send } = opts;
+  const inputRef = useRef<HTMLTextAreaElement | null>(null);
+
+  const geometryRef = useRef(geometry);
+  geometryRef.current = geometry;
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+
+  useEffect(() => {
+    const el = inputRef.current;
+    if (!el) return;
+
+    const onBeforeInput = (event: Event) => {
+      const e = event as InputEvent;
+      if (!enabledRef.current) return;
+      // Nothing is ever allowed to accumulate in the textarea: it is a keystroke source, not a
+      // field, and a growing value would make the caret and the undo stack real.
+      e.preventDefault();
+
+      const key = INPUT_TYPE_KEYS[e.inputType];
+      if (key) {
+        const g = geometryRef.current;
+        if (g) send({ type: "key", geometryGeneration: g.generation, key, action: "press" });
+        return;
+      }
+      const text = e.data ?? e.dataTransfer?.getData("text/plain") ?? "";
+      if (!text) return;
+      // `paste` and `text` reach the same server call; the distinction is kept on the wire so a
+      // future paste-specific behaviour has somewhere to live.
+      send(e.inputType === "insertFromPaste" ? { type: "paste", text } : { type: "text", text });
+    };
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!enabledRef.current) return;
+      if (!PASSTHROUGH_KEYS.has(event.key)) return;
+      // Deliberately NOT preventDefault for everything: swallowing the whole keyboard would also
+      // cancel the `beforeinput` the text path depends on, which is the exact trap
+      // `use-remote-input-capture.ts` documents for Ctrl+V.
+      event.preventDefault();
+      const g = geometryRef.current;
+      if (g) send({ type: "key", geometryGeneration: g.generation, key: event.key, action: "press" });
+    };
+
+    el.addEventListener("beforeinput", onBeforeInput);
+    el.addEventListener("keydown", onKeyDown);
+    return () => {
+      el.removeEventListener("beforeinput", onBeforeInput);
+      el.removeEventListener("keydown", onKeyDown);
+    };
+  }, [send]);
+
+  const focus = useCallback(() => inputRef.current?.focus(), []);
+  const blur = useCallback(() => inputRef.current?.blur(), []);
+
+  return { inputRef, focus, blur };
+}