@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/components/remote-desktop/use-webrtc-canvas-video.ts

@@ -0,0 +1,255 @@
+/**
+ * WebRTC (WHEP) video painted into the same `<canvas>` the WebCodecs path draws to.
+ *
+ * Painting into the canvas rather than showing a `<video>` is deliberate: every other part of
+ * the viewer — the scale modes in `remote-desktop-view-style.ts`, coordinate mapping in
+ * `remote-desktop-coords.ts`, the `MediaRecorder` in `use-remote-desktop-recorder.ts`, the
+ * stats overlay — is built on one canvas, and giving it a second rendering surface to reason
+ * about would touch all of them for no user-visible gain. The cost is one hardware-accelerated
+ * `drawImage` per frame.
+ *
+ * Why this path exists at all: `VideoDecoder` is **secure-context only**. Measured in one
+ * browser at one moment, it is `undefined` on `http://192.168.98.96:3210` and present on
+ * `http://127.0.0.1:3210` — so the WebCodecs viewer cannot start on a plain-HTTP LAN origin,
+ * which is how PPM is most often reached from a phone or tablet. `RTCPeerConnection` has no
+ * such restriction and works on both.
+ *
+ * The handshake is non-trickle: ICE gathering is allowed to finish before the offer is posted,
+ * so one request carries every candidate and there is no PATCH channel to keep open. It costs
+ * a few hundred milliseconds at connect and removes a whole signalling path.
+ */
+import { useCallback, useRef, useState } from "react";
+import { getAuthToken } from "@/lib/api-client";
+import type { DecoderStatus } from "./use-h264-canvas-decoder";
+
+/** MediaMTX answers 404 until the publisher's first packet lands, and a quality change
+ *  respawns that publisher — so the handshake retries rather than failing the viewer. */
+const WHEP_RETRY_MS = 400;
+const WHEP_RETRY_LIMIT = 25;   // ~10s, comfortably past ffmpeg's ~400ms respawn
+
+/** How long ICE gets once the answer is in. The media is UDP straight to the host's interface
+ *  addresses, which a viewer on the Cloudflare tunnel has no route to — and measured in
+ *  Chromium, with no candidate reachable `connectionState` only turns `failed` after 15 s, a
+ *  quarter-minute of black screen before the caller can try anything else. A path that works
+ *  connects long before this. */
+export const CONNECT_DEADLINE_MS = 6_000;
+
+export interface UseWebrtcCanvasVideoOptions {
+  /** Called at most once per `start()`, when this path cannot carry the picture: the browser has
+   *  no WebRTC, the handshake was refused or never produced a stream, ICE did not connect within
+   *  `CONNECT_DEADLINE_MS`, or a connection that was up failed. */
+  onFailure?: () => void;
+}
+
+export interface UseWebrtcCanvasVideoResult {
+  status: DecoderStatus;
+  errorMessage: string | null;
+  /** Run (or re-run) the WHEP handshake against a PPM path such as
+   *  `/api/remote-desktop/whep/<ticket>`. Safe to call again on a respawn. */
+  start: (whepPath: string) => void;
+  stop: () => void;
+  getFrameCount: () => number;
+  /** Bytes received on the video track, for the stats overlay. WebRTC counts these for us. */
+  getTotalBytes: () => number;
+  frameSize: { width: number; height: number };
+}
+
+export function useWebrtcCanvasVideo(
+  canvasRef: React.RefObject<HTMLCanvasElement | null>,
+  { onFailure }: UseWebrtcCanvasVideoOptions = {},
+): UseWebrtcCanvasVideoResult {
+  const [status, setStatus] = useState<DecoderStatus>("idle");
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [frameSize, setFrameSize] = useState({ width: 0, height: 0 });
+  const pcRef = useRef<RTCPeerConnection | null>(null);
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const ctxRef = useRef<CanvasRenderingContext2D | null>(null);
+  const frameCountRef = useRef(0);
+  const bytesRef = useRef(0);
+  const statsTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const deadlineRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const generationRef = useRef(0);
+  // A ref, so a new callback each render does not make `start` a new function.
+  const onFailureRef = useRef(onFailure);
+  onFailureRef.current = onFailure;
+
+  const teardown = useCallback(() => {
+    generationRef.current += 1;
+    if (statsTimerRef.current) { clearInterval(statsTimerRef.current); statsTimerRef.current = null; }
+    if (deadlineRef.current) { clearTimeout(deadlineRef.current); deadlineRef.current = null; }
+    try { pcRef.current?.close(); } catch { /* already closed */ }
+    pcRef.current = null;
+    const video = videoRef.current;
+    if (video) {
+      video.srcObject = null;
+      video.remove();
+      videoRef.current = null;
+    }
+    ctxRef.current = null;
+  }, []);
+
+  const stop = useCallback(() => {
+    teardown();
+    setStatus("idle");
+    setErrorMessage(null);
+  }, [teardown]);
+
+  const start = useCallback((whepPath: string) => {
+    teardown();
+    const generation = generationRef.current;
+    const stale = () => generation !== generationRef.current;
+    let failed = false;
+    const fail = (message: string, kind: DecoderStatus = "error") => {
+      if (stale() || failed) return;
+      failed = true;
+      setStatus(kind);
+      setErrorMessage(message);
+      onFailureRef.current?.();
+    };
+
+    if (typeof RTCPeerConnection === "undefined") {
+      fail("This browser has no WebRTC support.", "unsupported");
+      return;
+    }
+
+    // Hidden, but attached: a detached element is not guaranteed to run
+    // `requestVideoFrameCallback`, and `display:none` lets a browser stop decoding entirely.
+    const video = document.createElement("video");
+    video.autoplay = true;
+    video.muted = true;               // host audio has its own path; a muted element may autoplay
+    video.playsInline = true;
+    video.setAttribute("aria-hidden", "true");
+    video.style.cssText =
+      "position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none";
+    document.body.appendChild(video);
+    videoRef.current = video;
+
+    const paint = () => {
+      if (stale()) return;
+      const canvas = canvasRef.current;
+      if (canvas && video.videoWidth > 0) {
+        if (canvas.width !== video.videoWidth || canvas.height !== video.videoHeight) {
+          canvas.width = video.videoWidth;
+          canvas.height = video.videoHeight;
+          // Inside the size guard: one setState per resolution change, not per frame.
+          setFrameSize({ width: video.videoWidth, height: video.videoHeight });
+        }
+        if (!ctxRef.current) ctxRef.current = canvas.getContext("2d");
+        ctxRef.current?.drawImage(video, 0, 0, canvas.width, canvas.height);
+        frameCountRef.current += 1;
+      }
+      schedule();
+    };
+    // `requestVideoFrameCallback` fires once per *decoded* frame, so the canvas never repaints
+    // a picture that has not changed. rAF is the fallback for browsers without it and repaints
+    // at display rate instead, which is wasteful but correct.
+    const schedule = () =>
+      typeof video.requestVideoFrameCallback === "function"
+        ? video.requestVideoFrameCallback(() => paint())
+        : requestAnimationFrame(() => paint());
+
+    const pc = new RTCPeerConnection({ iceServers: [] });
+    pcRef.current = pc;
+    pc.addTransceiver("video", { direction: "recvonly" });
+    pc.ontrack = (e) => {
+      const stream = new MediaStream();
+      stream.addTrack(e.track);
+      video.srcObject = stream;
+      void video.play().catch(() => { /* autoplay is allowed for a muted element */ });
+      schedule();
+    };
+    pc.onconnectionstatechange = () => {
+      if (stale()) return;
+      if (pc.connectionState === "connected") {
+        if (deadlineRef.current) { clearTimeout(deadlineRef.current); deadlineRef.current = null; }
+        setStatus("ready");
+        setErrorMessage(null);
+      }
+      if (pc.connectionState === "failed") fail("The WebRTC connection failed.");
+    };
+
+    statsTimerRef.current = setInterval(async () => {
+      if (stale() || !pcRef.current) return;
+      try {
+        const report = await pcRef.current.getStats();
+        report.forEach((r: any) => {
+          if (r.type === "inbound-rtp" && r.kind === "video") bytesRef.current = r.bytesReceived ?? 0;
+        });
+      } catch { /* the connection is going away */ }
+    }, 1000);
+
+    void (async () => {
+      try {
+        await pc.setLocalDescription(await pc.createOffer());
+        await waitForIceGathering(pc);
+        if (stale()) return;
+
+        const token = getAuthToken();
+        const answer = await postOfferWithRetry(whepPath, pc.localDescription!.sdp, token, stale);
+        if (stale()) return;
+        if (!answer) {
+          fail("The host's WebRTC relay never produced a stream.");
+          return;
+        }
+        await pc.setRemoteDescription({ type: "answer", sdp: answer });
+        if (stale() || pc.connectionState === "connected") return;
+        deadlineRef.current = setTimeout(() => {
+          deadlineRef.current = null;
+          if (pc.connectionState !== "connected") fail("The WebRTC connection did not come up.");
+        }, CONNECT_DEADLINE_MS);
+      } catch (e) {
+        fail((e as Error).message);
+      }
+    })();
+  }, [canvasRef, teardown]);
+
+  return {
+    status, errorMessage, start, stop,
+    getFrameCount: () => frameCountRef.current,
+    getTotalBytes: () => bytesRef.current,
+    frameSize,
+  };
+}
+
+/** Resolve once the browser has gathered every candidate, so one POST carries them all. */
+function waitForIceGathering(pc: RTCPeerConnection): Promise<void> {
+  if (pc.iceGatheringState === "complete") return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      if (pc.iceGatheringState !== "complete") return;
+      pc.removeEventListener("icegatheringstatechange", done);
+      resolve();
+    };
+    pc.addEventListener("icegatheringstatechange", done);
+    // A candidate that never arrives must not hang the viewer; what has been gathered by then
+    // is enough on a LAN or a tailnet, where the host candidate is the one that wins anyway.
+    setTimeout(() => { pc.removeEventListener("icegatheringstatechange", done); resolve(); }, 2000);
+  });
+}
+
+/** POST the offer, retrying while the relay has no publisher yet. Returns the SDP answer. */
+async function postOfferWithRetry(
+  whepPath: string, offer: string, token: string | null, stale: () => boolean,
+): Promise<string | null> {
+  for (let attempt = 0; attempt < WHEP_RETRY_LIMIT; attempt++) {
+    if (stale()) return null;
+    const res = await fetch(whepPath, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/sdp",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        "x-ppm-client": "web",
+      },
+      body: offer,
+    });
+    if (res.ok) return await res.text();
+    // 404 is "the stream is not up yet" and is the expected answer for the first few hundred
+    // milliseconds. Anything else is a real refusal — auth, a dead ticket — and retrying it
+    // would just hide the reason.
+    if (res.status !== 404 && res.status !== 502) {
+      throw new Error(`the host refused the WebRTC handshake (${res.status})`);
+    }
+    await new Promise((r) => setTimeout(r, WHEP_RETRY_MS));
+  }
+  return null;
+}

package/src/web/components/root-error-boundary.tsx

@@ -16,6 +16,7 @@
  */
 import { Component, type ErrorInfo, type ReactNode } from "react";
 import { isChunkLoadError, purgeAndReload } from "@/lib/chunk-recovery";
+import { reportTraceError } from "@/lib/trace-client";
 
 interface Props {
   children: ReactNode;
@@ -84,6 +85,10 @@ export class RootErrorBoundary extends Component<Props, State> {
   }
 
   override componentDidCatch(error: Error, info: ErrorInfo) {
+    // To the server too: this screen is usually seen on a device with no devtools open.
+    reportTraceError(isChunkLoadError(error) ? "chunk_error" : "render_error", error, {
+      componentStack: info.componentStack ?? undefined,
+    });
     console.error("[ppm] unhandled render error", error, info.componentStack);
   }
 

package/src/web/components/settings/remote-desktop-settings-section.tsx

@@ -0,0 +1,176 @@
+/**
+ * Remote Desktop settings: the WebRTC relay, which is an optional download.
+ *
+ * Without it the viewer streams H.264 over the WebSocket and decodes with WebCodecs, which
+ * works — except that `VideoDecoder` is secure-context only, so on a plain-HTTP LAN origin
+ * (how a phone or tablet usually reaches PPM) it cannot start at all. With the relay installed
+ * the host serves WebRTC instead, which has no such restriction. Nothing else changes: the
+ * relay repackages the stream ffmpeg already encoded and never re-encodes it.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+import { Monitor, Loader2, Download, Trash2, Check } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { Separator } from "@/components/ui/separator";
+import { api } from "@/lib/api-client";
+
+interface RelayJob {
+  receivedBytes: number;
+  totalBytes: number;
+  done: boolean;
+  error: string | null;
+}
+
+interface RelayStatus {
+  installed: boolean;
+  path?: string;
+  source?: "bundled" | "system";
+  pinnedVersion: string;
+  /** False when the release publishes no build for this platform/architecture. */
+  available: boolean;
+  job: RelayJob | null;
+}
+
+const mb = (bytes: number) => `${Math.round(bytes / 1e6)} MB`;
+
+export function RemoteDesktopSettingsSection() {
+  const [status, setStatus] = useState<RelayStatus | null>(null);
+  const [busy, setBusy] = useState(false);
+  const pollRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setStatus(await api.get<RelayStatus>("/api/remote-desktop/relay"));
+    } catch {
+      // A status that cannot be read leaves the pane on "not installed", which is the thing
+      // the user can act on anyway.
+    }
+  }, []);
+
+  useEffect(() => { void load(); }, [load]);
+
+  // Poll only while a download is running: the byte count is the only sign of progress.
+  const installing = !!status?.job && !status.job.done;
+  useEffect(() => {
+    if (!installing) return;
+    pollRef.current = setTimeout(() => void load(), 700);
+    return () => { if (pollRef.current) clearTimeout(pollRef.current); };
+  }, [installing, status, load]);
+
+  const install = async () => {
+    setBusy(true);
+    try {
+      await api.post("/api/remote-desktop/relay/install");
+      await load();
+    } catch (e) {
+      toast.error("Could not start the download", {
+        description: e instanceof Error ? e.message : String(e),
+      });
+    } finally { setBusy(false); }
+  };
+
+  const uninstall = async () => {
+    setBusy(true);
+    try {
+      await api.post("/api/remote-desktop/relay/uninstall");
+      await load();
+    } catch (e) {
+      toast.error("Could not remove the relay", {
+        description: e instanceof Error ? e.message : String(e),
+      });
+    } finally { setBusy(false); }
+  };
+
+  const job = status?.job ?? null;
+  const percent = job && job.totalBytes > 0
+    ? Math.round((job.receivedBytes / job.totalBytes) * 100)
+    : null;
+  const insecure = typeof window !== "undefined" && !window.isSecureContext;
+
+  return (
+    <div className="space-y-6">
+      <section className="space-y-3">
+        <div>
+          <h3 className="text-sm font-medium">WebRTC relay</h3>
+          <p className="text-xs text-muted-foreground leading-relaxed">
+            Streams the desktop over WebRTC instead of a WebSocket. It repackages the video this
+            host already encoded — it never re-encodes, so the picture and the CPU cost are
+            unchanged.
+          </p>
+        </div>
+
+        {insecure && (
+          // The reason most people will end up on this pane, so it says so plainly rather than
+          // leaving them to discover it as a broken viewer.
+          <p className="rounded-md bg-muted px-4 py-3 text-xs leading-relaxed">
+            You are reading this over plain HTTP. Browsers only expose the WebCodecs video
+            decoder on HTTPS or localhost, so <strong>Remote Desktop cannot show a picture on
+            this address</strong> without the relay. Installing it fixes that; so does reaching
+            PPM through its HTTPS tunnel.
+          </p>
+        )}
+
+        {!status?.available && !status?.installed && (
+          <p className="text-xs text-muted-foreground leading-relaxed">
+            MediaMTX publishes no build for this platform. You can install it yourself and put
+            <code className="mx-1 rounded bg-muted px-1 py-0.5">mediamtx</code>
+            on this host's PATH — PPM generates its own configuration either way.
+          </p>
+        )}
+
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center">
+          <div className="flex items-center gap-2 text-sm">
+            {status?.installed
+              ? <Check className="size-4 text-emerald-500" />
+              : <Monitor className="size-4 text-muted-foreground" />}
+            <span>
+              {status?.installed
+                ? status.source === "system"
+                  ? "Installed on this host (not by PPM)"
+                  : `Installed — MediaMTX ${status.pinnedVersion}`
+                : "Not installed"}
+            </span>
+          </div>
+
+          <div className="flex flex-wrap gap-2 sm:ml-auto">
+            {!status?.installed && status?.available && (
+              <Button onClick={install} disabled={busy || installing} className="min-h-11 px-4">
+                {installing
+                  ? <><Loader2 className="size-4 animate-spin" />Downloading{percent !== null ? ` ${percent}%` : ""}</>
+                  : <><Download className="size-4" />Install</>}
+              </Button>
+            )}
+            {status?.installed && status.source === "bundled" && (
+              <Button variant="outline" onClick={uninstall} disabled={busy || installing} className="min-h-11 px-4">
+                <Trash2 className="size-4" />Remove
+              </Button>
+            )}
+          </div>
+        </div>
+
+        {installing && job && (
+          <p className="text-xs text-muted-foreground">
+            {mb(job.receivedBytes)}{job.totalBytes > 0 ? ` of ${mb(job.totalBytes)}` : ""}
+          </p>
+        )}
+        {job?.error && <p className="text-xs text-destructive">{job.error}</p>}
+        {status?.path && (
+          <p className="text-xs text-muted-foreground break-all">{status.path}</p>
+        )}
+      </section>
+
+      <Separator />
+
+      <section className="space-y-2">
+        <h3 className="text-sm font-medium">What changes when it is on</h3>
+        <ul className="list-disc space-y-1 pl-5 text-xs text-muted-foreground leading-relaxed">
+          <li>The picture works on a plain-HTTP LAN address, not only over HTTPS or localhost.</li>
+          <li>A lost packet costs one retransmission instead of stalling the whole stream.</li>
+          <li>Keyboard, mouse, clipboard and host audio keep using the same WebSocket.</li>
+          <li>Video leaves this host on its own UDP port, protected by per-session credentials.</li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/src/web/components/settings/settings-categories.ts

@@ -23,6 +23,7 @@ import {
   LayoutGrid,
   Mic,
   Zap,
+  Monitor,
 } from "@/lib/icons";
 
 /**
@@ -35,6 +36,7 @@ export type SettingsCategoryId =
   | "general"
   | "appearance"
   | "language-servers"
+  | "remote-desktop"
   | "ai-provider"
   | "accounts"
   | "design"
@@ -81,6 +83,7 @@ export const SETTINGS_CATEGORIES: SettingsCategoryDef[] = [
   { id: "general", group: "core", label: "General", subtitle: "Device name, password, version", icon: Settings2 },
   { id: "appearance", group: "core", label: "Appearance", subtitle: "Theme, tabs, explorer skin", icon: Palette },
   { id: "language-servers", group: "core", label: "Language Servers", subtitle: "Completions and go to definition, per language", icon: Zap },
+  { id: "remote-desktop", group: "core", label: "Remote Desktop", subtitle: "WebRTC relay for streaming this host's screen", icon: Monitor },
 
   { id: "ai-provider", group: "ai", label: "AI Provider", subtitle: "Model, execution mode, limits", icon: Bot },
   { id: "accounts", group: "ai", label: "Accounts", subtitle: "Claude and Codex sign-ins, rotation", icon: KeyRound },

package/src/web/components/settings/settings-section-content.tsx

@@ -7,29 +7,36 @@
  * does not pull every pane's dependencies (charts, editors, cron pickers) into the bundle.
  */
 
-import { Suspense, lazy, type ComponentType, type LazyExoticComponent } from "react";
+import { Suspense } from "react";
+import { lazyWithPreload, type PreloadableComponent } from "@/lib/lazy-with-preload";
 import { Loader2 } from "@/lib/icons";
 import type { SettingsCategoryId } from "./settings-categories";
 
-const SECTIONS: Record<SettingsCategoryId, LazyExoticComponent<ComponentType>> = {
-  general: lazy(() => import("./general-settings-section").then((m) => ({ default: m.GeneralSettingsSection }))),
-  appearance: lazy(() => import("./appearance-settings-section").then((m) => ({ default: m.AppearanceSettingsSection }))),
-  "language-servers": lazy(() => import("./language-servers-section").then((m) => ({ default: m.LanguageServersSection }))),
-  "ai-provider": lazy(() => import("./ai-settings-section").then((m) => ({ default: m.AISettingsSection }))),
-  accounts: lazy(() => import("./accounts/accounts-settings-section").then((m) => ({ default: m.AccountsSettingsSection }))),
-  design: lazy(() => import("./design-settings-section").then((m) => ({ default: m.DesignSettingsSection }))),
-  voice: lazy(() => import("./voice-settings-section").then((m) => ({ default: m.VoiceSettingsSection }))),
-  ppmbot: lazy(() => import("./ppmbot-settings-section").then((m) => ({ default: m.PPMBotSettingsSection }))),
-  notifications: lazy(() => import("./notifications-settings-section").then((m) => ({ default: m.NotificationsSettingsSection }))),
-  jira: lazy(() => import("./jira-watcher-section").then((m) => ({ default: m.JiraWatcherSection }))),
-  extensions: lazy(() => import("./extension-manager-section").then((m) => ({ default: m.ExtensionManagerSection }))),
-  proxy: lazy(() => import("./proxy-settings-section").then((m) => ({ default: m.ProxySettingsSection }))),
-  schedules: lazy(() => import("./schedules/schedules-settings-section").then((m) => ({ default: m.SchedulesSettingsSection }))),
-  shortcuts: lazy(() => import("./keyboard-shortcuts-section").then((m) => ({ default: m.KeyboardShortcutsSection }))),
-  files: lazy(() => import("./files-settings-section").then((m) => ({ default: m.FilesSettingsSection }))),
-  "query-audit": lazy(() => import("./query-audit-section").then((m) => ({ default: m.QueryAuditSection }))),
+export const SECTIONS: Record<SettingsCategoryId, PreloadableComponent<object>> = {
+  general: lazyWithPreload(() => import("./general-settings-section").then((m) => ({ default: m.GeneralSettingsSection }))),
+  appearance: lazyWithPreload(() => import("./appearance-settings-section").then((m) => ({ default: m.AppearanceSettingsSection }))),
+  "language-servers": lazyWithPreload(() => import("./language-servers-section").then((m) => ({ default: m.LanguageServersSection }))),
+  "remote-desktop": lazyWithPreload(() => import("./remote-desktop-settings-section").then((m) => ({ default: m.RemoteDesktopSettingsSection }))),
+  "ai-provider": lazyWithPreload(() => import("./ai-settings-section").then((m) => ({ default: m.AISettingsSection }))),
+  accounts: lazyWithPreload(() => import("./accounts/accounts-settings-section").then((m) => ({ default: m.AccountsSettingsSection }))),
+  design: lazyWithPreload(() => import("./design-settings-section").then((m) => ({ default: m.DesignSettingsSection }))),
+  voice: lazyWithPreload(() => import("./voice-settings-section").then((m) => ({ default: m.VoiceSettingsSection }))),
+  ppmbot: lazyWithPreload(() => import("./ppmbot-settings-section").then((m) => ({ default: m.PPMBotSettingsSection }))),
+  notifications: lazyWithPreload(() => import("./notifications-settings-section").then((m) => ({ default: m.NotificationsSettingsSection }))),
+  jira: lazyWithPreload(() => import("./jira-watcher-section").then((m) => ({ default: m.JiraWatcherSection }))),
+  extensions: lazyWithPreload(() => import("./extension-manager-section").then((m) => ({ default: m.ExtensionManagerSection }))),
+  proxy: lazyWithPreload(() => import("./proxy-settings-section").then((m) => ({ default: m.ProxySettingsSection }))),
+  schedules: lazyWithPreload(() => import("./schedules/schedules-settings-section").then((m) => ({ default: m.SchedulesSettingsSection }))),
+  shortcuts: lazyWithPreload(() => import("./keyboard-shortcuts-section").then((m) => ({ default: m.KeyboardShortcutsSection }))),
+  files: lazyWithPreload(() => import("./files-settings-section").then((m) => ({ default: m.FilesSettingsSection }))),
+  "query-audit": lazyWithPreload(() => import("./query-audit-section").then((m) => ({ default: m.QueryAuditSection }))),
 };
 
+/** Load every pane's code, so that opening Settings shows its pane without a spinner. */
+export function preloadSettingsSections(): Promise<unknown> {
+  return Promise.all(Object.values(SECTIONS).map((section) => section.preload()));
+}
+
 export function SettingsSectionContent({ category }: { category: SettingsCategoryId }) {
   const Section = SECTIONS[category];
   return (

package/src/web/hooks/use-chat-prewarm.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useRef } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import type { TurnSettings } from "@/hooks/use-chat";
+
+/** How long the picks must hold still before asking, so a tab passed through asks nothing. */
+const SETTLE_MS = 300;
+/** Asked again at most this often while the user types; the server keeps a process 5 min. */
+const REASK_MS = 60_000;
+
+export interface ChatPrewarmInput {
+  /** A new chat is open and on screen: no session yet, not a design tab. */
+  enabled: boolean;
+  projectName: string;
+  providerId: string;
+  permissionMode?: string;
+  /** The account the tab claimed, which the session will be created on. */
+  accountId?: string;
+  /** What the first message will carry — `useChat().turnSettings()`. */
+  picks: TurnSettings;
+}
+
+/**
+ * Has the server start the Claude process a new chat's first message will run on while
+ * that message is still being written, so sending it does not wait ~1.4 s for the CLI to
+ * boot (`src/providers/claude-warm-spare.ts` has the numbers).
+ *
+ * Asks when the composer opens and whenever a pick changes — the process only serves a
+ * message that carries the picks it was started with. Returns `touch`, for the composer to
+ * call as the user types: it asks again at most once a minute, which keeps the process
+ * alive while someone is writing and lets it go when they walk away.
+ */
+export function useChatPrewarm(input: ChatPrewarmInput): () => void {
+  const { enabled, projectName, providerId, permissionMode, accountId, picks } = input;
+  const lastAskAt = useRef(0);
+  const ask = useRef(() => {});
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+  ask.current = () => {
+    lastAskAt.current = Date.now();
+    void api.post(`${projectUrl(projectName)}/chat/prewarm`, { providerId, permissionMode, accountId, ...picks }).catch(() => {});
+  };
+
+  const key = JSON.stringify([projectName, providerId, permissionMode ?? null, accountId ?? null, picks]);
+  useEffect(() => {
+    if (!enabled) return;
+    const timer = setTimeout(() => ask.current(), SETTLE_MS);
+    return () => clearTimeout(timer);
+  }, [enabled, key]);
+
+  return useCallback(() => {
+    if (enabledRef.current && Date.now() - lastAskAt.current >= REASK_MS) ask.current();
+  }, []);
+}

package/src/web/hooks/use-chat.ts

@@ -54,6 +54,13 @@ export interface BashPartialEntry {
   lineCount: number;
 }
 
+/** The per-session picks a message carries; a pick the user never made is left out. */
+export interface TurnSettings {
+  model?: string;
+  effort?: string;
+  thinking?: boolean;
+}
+
 interface UseChatReturn {
   messages: ChatMessage[];
   /** Messages flattened with pre-compact expansions prepended before their compact cards. */
@@ -102,6 +109,8 @@ interface UseChatReturn {
   thinking: boolean;
   /** Toggle per-session thinking on/off */
   setThinking: (enabled: boolean) => void;
+  /** The picks the next message carries, exactly as `sendMessage` attaches them. */
+  turnSettings: () => TurnSettings;
   /** Team activity state from WS events */
   teamActivity: TeamActivityState;
   /** All team messages (ref-backed, updated live) */
@@ -1296,6 +1305,12 @@ export function useChat(
     };
   }, [sessionId, providerId, projectName, updateTeamActivity, loadTeamDetail]);
 
+  const turnSettings = useCallback((): TurnSettings => ({
+    ...(modelRef.current && { model: modelRef.current }),
+    ...(effortRef.current && { effort: effortRef.current }),
+    ...(thinkingRef.current !== null && { thinking: thinkingRef.current }),
+  }), []);
+
   const sendMessage = useCallback(
     (content: string, opts?: { permissionMode?: string; priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }>; imagePaths?: string[] }) => {
       // An attachment-only message is legitimate now that images travel with it: the
@@ -1357,12 +1372,10 @@ export function useChat(
         priority: opts?.priority,
         images: opts?.images,
         imagePaths: opts?.imagePaths,
-        ...(modelRef.current && { model: modelRef.current }),
-        ...(effortRef.current && { effort: effortRef.current }),
-        ...(thinkingRef.current !== null && { thinking: thinkingRef.current }),
+        ...turnSettings(),
       }));
     },
-    [send, isConnected, connectedSessionId],
+    [send, isConnected, connectedSessionId, turnSettings],
   );
 
   const setModel = useCallback(
@@ -1602,6 +1615,7 @@ export function useChat(
     setEffort,
     thinking,
     setThinking,
+    turnSettings,
     teamActivity,
     teamMessages,
     markTeamRead,