@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/components/layout/command-palette.tsx

@@ -18,9 +18,11 @@ import {
   CircleX,
   WrapText,
   Zap,
+  Cpu,
 } from "@/lib/icons";
 import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { openSettings } from "@/components/settings/open-settings";
+import { useOpenSystemMonitor } from "@/components/system/use-open-system-monitor";
 import { useTabStore, type TabType } from "@/stores/tab-store";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore } from "@/stores/settings-store";
@@ -28,6 +30,7 @@ import { useIsMobile } from "@/hooks/use-is-mobile";
 import { useIsTouchOnly } from "@/hooks/use-is-touch-only";
 import { useKeybindingsStore } from "@/stores/keybindings-store";
 import { useFileStore, type FileNode } from "@/stores/file-store";
+import { useRemoteFileSearch } from "@/hooks/use-remote-file-search";
 import { useExtensionStore } from "@/stores/extension-store";
 import { extensionIcon } from "@/lib/extension-icons";
 import { useCompareStore } from "@/stores/compare-store";
@@ -128,8 +131,10 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
   const activeProject = useProjectStore((s) => s.activeProject);
   const fileIndex = useFileStore((s) => s.fileIndex);
   const indexStatus = useFileStore((s) => s.indexStatus);
-  const indexProjectName = useFileStore((s) => s.indexProjectName);
+  const indexProject = useFileStore((s) => s.indexProject);
+  const indexRemote = useFileStore((s) => s.indexRemote);
   const loadIndex = useFileStore((s) => s.loadIndex);
+  const openIndexReader = useFileStore((s) => s.openIndexReader);
   const fileTree = useFileStore((s) => s.tree);
   const setSidebarActiveTab = useSettingsStore((s) => s.setSidebarActiveTab);
   const sidebarCollapsed = useSettingsStore((s) => s.sidebarCollapsed);
@@ -139,6 +144,7 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
   const isMobile = useIsMobile();
   const isTouchOnly = useIsTouchOnly();
   const lspEnabled = useSettingsStore((s) => s.lspEnabled);
+  const openSystemMonitor = useOpenSystemMonitor();
 
   /**
    * A query may name one place in a file — `app.ts:120`, `app.ts:120-140`, `app.ts#L120` —
@@ -151,6 +157,11 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
     () => splitSourceLocation(deferredQuery)?.path ?? deferredQuery,
     [deferredQuery],
   );
+  // A project too long to send is searched on the server as the query changes. What comes back
+  // is ranked below with everything else, exactly as the list itself would have been.
+  const remoteFiles = useRemoteFileSearch(activeProject?.name, searchPath, {
+    enabled: open && indexRemote && !!searchPath.trim() && !isPathQuery(searchPath),
+  });
 
   /**
    * Read when an item is actually picked, rather than closed over per command: the file
@@ -306,6 +317,15 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
           onClose();
         },
       },
+      // A phone's only way in: the status bar's CPU/MEM chip, the other one, is hidden below md.
+      {
+        id: "system-monitor", label: "System Monitor", icon: Cpu, group: "action",
+        keywords: "task manager activity monitor cpu memory ram disk network gpu processes services apps performance resources",
+        action: () => {
+          openSystemMonitor();
+          onClose();
+        },
+      },
     ];
 
     // Append extension-contributed commands (with keybinding shortcuts, respecting user overrides)
@@ -330,14 +350,16 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
     });
 
     return [...builtIn, ...designCommands, ...extCmds];
-  }, [activeProject, openTab, onClose, setSidebarActiveTab, sidebarCollapsed, toggleSidebar, getBinding, extContributions, isMobile, isTouchOnly, lspEnabled, designCommands]);
+  }, [activeProject, openTab, onClose, setSidebarActiveTab, sidebarCollapsed, toggleSidebar, getBinding, extContributions, isMobile, isTouchOnly, lspEnabled, designCommands, openSystemMonitor]);
 
   // File commands — from index when ready, fallback to flattened tree
   const fileCommands = useMemo<CommandItem[]>(() => {
     const projectId = activeProject?.name ?? null;
     const meta = activeProject ? { projectName: activeProject.name } : undefined;
     // Filter index to files only — directories are in the index for palette "open folder" affordances but not for file-open commands
-    const files = indexStatus === "ready" && indexProjectName === activeProject?.name ? fileIndex.filter((e) => e.type === "file") : flattenFiles(fileTree);
+    const files = indexRemote
+      ? remoteFiles
+      : indexStatus === "ready" && indexProject === activeProject?.name ? fileIndex.filter((e) => e.type === "file") : flattenFiles(fileTree);
 
     return files.map((f) => ({
       id: `file:${f.path}`,
@@ -350,7 +372,7 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
       isIgnored: ("isIgnored" in f ? f.isIgnored : undefined) as boolean | undefined,
       action: () => openFileTab(f.path, f.name, projectId, meta),
     }));
-  }, [indexStatus, indexProjectName, fileIndex, fileTree, activeProject, openFileTab]);
+  }, [indexStatus, indexProject, indexRemote, remoteFiles, fileIndex, fileTree, activeProject, openFileTab]);
 
   // Filesystem commands — from cached API results
   const fsCommands = useMemo<CommandItem[]>(() => {
@@ -473,12 +495,12 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
     setSelectedIdx(0);
   }, []);
 
-  // Auto-load file index when palette opens and index isn't ready
+  // Load the file index as the palette opens, or refresh it if files changed since, and keep it
+  // current while it stays open. Not on `indexStatus`: a failed load would retry itself in a
+  // loop — the hint below has a retry.
   useEffect(() => {
-    if (open && activeProject && (indexStatus === "idle" || indexProjectName !== activeProject.name)) {
-      loadIndex(activeProject.name);
-    }
-  }, [open, indexStatus, indexProjectName, activeProject, loadIndex]);
+    if (open && activeProject) return openIndexReader(activeProject.name);
+  }, [open, activeProject, openIndexReader]);
 
   // Reset state when opening
   useEffect(() => {

package/src/web/components/layout/mobile-drawer.tsx

@@ -1,5 +1,5 @@
 import { useState, useCallback, useEffect, useMemo, lazy, Suspense } from "react";
-import { X, Bug as BugIcon, Cloud, FolderTree, MonitorSmartphone, Settings } from "@/lib/icons";
+import { X, Bug as BugIcon, Cloud, FolderTree, MonitorSmartphone, Settings, Smartphone } from "@/lib/icons";
 import { useShallow } from "zustand/react/shallow";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
@@ -25,6 +25,8 @@ import { isMobileDevice } from "@/hooks/use-is-mobile";
 import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { useOpenRemoteDesktop } from "@/components/remote-desktop/open-remote-desktop";
 import { useRemoteDesktopAvailable } from "@/components/remote-desktop/use-remote-desktop-available";
+import { useOpenAndroid } from "@/components/android/open-android";
+import { useAndroidAvailable } from "@/components/android/use-android-available";
 import { openSettings } from "@/components/settings/open-settings";
 import { FeatureBadge } from "@/components/ui/feature-badge";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
@@ -84,6 +86,8 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
   const contributions = useExtensionStore((s) => s.contributions);
   const { available: remoteDesktopAvailable } = useRemoteDesktopAvailable();
   const openRemoteDesktop = useOpenRemoteDesktop();
+  const openAndroid = useOpenAndroid();
+  const { available: androidAvailable } = useAndroidAvailable();
   const [activeTab, setActiveTab] = useState<SidebarActiveTab>(initialTab ?? "explorer");
   const [cloudOpen, setCloudOpen] = useState(false);
 
@@ -122,6 +126,9 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
     ...(remoteDesktopAvailable
       ? [{ icon: MonitorSmartphone, label: "Remote", badge: "remote-desktop", onClick: () => { onClose(); openRemoteDesktop(); } } satisfies FooterTileDef]
       : []),
+    ...(androidAvailable
+      ? [{ icon: Smartphone, label: "Android", badge: "android", onClick: () => { onClose(); openAndroid(); } } satisfies FooterTileDef]
+      : []),
     { icon: Cloud, label: "Cloud", onClick: () => setCloudOpen(true) },
     // Also not a sidebar tab — settings open as their own tab here, window on desktop.
     { icon: Settings, label: "Settings", onClick: () => { onClose(); openSettings(); } },

package/src/web/components/layout/nav-section-rail.tsx

@@ -1,9 +1,11 @@
 import { useState, useRef, useEffect, useMemo, memo } from "react";
 import { createPortal } from "react-dom";
-import { Settings, Bug, Cloud, FolderTree, MonitorSmartphone } from "@/lib/icons";
+import { Settings, Bug, Cloud, FolderTree, MonitorSmartphone, Smartphone } from "@/lib/icons";
 import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { useOpenRemoteDesktop } from "@/components/remote-desktop/open-remote-desktop";
 import { useRemoteDesktopAvailable } from "@/components/remote-desktop/use-remote-desktop-available";
+import { useOpenAndroid } from "@/components/android/open-android";
+import { useAndroidAvailable } from "@/components/android/use-android-available";
 import { openSettings } from "@/components/settings/open-settings";
 import { FeatureBadge } from "@/components/ui/feature-badge";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
@@ -160,6 +162,8 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
   }, []);
 
   const openRemoteDesktop = useOpenRemoteDesktop();
+  const openAndroid = useOpenAndroid();
+  const { available: androidAvailable } = useAndroidAvailable();
   const { available: remoteDesktopAvailable } = useRemoteDesktopAvailable();
 
   const handleReportBug = () => openBugReportPopup(version);
@@ -229,6 +233,9 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
         {remoteDesktopAvailable && (
           <FooterUtil icon={MonitorSmartphone} label="Remote Desktop" featureBadge="remote-desktop" onClick={openRemoteDesktop} />
         )}
+        {androidAvailable && (
+          <FooterUtil icon={Smartphone} label="Android" featureBadge="android" onClick={openAndroid} />
+        )}
         <FooterUtil icon={Bug} label="Report Bug" onClick={handleReportBug} />
         <FooterUtil icon={Settings} label="Settings" onClick={() => openSettings()} />
       </div>

package/src/web/components/layout/reparenting-tab.tsx

@@ -12,7 +12,7 @@
  * remount the tab and destroy exactly the state (xterm buffer, Monaco undo stack, chat
  * scroll) this component exists to preserve.
  */
-import { useLayoutEffect, useRef, Suspense, type LazyExoticComponent, type ComponentType } from "react";
+import { useLayoutEffect, useRef, Suspense, type ComponentType } from "react";
 import { createPortal } from "react-dom";
 import { Loader2 } from "@/lib/icons";
 import { usePanelStore } from "@/stores/panel-store";
@@ -24,7 +24,7 @@ import { slotRegistry } from "./tab-pool-registry";
 export interface ReparentingTabProps {
   tabId: string;
   panelId: string;
-  component: LazyExoticComponent<ComponentType<{ metadata?: Record<string, unknown>; tabId?: string }>>;
+  component: ComponentType<{ metadata?: Record<string, unknown>; tabId?: string }>;
   metadata?: Record<string, unknown>;
   isActive: boolean;
   /** Off-screen parent the wrapper lives in whenever its panel has no slot mounted. */

package/src/web/components/layout/tab-content.tsx

@@ -64,6 +64,11 @@ const TAB_COMPONENTS: Record<TabType, React.LazyExoticComponent<React.ComponentT
       default: m.ConflictEditor,
     })),
   ),
+  android: lazy(() =>
+    import("@/components/android/android-tab").then((m) => ({
+      default: m.AndroidTab,
+    })),
+  ),
   "system-monitor": lazy(() =>
     import("@/components/system/system-monitor-tab").then((m) => ({
       default: m.SystemMonitorTab,

package/src/web/components/layout/tab-pool.tsx

@@ -12,7 +12,7 @@
  * ever swaps a wrapper. In exchange React binds its listeners to the wrapper itself, so
  * they travel with the node — including into another document.
  */
-import { useState, useEffect, useSyncExternalStore, lazy } from "react";
+import { useState, useEffect, useSyncExternalStore } from "react";
 import { usePanelStore } from "@/stores/panel-store";
 import { useMountedTabsStore } from "@/stores/mounted-tabs-store";
 import type { TabType } from "@/stores/tab-store";
@@ -20,33 +20,44 @@ import { collectTabEntries, filterMountableEntries } from "./tab-pool-collect";
 import { slotRegistry } from "./tab-pool-registry";
 import { ReparentingTab } from "./reparenting-tab";
 import { useWindowPanelReconcile } from "./use-window-panel-reconcile";
+import { lazyWithPreload, type PreloadableComponent } from "@/lib/lazy-with-preload";
 
 export { registerPanelSlot } from "./tab-pool-registry";
 
 // ---------------------------------------------------------------------------
 // Lazy tab components (single source of truth for all tab types)
 // ---------------------------------------------------------------------------
-const TAB_COMPONENTS: Record<TabType, React.LazyExoticComponent<React.ComponentType<{ metadata?: Record<string, unknown>; tabId?: string }>>> = {
-  terminal: lazy(() => import("@/components/terminal/terminal-tab").then((m) => ({ default: m.TerminalTab }))),
-  chat: lazy(() => import("@/components/chat/chat-tab").then((m) => ({ default: m.ChatTab }))),
-  editor: lazy(() => import("@/components/editor/code-editor").then((m) => ({ default: m.CodeEditor }))),
-  database: lazy(() => import("@/components/database/database-viewer").then((m) => ({ default: m.DatabaseViewer }))),
-  sqlite: lazy(() => import("@/components/sqlite/sqlite-viewer").then((m) => ({ default: m.SqliteViewer }))),
-  postgres: lazy(() => import("@/components/postgres/postgres-viewer").then((m) => ({ default: m.PostgresViewer }))),
-  "git-diff": lazy(() => import("@/components/editor/diff-viewer").then((m) => ({ default: m.DiffViewer }))),
-  "branch-review": lazy(() => import("@/components/branch-review/branch-review-tab").then((m) => ({ default: m.BranchReviewTab }))),
-  settings: lazy(() => import("@/components/settings/settings-tab").then((m) => ({ default: m.SettingsTab }))),
-  extension: lazy(() => import("@/components/extensions/extension-webview").then((m) => ({ default: m.ExtensionWebview }))),
-  "extension-webview": lazy(() => import("@/components/extensions/extension-webview").then((m) => ({ default: m.ExtensionWebview }))),
-  "conflict-editor": lazy(() => import("@/components/editor/conflict-editor").then((m) => ({ default: m.ConflictEditor }))),
-  "system-monitor": lazy(() => import("@/components/system/system-monitor-tab").then((m) => ({ default: m.SystemMonitorTab }))),
-  "git-log": lazy(() => import("@/components/git/git-log-panel").then((m) => ({ default: m.GitLogPanel }))),
-  "ai-resource": lazy(() => import("@/components/ai-resources/ai-resource-editor").then((m) => ({ default: m.AiResourceEditor }))),
-  group: lazy(() => import("@/components/group-chat/group-chat-tab").then((m) => ({ default: m.GroupChatTab }))),
-  problems: lazy(() => import("@/components/problems/problems-panel").then((m) => ({ default: m.ProblemsPanel }))),
-  design: lazy(() => import("@/components/design/design-tab").then((m) => ({ default: m.DesignTab }))),
+export const TAB_COMPONENTS: Record<TabType, PreloadableComponent<{ metadata?: Record<string, unknown>; tabId?: string }>> = {
+  terminal: lazyWithPreload(() => import("@/components/terminal/terminal-tab").then((m) => ({ default: m.TerminalTab }))),
+  chat: lazyWithPreload(() => import("@/components/chat/chat-tab").then((m) => ({ default: m.ChatTab }))),
+  editor: lazyWithPreload(() => import("@/components/editor/code-editor").then((m) => ({ default: m.CodeEditor }))),
+  database: lazyWithPreload(() => import("@/components/database/database-viewer").then((m) => ({ default: m.DatabaseViewer }))),
+  sqlite: lazyWithPreload(() => import("@/components/sqlite/sqlite-viewer").then((m) => ({ default: m.SqliteViewer }))),
+  postgres: lazyWithPreload(() => import("@/components/postgres/postgres-viewer").then((m) => ({ default: m.PostgresViewer }))),
+  "git-diff": lazyWithPreload(() => import("@/components/editor/diff-viewer").then((m) => ({ default: m.DiffViewer }))),
+  "branch-review": lazyWithPreload(() => import("@/components/branch-review/branch-review-tab").then((m) => ({ default: m.BranchReviewTab }))),
+  settings: lazyWithPreload(() => import("@/components/settings/settings-tab").then((m) => ({ default: m.SettingsTab }))),
+  extension: lazyWithPreload(() => import("@/components/extensions/extension-webview").then((m) => ({ default: m.ExtensionWebview }))),
+  "extension-webview": lazyWithPreload(() => import("@/components/extensions/extension-webview").then((m) => ({ default: m.ExtensionWebview }))),
+  "conflict-editor": lazyWithPreload(() => import("@/components/editor/conflict-editor").then((m) => ({ default: m.ConflictEditor }))),
+  android: lazyWithPreload(() => import("@/components/android/android-tab").then((m) => ({ default: m.AndroidTab }))),
+  "system-monitor": lazyWithPreload(() => import("@/components/system/system-monitor-tab").then((m) => ({ default: m.SystemMonitorTab }))),
+  "git-log": lazyWithPreload(() => import("@/components/git/git-log-panel").then((m) => ({ default: m.GitLogPanel }))),
+  "ai-resource": lazyWithPreload(() => import("@/components/ai-resources/ai-resource-editor").then((m) => ({ default: m.AiResourceEditor }))),
+  group: lazyWithPreload(() => import("@/components/group-chat/group-chat-tab").then((m) => ({ default: m.GroupChatTab }))),
+  problems: lazyWithPreload(() => import("@/components/problems/problems-panel").then((m) => ({ default: m.ProblemsPanel }))),
+  design: lazyWithPreload(() => import("@/components/design/design-tab").then((m) => ({ default: m.DesignTab }))),
 };
 
+/** The tabs opened most, loaded first by `preloadWhenIdle`. */
+const PRELOAD_FIRST: TabType[] = ["editor", "terminal", "chat", "git-diff", "settings"];
+
+/** Every kind of tab's `preload`, the ones opened most first. */
+export function tabPreloads(): Array<() => Promise<void>> {
+  const rest = (Object.keys(TAB_COMPONENTS) as TabType[]).filter((type) => !PRELOAD_FIRST.includes(type));
+  return [...PRELOAD_FIRST, ...rest].map((type) => TAB_COMPONENTS[type].preload);
+}
+
 const HIDDEN_CONTAINER_STYLE: React.CSSProperties = {
   position: "fixed",
   top: 0,

package/src/web/components/remote-desktop/use-h264-canvas-decoder.ts

@@ -33,6 +33,28 @@ export function shouldDecodeAccessUnit(hasSeenKeyframeThisInstance: boolean, isK
   return isKey || hasSeenKeyframeThisInstance;
 }
 
+/**
+ * Why `VideoDecoder` is missing — and it is usually not the browser.
+ *
+ * WebCodecs is **secure-context only**. Measured in one browser at one moment: `VideoDecoder`
+ * is `undefined` on `http://192.168.98.96:3210` and present on `http://127.0.0.1:3210`. Since
+ * PPM is most often reached over plain HTTP on a LAN — which is exactly how a phone or tablet
+ * gets to it — the common case for this message is a perfectly capable browser on an origin
+ * the specification excludes, and telling that user to "try Chrome" sends them to fix
+ * something that is not broken.
+ *
+ * Exported for the test; there is no `VideoDecoder` to stub in `bun:test` otherwise.
+ */
+export function missingDecoderReason(
+  secureContext: boolean = typeof window !== "undefined" ? window.isSecureContext : true,
+): string {
+  return secureContext
+    ? "This browser has no WebCodecs VideoDecoder — try Chrome, Edge, or Safari 16.4+."
+    : "Video needs a secure origin on this transport: browsers only expose WebCodecs over HTTPS "
+      + "or on localhost. Reach PPM through its HTTPS tunnel, or install the WebRTC relay in "
+      + "Settings, which streams over plain HTTP too.";
+}
+
 export interface UseH264CanvasDecoderResult {
   status: DecoderStatus;
   errorMessage: string | null;
@@ -78,7 +100,7 @@ export function useH264CanvasDecoder(
     lastCodecRef.current = codec;
     if (typeof VideoDecoder === "undefined") {
       setStatus("unsupported");
-      setErrorMessage("This browser has no WebCodecs VideoDecoder — try Chrome, Edge, or Safari 16.4+.");
+      setErrorMessage(missingDecoderReason());
       return;
     }
     const config: VideoDecoderConfig = { codec, optimizeForLatency: true };

package/src/web/components/remote-desktop/use-remote-desktop-connection.ts

@@ -19,6 +19,7 @@ import { api } from "@/lib/api-client";
 import { useSettingsStore } from "@/stores/settings-store";
 import { resolveRemoteDesktopWsUrl } from "./remote-desktop-ws-url";
 import { useH264CanvasDecoder, type DecoderStatus } from "./use-h264-canvas-decoder";
+import { useWebrtcCanvasVideo } from "./use-webrtc-canvas-video";
 import {
   DEFAULT_PRESET_ID, parsePresetId, type QualityChoice, type QualityPresetId,
 } from "../../../shared/remote-desktop-quality";
@@ -33,9 +34,24 @@ const PING_INTERVAL_MS = 5_000;
  *  nonce and its own eviction rules. */
 const FRAME_AUDIO = 2;
 
+/** Set once WebRTC could not carry the picture in this tab. Session storage rather than a ref,
+ *  so a viewer reopened from the same origin does not wait out `CONNECT_DEADLINE_MS` again. */
+const WEBRTC_UNUSABLE_KEY = "ppm.remoteDesktop.webrtcUnusable";
+
+function webrtcMarkedUnusable(): boolean {
+  try { return sessionStorage.getItem(WEBRTC_UNUSABLE_KEY) === "1"; } catch { return false; }
+}
+
+function markWebrtcUnusable(): void {
+  try { sessionStorage.setItem(WEBRTC_UNUSABLE_KEY, "1"); } catch { /* the hook's own ref still holds it */ }
+}
+
 export interface UseRemoteDesktopConnectionResult {
   connState: RemoteDesktopConnState;
   errorMessage: string | null;
+  /** Which transport is carrying the picture. `webrtc` means the host's relay is in use and
+   *  this socket carries only control messages. */
+  transport: "websocket" | "webrtc";
   decoderStatus: DecoderStatus;
   decoderErrorMessage: string | null;
   sendMessage: (msg: Record<string, unknown>) => void;
@@ -162,6 +178,23 @@ export function useRemoteDesktopConnection(
   const [codec, setCodecState] = useState<string | null>(codecRef.current);
 
   const decoder = useH264CanvasDecoder(canvasRef);
+  const webrtcUnusableRef = useRef(false);
+  /** WebRTC's media is UDP straight to the host's interface addresses, which a viewer on the
+   *  Cloudflare tunnel has no route to: the handshake goes through and the picture never comes.
+   *  So a WebRTC that cannot carry it reconnects asking for this socket's stream instead —
+   *  wherever WebCodecs exists to decode that. On a plain-HTTP origin it does not, and the
+   *  WebRTC error is the answer: reconnecting would only fail the same way again. */
+  const onWebrtcFailure = useCallback(() => {
+    if (typeof VideoDecoder === "undefined" || webrtcUnusableRef.current) return;
+    webrtcUnusableRef.current = true;
+    markWebrtcUnusable();
+    setGeneration((g) => g + 1);
+  }, []);
+  const webrtc = useWebrtcCanvasVideo(canvasRef, { onFailure: onWebrtcFailure });
+  /** Which transport is actually carrying the picture. The server decides: it answers with a
+   *  `webrtc` message only when its relay is installed and came up, and otherwise frames access
+   *  units onto this socket exactly as before. */
+  const [transport, setTransport] = useState<"websocket" | "webrtc">("websocket");
   const audio = useOpusAudioPlayer();
   const [audioOn, setAudioOn] = useState(false);
   const [privacyOn, setPrivacyOn] = useState(false);
@@ -276,6 +309,8 @@ export function useRemoteDesktopConnection(
     let pingTimer: ReturnType<typeof setInterval> | null = null;
     setConnState("connecting");
     setErrorMessage(null);
+    // Until the host says otherwise with a `webrtc` message, the picture comes on this socket.
+    setTransport("websocket");
     // A fresh session engages nothing, and the old session's grab died with its socket.
     setPrivacyOn(false);
     setPrivacyError(null);
@@ -306,6 +341,11 @@ export function useRemoteDesktopConnection(
         ws.send(JSON.stringify({
           type: "auth", nonce, ...(displayId ? { displayId } : {}), cursor: showCursorRef.current,
           ...(codecRef.current ? { codec: codecRef.current } : {}),
+          // Asked for until it has failed in this tab (`onWebrtcFailure`); the host grants it
+          // only when its relay is installed. There is no setting for this: WebRTC measured
+          // better on every axis, and on a plain-HTTP LAN origin the WebCodecs path cannot
+          // start at all (`VideoDecoder` is secure-context only).
+          webrtc: !(webrtcUnusableRef.current || webrtcMarkedUnusable()),
         }));
         // Re-pin across a reconnect so a deliberate choice is not silently reset to balanced.
         if (pinnedRef.current) ws.send(JSON.stringify(qualityMessage(pinnedRef.current)));
@@ -315,7 +355,18 @@ export function useRemoteDesktopConnection(
         if (typeof event.data === "string") {
           let msg: Record<string, unknown>;
           try { msg = JSON.parse(event.data); } catch { return; }
-          if (msg.type === "config" && typeof msg.codec === "string") {
+          if (msg.type === "webrtc" && typeof msg.whepPath === "string") {
+            // Sent on connect and again after any respawn (a quality change restarts the
+            // publisher, which drops the browser's reader), so this re-runs the handshake.
+            setTransport("webrtc");
+            // This message stands in for `config` on the relay transport, so the same state it
+            // would have set is applied here — otherwise the quality and codec menus show
+            // their defaults instead of what the host is running.
+            applyQualityMessage(msg);
+            setCodecState(typeof msg.encoder === "string" ? msg.encoder : null);
+            webrtc.start(msg.whepPath);
+            setConnState("streaming");
+          } else if (msg.type === "config" && typeof msg.codec === "string") {
             // A second `config` arrives on every quality change: the new ffmpeg has its own SPS
             // and resolution, and `configure()` closes the old decoder and waits for a keyframe.
             applyQualityMessage(msg);
@@ -394,24 +445,31 @@ export function useRemoteDesktopConnection(
       try { wsRef.current?.close(); } catch { /* tearing down regardless */ }
       wsRef.current = null;
       try { decoder.reset(); } catch { /* tearing down regardless */ }
+      try { webrtc.stop(); } catch { /* tearing down regardless */ }
       try { audio.reset(); } catch { /* tearing down regardless */ }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- reconnect is driven by `generation` + the display pick
   }, [generation, displayId]);
 
   const reconnect = useCallback(() => setGeneration((g) => g + 1), []);
-  const getTotalBytes = useCallback(() => totalBytesRef.current, []);
+  // On the relay transport no video crosses this socket, so the byte counter that feeds the
+  // KB/s stat has to come from WebRTC's own inbound-rtp report instead.
+  const getTotalBytes = useCallback(
+    () => (transport === "webrtc" ? webrtc.getTotalBytes() : totalBytesRef.current),
+    [transport, webrtc],
+  );
 
   return {
     connState,
     errorMessage,
-    decoderStatus: decoder.status,
-    decoderErrorMessage: decoder.errorMessage,
+    transport,
+    decoderStatus: transport === "webrtc" ? webrtc.status : decoder.status,
+    decoderErrorMessage: transport === "webrtc" ? webrtc.errorMessage : decoder.errorMessage,
     sendMessage,
     reconnect,
     getTotalBytes,
-    getFrameCount: decoder.getFrameCount,
-    frameSize: decoder.frameSize,
+    getFrameCount: transport === "webrtc" ? webrtc.getFrameCount : decoder.getFrameCount,
+    frameSize: transport === "webrtc" ? webrtc.frameSize : decoder.frameSize,
     quality,
     setQuality,
     setCustomQuality,