serve-sim 0.1.43 → 0.1.44-beta.91.2

package/src/middleware.ts

@@ -3,8 +3,14 @@ import { execSync, spawn, exec, execFile, type ChildProcess, type ExecException
 import { tmpdir } from "os";
 import { join } from "path";
 import { createServer as createNetServer } from "net";
-import { randomBytes, timingSafeEqual } from "crypto";
-import type { IncomingMessage, ServerResponse } from "http";
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+import { request as httpRequest, type IncomingMessage, type ServerResponse } from "http";
+import type { Socket } from "net";
+// `ws` (kept external in the build) supplies a WebSocket *client* for the
+// helper/devtools proxy. Node only exposes a global `WebSocket` on newer LTS
+// lines, and `serve-sim/middleware` is embedded in third-party dev servers, so
+// importing the dependency keeps the proxy working regardless of runtime.
+import { WebSocket } from "ws";
 import { createAxStreamerCache } from "./ax";
 import { debugMw } from "./debug";
 import {
@@ -19,6 +25,10 @@ import { UI_OPTIONS, getUiStatus, normalizeUiValue, setUiOption } from "./ui-set
 type SimReq = IncomingMessage;
 type SimRes = ServerResponse;
 type SimNext = (err?: unknown) => void;
+export type SimMiddleware = {
+  (req: SimReq, res: SimRes, next?: SimNext): void;
+  handleUpgrade(req: SimReq, socket: Socket, head: Buffer): void;
+};
 
 // Injected at build time as a base64-encoded string via `define`
 declare const __PREVIEW_HTML_B64__: string;
@@ -41,7 +51,7 @@ type WebKitBridgeTarget = {
   inUseByOtherInspector?: boolean;
 };
 
-type WebKitBridge = {
+export type WebKitBridge = {
   port: number;
   cdpUrl: string;
   listTargets(): Promise<WebKitBridgeTarget[]>;
@@ -126,6 +136,10 @@ function isUserFacingBundle(bundleId: string): boolean {
   return !NON_UI_BUNDLE_RE.test(bundleId);
 }
 
+function isSimulatorUdid(value: string): boolean {
+  return /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i.test(value);
+}
+
 export function parseForegroundAppLogMessage(message: string): { bundleId: string; pid: number } | null {
   // e.g. "[app<com.apple.mobilesafari>:43117] Setting process visibility to: Foreground"
   const match = /\[app<([^>]+)>:(\d+)\] Setting process visibility to: Foreground/.exec(message);
@@ -259,7 +273,7 @@ export function readServeSimStates(): ServeSimState[] {
       // would accept connections yet never produce frames, leaving the
       // preview stuck on "Connecting...". Recycle the stale state so the
       // caller can spawn a fresh helper bound to whatever is booted.
-      if (booted && !booted.has(state.device)) {
+      if (booted && isSimulatorUdid(state.device) && !booted.has(state.device)) {
         debugMw(
           "recycling stale helper pid=%d (device %s no longer booted)",
           state.pid,
@@ -291,41 +305,316 @@ function queryDevice(rawUrl: string): string | null {
   return new URLSearchParams(rawUrl.slice(qIndex + 1)).get("device");
 }
 
+function hostForRequest(req: SimReq): string | undefined {
+  const host = req.headers?.host;
+  if (host) return host;
+  const port = req.socket.localPort;
+  return port ? `localhost:${port}` : undefined;
+}
+
 function endpoint(base: string, path: string, device: string): string {
   const value = `${base}${path}`;
   return `${value}?device=${encodeURIComponent(device)}`;
 }
 
 /**
- * Rewrite the helper URLs in a state so they point at the hostname the request
- * came in on. The helper binds on `*:<port>`, so once the host portion matches
- * the dev-server origin, a remote viewer (LAN, or tunnel exposing the helper
- * port under the same hostname) can reach the stream. Loopback callers get
- * the state untouched.
+ * Rewrite the helper URLs in a state for the requesting browser.
+ *
+ * When `proxy` is set (standalone `serve-sim`, which owns its server and wires
+ * WebSocket upgrades), the URLs point at the preview's same-origin `/helper`
+ * proxy so remote viewers only need the one preview port. When it's off — the
+ * default for embedded `app.use(simMiddleware(...))` mounts, where the host's
+ * server doesn't forward `upgrade` events to `handleUpgrade` — the helper's
+ * loopback URLs are emitted directly (with `127.0.0.1` swapped for the request
+ * hostname so LAN/tunnel viewers can still reach the separate helper port).
  */
 export function rewriteStateForRequestHost(
   state: ServeSimState,
   hostHeader: string | undefined,
+  base = "",
+  protocol: "http" | "https" = "http",
+  proxy = false,
 ): ServeSimState {
-  if (!hostHeader) return state;
-  let hostname: string;
-  try {
-    hostname = new URL(`http://${hostHeader}`).hostname;
-  } catch {
+  if (!hostHeader) {
     return state;
   }
-  // `URL.hostname` keeps brackets around IPv6 literals, so the IPv6 loopback
-  // comparison is against the bracketed form rather than `::1`.
-  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]") {
-    return state;
+  if (!proxy) {
+    let hostname: string;
+    try {
+      hostname = new URL(`http://${hostHeader}`).hostname;
+    } catch {
+      return state;
+    }
+    // `URL.hostname` keeps brackets around IPv6 literals, so the IPv6 loopback
+    // comparison is against the bracketed form rather than `::1`.
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]") {
+      return state;
+    }
+    const rewrite = (s: string) => s.replace("127.0.0.1", hostname);
+    return {
+      ...state,
+      url: rewrite(state.url),
+      streamUrl: rewrite(state.streamUrl),
+      wsUrl: rewrite(state.wsUrl),
+    };
   }
-  const rewrite = (s: string) => s.replace("127.0.0.1", hostname);
+  const normalizedBase = base === "/" ? "" : base.replace(/\/+$/, "");
+  const helperBase = `${normalizedBase}/helper`;
+  const devicePath = `${helperBase}/${encodeURIComponent(state.device)}`;
+  // Match the request's scheme so an HTTPS-served preview doesn't hand the
+  // browser `http`/`ws` helper URLs (blocked as mixed content). Behind a proxy
+  // the original scheme arrives via `x-forwarded-proto`.
+  const origin = `${protocol}://${hostHeader}`;
+  const wsOrigin = `${protocol === "https" ? "wss" : "ws"}://${hostHeader}`;
   return {
     ...state,
-    url: rewrite(state.url),
-    streamUrl: rewrite(state.streamUrl),
-    wsUrl: rewrite(state.wsUrl),
+    url: `${origin}${devicePath}`,
+    streamUrl: `${origin}${devicePath}/stream.mjpeg`,
+    wsUrl: `${wsOrigin}${devicePath}/ws`,
+  };
+}
+
+function helperProxyPrefix(base: string): string {
+  return `${base === "/" ? "" : base}/helper`;
+}
+
+function devtoolsProxyPrefix(base: string): string {
+  return `${base === "/" ? "" : base}/devtools`;
+}
+
+function devtoolsProxyTarget(rawUrl: string, prefix: string): { upstreamPath: string } | null {
+  const parsed = new URL(rawUrl, "http://serve-sim.local");
+  if (!parsed.pathname.startsWith(`${prefix}/page/`)) {
+    return null;
+  }
+  const suffix = parsed.pathname.slice(prefix.length);
+  return { upstreamPath: `/devtools${suffix}${parsed.search}` };
+}
+
+function helperProxyTarget(rawUrl: string, prefix: string): { device: string | null; upstreamPath: string } | null {
+  const parsed = new URL(rawUrl, "http://serve-sim.local");
+  if (parsed.pathname !== prefix && !parsed.pathname.startsWith(`${prefix}/`)) {
+    return null;
+  }
+  const rawSuffix = parsed.pathname.slice(prefix.length);
+  const segments = rawSuffix.replace(/^\/+/, "").split("/").filter(Boolean);
+  const directHelperEndpoints = new Set([
+    "ax",
+    "config",
+    "foreground",
+    "health",
+    "stream.avcc",
+    "stream.mjpeg",
+    "ws",
+  ]);
+  let device = parsed.searchParams.get("device");
+  let upstreamSegments = segments;
+  if (segments[0] && !directHelperEndpoints.has(segments[0])) {
+    device = decodeURIComponent(segments[0]);
+    upstreamSegments = segments.slice(1);
+  }
+  const suffix = upstreamSegments.length > 0 ? `/${upstreamSegments.join("/")}` : "/";
+  parsed.searchParams.delete("device");
+  return { device, upstreamPath: `${suffix}${parsed.search}` };
+}
+
+function proxyHelperHttp(req: SimReq, res: SimRes, state: ServeSimState, upstreamPath: string): void {
+  const proxyReq = httpRequest(
+    {
+      host: "127.0.0.1",
+      port: state.port,
+      method: req.method,
+      path: upstreamPath,
+      headers: {
+        ...req.headers,
+        host: `127.0.0.1:${state.port}`,
+      },
+    },
+    (proxyRes) => {
+      res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("error", (err) => {
+    if (res.headersSent) {
+      res.destroy(err);
+      return;
+    }
+    res.writeHead(502, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end(err instanceof Error ? err.message : "Helper proxy failed");
+  });
+  req.pipe(proxyReq);
+}
+
+const WS_ACCEPT_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+function websocketFrame(opcode: number, payload: Buffer<ArrayBufferLike>): Buffer {
+  const length = payload.length;
+  let header: Buffer;
+  if (length < 126) {
+    header = Buffer.from([0x80 | opcode, length]);
+  } else if (length <= 0xffff) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(length, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(length), 2);
+  }
+  return Buffer.concat([header, payload]);
+}
+
+type ParsedWebSocketFrame = {
+  opcode: number;
+  payload: Buffer<ArrayBufferLike>;
+  consumed: number;
+};
+
+function parseWebSocketFrame(buffer: Buffer): ParsedWebSocketFrame | null {
+  if (buffer.length < 2) return null;
+  const opcode = buffer[0]! & 0x0f;
+  const masked = (buffer[1]! & 0x80) !== 0;
+  let length = buffer[1]! & 0x7f;
+  let offset = 2;
+  if (length === 126) {
+    if (buffer.length < offset + 2) return null;
+    length = buffer.readUInt16BE(offset);
+    offset += 2;
+  } else if (length === 127) {
+    if (buffer.length < offset + 8) return null;
+    const bigLength = buffer.readBigUInt64BE(offset);
+    if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error("WebSocket frame too large");
+    }
+    length = Number(bigLength);
+    offset += 8;
+  }
+  const maskOffset = offset;
+  if (masked) offset += 4;
+  if (buffer.length < offset + length) return null;
+  const payload = Buffer.from(buffer.subarray(offset, offset + length));
+  if (masked) {
+    const mask = buffer.subarray(maskOffset, maskOffset + 4);
+    for (let i = 0; i < payload.length; i++) {
+      payload[i] = payload[i]! ^ mask[i % 4]!;
+    }
+  }
+  return { opcode, payload, consumed: offset + length };
+}
+
+function sendBrowserFrame(socket: Socket, opcode: number, payload: Buffer<ArrayBufferLike> = Buffer.alloc(0)): void {
+  if (socket.destroyed || !socket.writable) return;
+  socket.write(websocketFrame(opcode, payload));
+}
+
+type PendingWebSocketFrame = {
+  opcode: number;
+  payload: Buffer<ArrayBufferLike>;
+};
+
+function webSocketBinary(payload: Buffer<ArrayBufferLike>): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(payload.length);
+  bytes.set(payload);
+  return bytes;
+}
+
+function bridgeWebSocketFrames(req: SimReq, socket: Socket, head: Buffer, upstreamUrl: string): void {
+  const key = req.headers["sec-websocket-key"];
+  if (typeof key !== "string") {
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+    return;
+  }
+  const accept = createHash("sha1")
+    .update(key + WS_ACCEPT_GUID)
+    .digest("base64");
+  socket.write(
+    "HTTP/1.1 101 Switching Protocols\r\n" +
+    "Upgrade: websocket\r\n" +
+    "Connection: Upgrade\r\n" +
+    `Sec-WebSocket-Accept: ${accept}\r\n` +
+    "\r\n",
+  );
+  socket.resume();
+
+  const upstream = new WebSocket(upstreamUrl);
+  upstream.binaryType = "arraybuffer";
+  let upstreamOpen = false;
+  let closed = false;
+  let pendingToUpstream: PendingWebSocketFrame[] = [];
+  let buffered = Buffer.from(head);
+
+  const closeBoth = () => {
+    if (closed) return;
+    closed = true;
+    try { upstream.close(); } catch {}
+    try { socket.end(websocketFrame(0x8, Buffer.alloc(0))); } catch {}
+    try { socket.destroy(); } catch {}
+  };
+
+  const sendToUpstream = (frame: PendingWebSocketFrame) => {
+    if (upstreamOpen && upstream.readyState === WebSocket.OPEN) {
+      upstream.send(frame.opcode === 0x1 ? frame.payload.toString("utf8") : webSocketBinary(frame.payload));
+      return;
+    }
+    pendingToUpstream.push({ opcode: frame.opcode, payload: Buffer.from(frame.payload) });
   };
+
+  const drainFrames = () => {
+    try {
+      while (buffered.length > 0) {
+        const frame = parseWebSocketFrame(buffered);
+        if (!frame) break;
+        buffered = buffered.subarray(frame.consumed);
+        if (frame.opcode === 0x8) {
+          sendBrowserFrame(socket, 0x8, frame.payload);
+          closeBoth();
+          return;
+        }
+        if (frame.opcode === 0x9) {
+          sendBrowserFrame(socket, 0xA, frame.payload);
+          continue;
+        }
+        if (frame.opcode === 0x1 || frame.opcode === 0x2) {
+          sendToUpstream({ opcode: frame.opcode, payload: frame.payload });
+        }
+      }
+    } catch {
+      closeBoth();
+    }
+  };
+
+  upstream.onopen = () => {
+    upstreamOpen = true;
+    for (const frame of pendingToUpstream) {
+      upstream.send(frame.opcode === 0x1 ? frame.payload.toString("utf8") : webSocketBinary(frame.payload));
+    }
+    pendingToUpstream = [];
+  };
+  upstream.onmessage = (event) => {
+    const data = event.data;
+    const payload = typeof data === "string"
+      ? Buffer.from(data)
+      : Buffer.from(data as ArrayBuffer);
+    sendBrowserFrame(socket, typeof data === "string" ? 0x1 : 0x2, payload);
+  };
+  upstream.onerror = closeBoth;
+  upstream.onclose = closeBoth;
+
+  socket.on("data", (chunk) => {
+    if (typeof chunk === "string") chunk = Buffer.from(chunk);
+    buffered = Buffer.concat([buffered, chunk]);
+    drainFrames();
+  });
+  socket.on("error", closeBoth);
+  socket.on("close", closeBoth);
+  drainFrames();
+}
+
+function bridgeHelperWebSocket(req: SimReq, socket: Socket, head: Buffer, state: ServeSimState): void {
+  bridgeWebSocketFrames(req, socket, head, state.wsUrl);
 }
 
 export function previewConfigForState(
@@ -333,6 +622,8 @@ export function previewConfigForState(
   base: string,
   serveSimBin: string,
   execToken: string,
+  codec?: string,
+  proxyHelpers = false,
 ): ServeSimState & {
   basePath: string;
   appStateEndpoint: string;
@@ -345,6 +636,8 @@ export function previewConfigForState(
   gridMemoryEndpoint: string;
   previewEndpoint: string;
   execToken: string;
+  codec?: string;
+  proxyHelpers?: boolean;
 } {
   const gridApiBase = (base === "" ? "" : base) + "/grid/api";
   return {
@@ -360,6 +653,8 @@ export function previewConfigForState(
     gridMemoryEndpoint: gridApiBase + "/memory",
     previewEndpoint: base === "" ? "/" : base,
     execToken,
+    ...(codec ? { codec } : {}),
+    ...(proxyHelpers ? { proxyHelpers: true } : {}),
   };
 }
 
@@ -430,10 +725,9 @@ async function ensureInspectWebKitBridge(): Promise<WebKitBridge> {
         continue;
       }
       try {
-        // Bind explicitly to IPv4 127.0.0.1 to match what bridgeWsHost emits
-        // (and what the DevTools frontend CSP whitelists). `localhost` resolves
-        // to ::1 first on some setups, which would leave the iframe's
-        // ws://127.0.0.1:9222 connection refused.
+        // Bind explicitly to IPv4 127.0.0.1 so the preview's DevTools
+        // websocket proxy has a stable loopback upstream. `localhost` resolves
+        // to ::1 first on some setups, which would leave the bridge unreachable.
         const server = await startCdpServer({ host: "127.0.0.1", port }) as Awaited<ReturnType<typeof startCdpServer>> & {
           highlightTarget?(targetId: string, on: boolean): Promise<void>;
           releaseHighlight?(targetId?: string): void;
@@ -478,22 +772,34 @@ async function ensureInspectWebKitBridge(): Promise<WebKitBridge> {
   return inspectWebKitBridge;
 }
 
-function devtoolsFrontendUrl(frontendBase: string, wsHost: string, targetId: string): string {
-  const url = new URL(`${frontendBase}/inspector.html`, "http://serve-sim.local");
-  url.searchParams.set("ws", `${wsHost}/devtools/page/${targetId}`);
-  return `${url.pathname}${url.search}`;
+function firstHeaderValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function forwardedProtoForRequest(req: SimReq): string | undefined {
+  return firstHeaderValue(req.headers["x-forwarded-proto"])
+    ?.split(",", 1)[0]
+    ?.trim()
+    .toLowerCase();
 }
 
-// The inspect-webkit bridge binds locally. Always emit `127.0.0.1` rather
-// than `localhost` for the iframe's WS URL: the chrome-devtools-frontend
-// inspector.html ships a CSP whose connect-src only whitelists
-// `ws://127.0.0.1:*` (plus `'self'`, which doesn't cover the bridge's
-// different port). A `ws://localhost:9222/...` connection from the iframe
-// gets CSP-blocked and surfaces as "WebSocket disconnected."
-// Non-local hostnames fall back to 127.0.0.1 since the bridge isn't
-// reachable from off-host anyway.
-function bridgeWsHost(_reqHost: string | undefined, bridgePort: number): string {
-  return `127.0.0.1:${bridgePort}`;
+function websocketProtocolForRequest(req: SimReq): "ws" | "wss" {
+  return forwardedProtoForRequest(req) === "https" ? "wss" : "ws";
+}
+
+function httpProtocolForRequest(req: SimReq): "http" | "https" {
+  return forwardedProtoForRequest(req) === "https" ? "https" : "http";
+}
+
+function devtoolsFrontendUrl(
+  frontendBase: string,
+  wsParamName: "ws" | "wss",
+  wsTargetBase: string,
+  targetId: string,
+): string {
+  const url = new URL(`${frontendBase}/inspector.html`, "http://serve-sim.local");
+  url.searchParams.set(wsParamName, `${wsTargetBase}/page/${encodeURIComponent(targetId)}`);
+  return `${url.pathname}${url.search}`;
 }
 
 let _html: string | null = null;
@@ -704,6 +1010,26 @@ export interface SimMiddlewareOptions {
    * cross-origin pages cannot read it.
    */
   execToken?: string;
+  /**
+   * Pin the preview stream codec. `"mjpeg"` forces the software JPEG path for
+   * hosts whose hardware can't encode H.264 (e.g. VMs without the high/low-
+   * latency H.264 profiles); `"auto"`/undefined lets the browser pick H.264.
+   * Reserved for future values such as `"hevc"`/`"av1"`.
+   */
+  codec?: string;
+  /**
+   * Route the browser's helper stream/control and DevTools sockets through the
+   * preview's same-origin `/helper` and `/devtools` proxies instead of the
+   * helper's own loopback port — so a single exposed preview port is enough for
+   * remote viewers. Requires the mounting server to forward WebSocket `upgrade`
+   * events to {@link SimMiddleware.handleUpgrade}. Standalone `serve-sim`
+   * enables this; plain `app.use(simMiddleware(...))` mounts leave it off (and
+   * keep direct helper URLs) unless they also wire upgrades. See the README's
+   * "Embed in your dev server" section.
+   */
+  proxyHelpers?: boolean;
+  /** Test hook for supplying a fake inspect-webkit bridge. */
+  inspectWebKitBridge?: () => Promise<WebKitBridge>;
 }
 
 function safeEqualString(a: string, b: string): boolean {
@@ -728,8 +1054,12 @@ function isJsonContentType(value: string | undefined): boolean {
  *   GET  {basePath}/api     — serve-sim state JSON
  *   GET  {basePath}/ax      — SSE stream of normalized accessibility snapshots
  */
-export function simMiddleware(options?: SimMiddlewareOptions) {
+export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
   const base = (options?.basePath ?? "/.sim").replace(/\/+$/, "");
+  const helperPrefix = helperProxyPrefix(base);
+  const devtoolsPrefix = devtoolsProxyPrefix(base);
+  const proxyHelpers = options?.proxyHelpers ?? false;
+  const getInspectWebKitBridge = options?.inspectWebKitBridge ?? ensureInspectWebKitBridge;
   // Per-process random token. Anyone who can read the preview HTML same-origin
   // can call /exec; cross-origin pages and LAN clients cannot, because they
   // can't read this value (it's only injected into the preview page's config).
@@ -753,13 +1083,26 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
     return { ok: true };
   };
 
-  const middleware = (req: SimReq, res: SimRes, next?: SimNext) => {
+  const middleware = ((req: SimReq, res: SimRes, next?: SimNext) => {
     const rawUrl: string = req.url ?? "";
     const qIndex = rawUrl.indexOf("?");
     const url = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
     const selectedDevice = queryDevice(rawUrl) ?? options?.device ?? null;
     const devtoolsFrontendBase = base === "/" ? "/devtools-frontend" : `${base}/devtools-frontend`;
 
+    const helperTarget = helperProxyTarget(rawUrl, helperPrefix);
+    if (helperTarget) {
+      const states = readServeSimStates();
+      const state = selectServeSimState(states, helperTarget.device ?? selectedDevice);
+      if (!state) {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("No serve-sim device");
+        return;
+      }
+      proxyHelperHttp(req, res, state, helperTarget.upstreamPath);
+      return;
+    }
+
     // Same-origin proxy for Chrome DevTools frontend assets. Loading the
     // appspot-hosted frontend directly works as a top-level tab, but is flaky
     // inside embedded browser iframes. Serving it from the preview origin keeps
@@ -812,8 +1155,8 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
       }
 
       if (state) {
-        const remoteState = rewriteStateForRequestHost(state, req.headers?.host);
-        const config = JSON.stringify(previewConfigForState(remoteState, base, serveSimBinPath(), execToken));
+        const remoteState = rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers);
+        const config = JSON.stringify(previewConfigForState(remoteState, base, serveSimBinPath(), execToken, options?.codec, proxyHelpers));
         const configScript = `<script>window.__SIM_PREVIEW__=${config}</script>`;
         html = html.replace("<!--__SIM_PREVIEW_CONFIG__-->", configScript);
       }
@@ -853,7 +1196,7 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
       const sims = listAllSimulators();
       const devices = sims.map((d) => {
         const helper = helperByUdid.get(d.udid);
-        const remoteHelper = helper ? rewriteStateForRequestHost(helper, req.headers?.host) : null;
+        const remoteHelper = helper ? rewriteStateForRequestHost(helper, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers) : null;
         return {
           device: d.udid,
           name: d.name,
@@ -1017,17 +1360,23 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
           return;
         }
         try {
-          const bridge = await ensureInspectWebKitBridge();
+          const bridge = await getInspectWebKitBridge();
           const bridgeTargets = await bridge.listTargets();
-          const wsHost = bridgeWsHost(req.headers?.host, bridge.port);
+          // Proxy mode routes the inspector socket through the preview's
+          // same-origin `/devtools` proxy; otherwise the browser talks to the
+          // bridge's loopback port directly (the pre-proxy behavior).
+          const wsProtocol = proxyHelpers ? websocketProtocolForRequest(req) : "ws";
+          const wsTargetBase = proxyHelpers
+            ? `${hostForRequest(req) ?? `127.0.0.1:${bridge.port}`}${devtoolsPrefix}`
+            : `127.0.0.1:${bridge.port}/devtools`;
           // inspect-webkit@0.0.3 only exposes `sim:<webinspectord-pid>` for
           // simulator targets, which can't be reconciled against a sim UDID.
           // Surface every booted sim's targets (Safari Develop-menu behavior)
           // until inspect-webkit grows a real UDID we can filter on.
           const targets = bridgeTargets.map((target) => ({
             ...target,
-            webSocketDebuggerUrl: `ws://${wsHost}/devtools/page/${encodeURIComponent(target.id)}`,
-            devtoolsFrontendUrl: devtoolsFrontendUrl(devtoolsFrontendBase, wsHost, target.id),
+            webSocketDebuggerUrl: `${wsProtocol}://${wsTargetBase}/page/${encodeURIComponent(target.id)}`,
+            devtoolsFrontendUrl: devtoolsFrontendUrl(devtoolsFrontendBase, wsProtocol, wsTargetBase, target.id),
           }));
           res.writeHead(200, {
             "Content-Type": "application/json",
@@ -1056,7 +1405,7 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
       req.on("end", async () => {
         try {
           const parsed: ReleaseRequestBody = body ? JSON.parse(body) : {};
-          const bridge = await ensureInspectWebKitBridge();
+          const bridge = await getInspectWebKitBridge();
           bridge.releaseHighlight?.(parsed.targetId);
           res.writeHead(200, { "Content-Type": "application/json" });
           res.end("{}");
@@ -1084,7 +1433,7 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
             res.end(JSON.stringify({ error: "Missing targetId" }));
             return;
           }
-          const bridge = await ensureInspectWebKitBridge();
+          const bridge = await getInspectWebKitBridge();
           if (!bridge.highlightTarget) {
             res.writeHead(501, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ error: "highlightTarget not supported by inspect-webkit" }));
@@ -1126,8 +1475,8 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
         "Content-Type": "application/json",
         "Cache-Control": "no-store",
       });
-      const remoteState = state ? rewriteStateForRequestHost(state, req.headers?.host) : null;
-      res.end(JSON.stringify(remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken) : null));
+      const remoteState = state ? rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers) : null;
+      res.end(JSON.stringify(remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken, options?.codec, proxyHelpers) : null));
       return;
     }
 
@@ -1139,9 +1488,9 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
       const computeConfig = (): string => {
         const states = readServeSimStates();
         const state = selectServeSimState(states, selectedDevice);
-        const remoteState = state ? rewriteStateForRequestHost(state, req.headers?.host) : null;
+        const remoteState = state ? rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers) : null;
         return JSON.stringify(
-          remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken) : null,
+          remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken, options?.codec, proxyHelpers) : null,
         );
       };
 
@@ -1414,24 +1763,63 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
 
     // Not ours — pass through
     if (next) next();
+  }) as SimMiddleware;
+  middleware.handleUpgrade = (req: SimReq, socket: Socket, head: Buffer) => {
+    const rawUrl = req.url ?? "";
+    const selectedDevice = queryDevice(rawUrl) ?? options?.device ?? null;
+    const helperTarget = helperProxyTarget(rawUrl, helperPrefix);
+    const devtoolsTarget = devtoolsProxyTarget(rawUrl, devtoolsPrefix);
+    if (devtoolsTarget) {
+      (async () => {
+        try {
+          const bridge = await getInspectWebKitBridge();
+          bridgeWebSocketFrames(req, socket, head, `ws://127.0.0.1:${bridge.port}${devtoolsTarget.upstreamPath}`);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : "Failed to start inspect-webkit";
+          socket.end(`HTTP/1.1 502 Bad Gateway\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${message}`);
+        }
+      })();
+      return;
+    }
+    if (!helperTarget) {
+      socket.destroy();
+      return;
+    }
+    const states = readServeSimStates();
+    const state = selectServeSimState(states, helperTarget.device ?? selectedDevice);
+    if (!state) {
+      socket.end("HTTP/1.1 404 Not Found\r\n\r\n");
+      return;
+    }
+    if (helperTarget.upstreamPath === "/ws") {
+      bridgeHelperWebSocket(req, socket, head, state);
+      return;
+    }
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
   };
-
   // WebSocket exec channel — same auth/origin policy as POST /exec, but off
   // the browser's per-origin HTTP connection pool so multiple preview tabs
   // (each holding MJPEG + SSE streams) can't starve exec actions. Servers
   // mounting this middleware should forward `upgrade` events here (the
   // built-in preview server does); the client falls back to POST /exec when
   // the upgrade never completes.
-  return Object.assign(middleware, {
-    handleUpgrade: createExecUpgradeHandler({
-      path: `${base}/exec-ws`,
-      execToken,
-      ssePrefixes: [
-        `${base}/api/events`,
-        `${base}/appstate`,
-        `${base}/ax`,
-      ],
-      onUiRequest: handleUiRequest,
-    }),
+  const handleExecUpgrade = createExecUpgradeHandler({
+    path: `${base}/exec-ws`,
+    execToken,
+    ssePrefixes: [
+      `${base}/api/events`,
+      `${base}/appstate`,
+      `${base}/ax`,
+    ],
+    onUiRequest: handleUiRequest,
   });
+
+  // WebSocket upgrades owned by the preview: the authenticated exec/control
+  // channel plus same-origin helper/devtools proxy sockets.
+  const handleProxyUpgrade = middleware.handleUpgrade;
+  middleware.handleUpgrade = (req: SimReq, socket: Socket, head: Buffer) => {
+    if (handleExecUpgrade(req, socket, head)) return;
+    handleProxyUpgrade(req, socket, head);
+  };
+  return middleware;
 }