@expo/serve-sim 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/serve-sim",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "author": {
     "name": "Evan Bacon",
@@ -37,6 +37,9 @@
     "dist/middleware.js",
     "dist/middleware.cjs",
     "dist/state.js",
+    "dist/capability-loader/libServeSimCapabilityLoader.dylib",
+    "Sources/ServeSimCapabilityLoader/serve-sim-capability-loader.c",
+    "Sources/ServeSimCapabilityLoader/build.sh",
     "dist/simcam/libSimCameraInjector.dylib",
     "dist/simcam/serve-sim-camera-helper",
     "dist/simax/serve-sim-ax-settings",
@@ -74,6 +77,7 @@
   "scripts": {
     "build": "bun run build.ts",
     "dev": "bun run dev.ts",
+    "test:capability-loader": "Sources/ServeSimCapabilityLoader/tests/run.sh",
     "tart": "bun scripts/tart/cli.ts",
     "tart-test": "bun scripts/tart/cli.ts test",
     "tart-dev": "bun scripts/tart/cli.ts dev"
@@ -83,6 +87,7 @@
     "@types/debug": "^4.1.13",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/three": "^0.186.0",
     "@types/ws": "^8.18.1",
     "bun-plugin-tailwind": "^0.1.2",
     "commander": "^14.0.1",
@@ -93,6 +98,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.1.7",
+    "three": "^0.186.0",
     "typescript": "^5.7.0",
     "werift": "^0.24.4",
     "zod": "^4.5.4"

package/src/connect-to-fetch.ts

@@ -53,6 +53,9 @@ export function connectToFetch(
 
   let status = 200;
   let responseHeaders = new Headers();
+  // Set before the status is written, the way `ServerResponse.setHeader` allows. `writeHead`
+  // values win, matching Node.
+  const presetHeaders = new Headers();
   let headersSent = false;
   let writableEnded = false;
   let writableFinished = false;
@@ -96,6 +99,9 @@ export function connectToFetch(
   const ensureResponse = () => {
     if (headersSent) return;
     headersSent = true;
+    for (const [name, value] of presetHeaders) {
+      if (!responseHeaders.has(name)) responseHeaders.set(name, value);
+    }
     resolveOnce(new Response(statusAllowsBody() ? body : null, { status, headers: responseHeaders }));
   };
   const writeChunk = (chunk: Buffer | string | Uint8Array) => {
@@ -122,6 +128,9 @@ export function connectToFetch(
     get writableNeedDrain() { return writableNeedDrain; },
     get statusCode() { return status; },
     set statusCode(nextStatus: number) { status = nextStatus; },
+    setHeader(name: string, value: string) {
+      presetHeaders.set(name, value);
+    },
     writeHead(nextStatus: number, headers?: Record<string, string | number | string[]>) {
       status = nextStatus;
       if (headers) {

package/src/middleware.ts

@@ -21,7 +21,6 @@ import {
   closeDeviceSession,
   getDeviceSession,
   peekDeviceSession,
-  sendCorsPreflight,
   type HidSocket,
 } from "./device-session";
 import { assertPreviewAccess, assertUpgradeAccess } from "./session-auth";
@@ -40,6 +39,8 @@ import {
   serveDevicePlaceholderAsset,
   type DeviceKitChromeDescriptor,
 } from "./devicekit-chrome";
+import { serveDeviceKitModelAsset } from "./devicekit-model";
+import { validatePanelRoute } from "./panel-route";
 import { createExecWebSocketHandler, type UiRequestHandler } from "./exec-ws";
 import { claimHelperHidSocket, type UpgradeHandlerWebSocket } from "./middleware-utils";
 import { UI_OPTIONS, getUiStatus, normalizeUiValue, setUiOption } from "./ui-settings";
@@ -179,11 +180,6 @@ 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);
 }
 
-const SCREENSHOT_RESPONSE_HEADERS = {
-  "Access-Control-Allow-Origin": "*",
-  "Cache-Control": "no-store",
-};
-
 /** What to do with a persisted device state when reaping during a grid poll. */
 type StaleStateAction = "keep" | "recycle-self" | "recycle-helper";
 
@@ -558,6 +554,7 @@ function helperProxyTarget(rawUrl: string, prefix: string): { device: string | n
     "config",
     "foreground",
     "health",
+    "panel",
     "stream.avcc",
     "stream.mjpeg",
     "webrtc",
@@ -803,18 +800,20 @@ function serveHelperInProcess(
 ): boolean {
   if (!device) return false;
   const endpoint = upstreamPath.split("?")[0];
+  const panelRoute = /^\/panel\/([^/]+)\/(.+)$/.exec(endpoint ?? "");
+  if (panelRoute) {
+    const route = validatePanelRoute(panelRoute[1]!, panelRoute[2]!, req.method);
+    if ("error" in route) {
+      res.writeHead(route.status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: route.error }));
+      return true;
+    }
+    if (req.method === "OPTIONS") { res.writeHead(204); res.end(); return true; }
+  }
   if (endpoint === "/camera/status") {
     void handleCameraStatus(req, res, device);
     return true;
   }
-  if (
-    (endpoint === "/webrtc/offer" || endpoint === "/webrtc/close" || endpoint === "/webrtc/stats"
-      || endpoint === "/stream-settings")
-    && req.method === "OPTIONS"
-  ) {
-    sendCorsPreflight(res);
-    return true;
-  }
   // Polled once a second by the panel and the recorder, so creating a session here would start a
   // capture nothing asked for, and re-create one every tick after the simulator is shut down.
   if (endpoint === "/webrtc/stats") {
@@ -824,11 +823,25 @@ function serveHelperInProcess(
     return true;
   }
   let session;
+  if (panelRoute && (panelRoute[2] === "webrtc/stats" || panelRoute[2] === "webrtc/close")) {
+    const live = peekDeviceSession(device);
+    if (!live) {
+      res.writeHead(panelRoute[2] === "webrtc/close" ? 204 : 404);
+      res.end();
+      return true;
+    }
+    void live.handlePanel(req, res, Number(panelRoute[1]), panelRoute[2]!);
+    return true;
+  }
   try {
     session = getDeviceSession(device, initialStreamSettings);
   } catch {
     return false; // not booted / capture unavailable → 404
   }
+  if (panelRoute) {
+    void session.handlePanel(req, res, Number(panelRoute[1]), panelRoute[2]!);
+    return true;
+  }
   switch (endpoint) {
     case "/stream.mjpeg": session.handleMjpeg(req, res); return true;
     case "/stream.avcc": session.handleAvcc(req, res); return true;
@@ -1502,10 +1515,12 @@ export interface SimMiddlewareOptions {
   /** Stream transport and codec settings for the preview. */
   streamSettings?: StreamSettings;
   /**
-   * Origins allowed to read the `/metrics` SSE stream cross-origin (e.g. a
-   * hosted dashboard). Read-only telemetry only; the control routes stay
-   * same-origin + token-gated regardless. Loopback is always allowed.
+   * Origins allowed to read this preview cross-origin (e.g. a hosted dashboard).
+   * Every route answers with the policy, so the token gate stays the thing that
+   * decides access. Loopback is always allowed.
    */
+  corsOrigins?: string[];
+  /** @deprecated Use `corsOrigins`. */
   metricsCorsOrigins?: string[];
   frameAncestors?: string[];
   /** Public page the Share button copies instead of this preview's address. */
@@ -1548,7 +1563,6 @@ export function handleMetricsRequest(
   res: SimRes,
   state: ServeSimState | null,
   samplerCache: MetricsSamplerCache = metricsSamplerCache,
-  corsOrigins: readonly string[] = [],
   tracker: ForegroundTrackerCache = foregroundTracker,
 ): void {
   if (!state) {
@@ -1561,7 +1575,6 @@ export function handleMetricsRequest(
     "Cache-Control": "no-cache",
     Connection: "keep-alive",
     "X-Accel-Buffering": "no",
-    ...corsAllowOriginHeaders(req.headers.origin, corsOrigins),
   });
   res.write(":\n\n");
   // Keep the foreground tail warm for this stream's lifetime so the sampler can scope to the
@@ -1594,9 +1607,13 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
   // can't read this value (it's only injected into the preview page's config).
   const execToken = options?.execToken ?? randomBytes(32).toString("base64url");
   const requirePreviewToken = options?.requirePreviewToken ?? false;
-  const metricsCorsOrigins = options?.metricsCorsOrigins ?? [];
+  const corsOrigins = [...(options?.corsOrigins ?? []), ...(options?.metricsCorsOrigins ?? [])];
   const frameAncestors = options?.frameAncestors ?? [];
   const shareUrl = options?.shareUrl;
+  // The proxied DevTools frontend sits behind the same cookie, so its document needs the policy too.
+  const framePolicyHeaders: Record<string, string> = requirePreviewToken
+    ? { "Content-Security-Policy": frameAncestorsPolicy(frameAncestors) }
+    : {};
 
   // Simulator-settings requests run in-process (just the underlying simctl /
   // ax-tool spawn) instead of round-tripping a full `node <cli>` exec per
@@ -1646,6 +1663,25 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     const rawUrl: string = req.url ?? "";
     const qIndex = rawUrl.indexOf("?");
     const url = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
+    const ownPath = url === base || url.startsWith(`${base}/`);
+    // Whole-middleware, so a new route is reachable cross-origin without opting in.
+    if (ownPath) {
+      // Unconditional, including when the origin is refused: a cached copy carrying no policy
+      // would otherwise be replayed to an origin that is allowed one.
+      res.setHeader("Vary", "Origin");
+      const corsHeaders = corsAllowOriginHeaders(req.headers.origin, corsOrigins);
+      for (const [name, value] of Object.entries(corsHeaders)) res.setHeader(name, value);
+    }
+    // A preflight carries no cookie and no token, so it has to be answered before the gate.
+    if (ownPath && req.method === "OPTIONS") {
+      res.writeHead(204, {
+        "Access-Control-Allow-Methods": "GET, POST, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "Authorization, Content-Type",
+        "Access-Control-Max-Age": "600",
+      });
+      res.end();
+      return;
+    }
     const requestedDevice = queryDevice(rawUrl);
     const selectedDevice = requestedDevice ?? options?.device ?? null;
     const devtoolsFrontendBase = base === "/" ? "/devtools-frontend" : `${base}/devtools-frontend`;
@@ -1653,7 +1689,11 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     // Gated as a whole rather than per route, so a new route is protected by default.
     if (
       !UNGATED_PATHS.some((path) => url === base + path)
-      && !assertPreviewAccess(req, res, execToken, { required: requirePreviewToken, basePath: base })
+      && !assertPreviewAccess(req, res, execToken, {
+        required: requirePreviewToken,
+        basePath: base,
+        htmlHeaders: framePolicyHeaders,
+      })
     ) {
       return;
     }
@@ -1691,10 +1731,13 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         const upstream = await fetch(
           `https://chrome-devtools-frontend.appspot.com/serve_rev/@${DEVTOOLS_FRONTEND_REV}/${assetPath}${upstreamSuffix}`,
         );
+        const contentType = upstream.headers.get("content-type");
+        const isDocument = contentType?.startsWith("text/html") ?? false;
         const headers: Record<string, string> = {
-          "Cache-Control": "public, max-age=604800",
+          // A cached copy would otherwise outlive the policy it was fetched under.
+          "Cache-Control": isDocument ? "no-store" : "public, max-age=604800",
+          ...(isDocument ? framePolicyHeaders : {}),
         };
-        const contentType = upstream.headers.get("content-type");
         if (contentType) headers["Content-Type"] = contentType;
         res.writeHead(upstream.status, headers);
         res.end(Buffer.from(await upstream.arrayBuffer()));
@@ -1738,9 +1781,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       res.writeHead(200, {
         "Content-Type": "text/html; charset=utf-8",
         "Cache-Control": "no-store",
-        ...(requirePreviewToken
-          ? { "Content-Security-Policy": frameAncestorsPolicy(frameAncestors) }
-          : {}),
+        ...framePolicyHeaders,
       });
       res.end(html);
       return;
@@ -1766,6 +1807,11 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       return;
     }
 
+    if (url === base + "/grid/api/devicekit-model") {
+      serveDeviceKitModelAsset(req, res);
+      return;
+    }
+
     // Static simulator metadata. The browser keeps this catalog in memory and
     // receives state/helper changes through the compact status feed below.
     if (url === base + "/grid/api/catalog") {
@@ -2185,7 +2231,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     if (url === base + "/api/screenshot") {
       if (req.method !== "POST") {
         res.writeHead(405, {
-          ...SCREENSHOT_RESPONSE_HEADERS,
+          "Cache-Control": "no-store",
           "Content-Type": "text/plain; charset=utf-8",
         });
         res.end("method not allowed");
@@ -2194,7 +2240,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       let udid = selectedDevice;
       if (udid && !isSimulatorUdid(udid)) {
         res.writeHead(400, {
-          ...SCREENSHOT_RESPONSE_HEADERS,
+          "Cache-Control": "no-store",
           "Content-Type": "application/json",
         });
         res.end(JSON.stringify({ ok: false, error: "Invalid simulator device ID" }));
@@ -2206,7 +2252,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       }
       if (!udid) {
         res.writeHead(400, {
-          ...SCREENSHOT_RESPONSE_HEADERS,
+          "Cache-Control": "no-store",
           "Content-Type": "application/json",
         });
         res.end(JSON.stringify({ ok: false, error: "No booted simulator to screenshot" }));
@@ -2229,7 +2275,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         });
         const png = await readFile(file);
         res.writeHead(200, {
-          ...SCREENSHOT_RESPONSE_HEADERS,
+          "Cache-Control": "no-store",
           "Content-Type": "image/png",
         });
         res.end(png);
@@ -2239,7 +2285,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
           (typeof stderr === "string" && stderr.trim()) ||
           (err instanceof Error ? err.message : String(err));
         res.writeHead(500, {
-          ...SCREENSHOT_RESPONSE_HEADERS,
+          "Cache-Control": "no-store",
           "Content-Type": "application/json",
         });
         res.end(JSON.stringify({ ok: false, error: message }));
@@ -2463,7 +2509,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     if (url === base + "/metrics") {
       const states = await readServeSimStates();
       const state = selectServeSimState(states, selectedDevice);
-      handleMetricsRequest(req, res, state, metricsSamplerCache, metricsCorsOrigins);
+      handleMetricsRequest(req, res, state, metricsSamplerCache);
       return;
     }
 

package/src/native.ts

@@ -16,6 +16,7 @@ import {
   type StreamEncoderSettings,
 } from "./stream-settings";
 import { readSenderStats, type SenderStats } from "./webrtc-sender-stats";
+import type { HingePhysicalOrientation } from "./hinge-control";
 
 const require = createRequire(import.meta.url);
 
@@ -24,6 +25,12 @@ const require = createRequire(import.meta.url);
 // handle is garbage-collected (Swift `deinit`), so there are no explicit
 // destroy/free calls here.
 interface SimHIDHandle {
+  setScreen(screenId: number): Promise<void>;
+  supportsHingeAngle(): Promise<boolean>;
+  hingeState(): Promise<NativeHingeState>;
+  setHingeAngle(angle: number): Promise<boolean>;
+  setHingePose(pose: string): Promise<boolean>;
+  setTableMode(enabled: boolean): Promise<boolean>;
   touch(type: TouchType, x: number, y: number, w: number, hh: number, edge: number): Promise<void>;
   multiTouch(type: TouchType, x1: number, y1: number, x2: number, y2: number, w: number, hh: number): Promise<void>;
   button(button: string): Promise<void>;
@@ -49,7 +56,8 @@ interface SimCaptureHandle {
   handleWebRTCOffer(offerJson: string): Promise<string>;
   closeWebRTCSession(sessionId: string): Promise<void>;
   webRTCSenderStats(sessionId: string): Promise<string>;
-  screenSize(): Promise<{ width: number; height: number }>;
+  screenSize(): Promise<NativeScreenInfo>;
+  subscribeScreenChanges(onChange: () => Promise<void>): Promise<NativeUnsubscribe>;
   stop(): Promise<void>;
   subscribe(codec: number, onFrame: RawFrameCallback): Promise<NativeUnsubscribe>;
 }
@@ -63,6 +71,7 @@ interface NativeAddon {
     maxDimension: number,
     h264Fps: number,
     h264Bitrate: number,
+    screenId?: number,
   ) => SimCaptureHandle;
   axDescribe(udid: string): Promise<string>;
   axFrontmost(udid: string): Promise<string>;
@@ -98,6 +107,21 @@ export type AvccFrame = {
 
 export type NativeCaptureOptions = StreamEncoderSettings;
 
+export type NativeHingeState = {
+  hingeAngle?: number;
+  tableMode?: boolean;
+  physicalOrientation?: HingePhysicalOrientation;
+};
+
+export type NativeScreenInfo = {
+  width: number;
+  height: number;
+  /** Present when CoreSimulator exposes its active screen metadata. */
+  orientation?: "portrait" | "portrait_upside_down" | "landscape_left" | "landscape_right";
+  screenId?: number;
+  chromeIdentifier?: string;
+};
+
 export type NativeUnsubscribe = () => Promise<void>;
 
 export type TouchType = "begin" | "move" | "end";
@@ -144,6 +168,7 @@ function load(): NativeAddon {
  */
 export class NativeHid {
   private readonly handle: SimHIDHandle;
+  private inputUnavailable = false;
 
   constructor(udid: string) {
     this.handle = new (load().SimHID)(udid);
@@ -157,6 +182,7 @@ export class NativeHid {
   // the sim reboots. The spawned helper used to absorb this in its own process;
   // `guard` restores that isolation by swallowing malformed-input errors.
   private async guard<T>(op: string, fn: () => PromiseLike<T>, fallback: T): Promise<T> {
+    if (this.inputUnavailable) return fallback;
     try {
       return await fn();
     } catch (err) {
@@ -169,6 +195,38 @@ export class NativeHid {
     return this.guard("touch", () => this.handle.touch(type, x, y, w, h, edge), undefined);
   }
 
+  async setScreen(screenId: number): Promise<void> {
+    if (this.inputUnavailable) return;
+    try {
+      await this.handle.setScreen(screenId);
+    } catch (err) {
+      // Native setup is cached for this handle; a failed setup cannot recover
+      // until a new session. Keep capture running without calling partial HID state.
+      this.inputUnavailable = true;
+      console.error("[hid] Input setup failed; streaming will continue without input:", err instanceof Error ? err.message : err);
+    }
+  }
+
+  setHingeAngle(angle: number): Promise<boolean> {
+    return this.guard("setHingeAngle", () => this.handle.setHingeAngle(angle), false);
+  }
+
+  setHingePose(pose: string): Promise<boolean> {
+    return this.guard("setHingePose", () => this.handle.setHingePose(pose), false);
+  }
+
+  setTableMode(enabled: boolean): Promise<boolean> {
+    return this.guard("setTableMode", () => this.handle.setTableMode(enabled), false);
+  }
+
+  supportsHingeAngle(): Promise<boolean> {
+    return this.guard("supportsHingeAngle", () => this.handle.supportsHingeAngle(), false);
+  }
+
+  hingeState(): Promise<NativeHingeState> {
+    return this.guard("hingeState", () => this.handle.hingeState(), {});
+  }
+
   multiTouch(type: TouchType, x1: number, y1: number, x2: number, y2: number, w: number, h: number): Promise<void> {
     return this.guard("multiTouch", () => this.handle.multiTouch(type, x1, y1, x2, y2, w, h), undefined);
   }
@@ -220,7 +278,11 @@ export class NativeHid {
 export class NativeCapture {
   private readonly handle: SimCaptureHandle;
 
-  constructor(udid: string, options: NativeCaptureOptions = DEFAULT_STREAM_ENCODER_SETTINGS) {
+  /** A fixed screen ID captures that panel independently of active-display/input routing. */
+  constructor(udid: string, options: NativeCaptureOptions = DEFAULT_STREAM_ENCODER_SETTINGS, screenId?: number) {
+    if (screenId !== undefined && (!Number.isInteger(screenId) || screenId < 0 || screenId > 0xffff_ffff)) {
+      throw new RangeError("Screen ID must be an unsigned 32-bit integer.");
+    }
     this.handle = new (load().SimCapture)(
       udid,
       options.mjpegFps,
@@ -228,6 +290,7 @@ export class NativeCapture {
       options.maxDimension,
       options.h264Fps,
       options.h264Bitrate,
+      screenId ?? 0,
     );
   }
 
@@ -281,10 +344,14 @@ export class NativeCapture {
     return readSenderStats(JSON.parse(await this.handle.webRTCSenderStats(sessionId ?? "")));
   }
 
-  screenSize(): Promise<{ width: number; height: number }> {
+  screenSize(): Promise<NativeScreenInfo> {
     return this.handle.screenSize();
   }
 
+  subscribeScreenChanges(onChange: () => Promise<void>): Promise<NativeUnsubscribe> {
+    return this.handle.subscribeScreenChanges(onChange);
+  }
+
   /** Halt frame production. Full teardown happens when this object is GC'd. */
   stop(): Promise<void> {
     return this.handle.stop();