Add LAN pairing and WebRTC fallback support

Author: DjDeveloperr

AGENTS.md

@@ -99,7 +99,7 @@ Run the local daemon:
 ./build/simdeck daemon start --port 4310
 ```
 
-Running without a subcommand starts a foreground workspace daemon, prints local and LAN browser URLs, and stops when the command exits. Pass a simulator name or UDID as the only argument to select it by default in the UI. Use `./build/simdeck -d`, `./build/simdeck -k`, and `./build/simdeck -r` as detached start, kill, and restart shortcuts.
+Running without a subcommand starts a foreground workspace daemon, prints local and LAN HTTP URLs, prints a six-digit pairing code for LAN browsers, and stops when the command exits, when you press `q`, or when you press Ctrl-C. Pass a simulator name or UDID as the only argument to select it by default in the UI. Use `./build/simdeck -d`, `./build/simdeck -k`, and `./build/simdeck -r` as detached start, kill, and restart shortcuts.
 
 Use software H.264 when macOS screen recording starves the hardware encoder:
 

README.md

@@ -37,7 +37,7 @@ Full documentation lives at [simdeck.nativescript.org](https://simdeck.nativescr
 simdeck
 ```
 
-This starts a workspace-local foreground daemon, prints local and LAN browser URLs, and stops when you press Ctrl-C.
+This starts a workspace-local foreground daemon, prints local and LAN HTTP URLs plus a pairing code for LAN browsers, and stops when you press `q` or Ctrl-C.
 To focus a specific simulator by name or UDID, pass it as the only argument:
 
 ```sh
@@ -46,6 +46,7 @@ simdeck "iPhone 17 Pro Max"
 
 Use `simdeck ui --open` or `simdeck daemon start` when you want a reusable background daemon instead.
 The no-subcommand lifecycle shortcuts are `simdeck -d` for detached start, `simdeck -k` to kill the background daemon, and `simdeck -r` to restart it.
+The served loopback browser UI receives the generated API access token automatically. LAN browsers pair with the printed code before receiving the API cookie.
 
 CLI commands automatically use the same warm daemon:
 

cli/DFPrivateSimulatorDisplayBridge.m

@@ -7,10 +7,12 @@
 #import <mach-o/dyld.h>
 #import <mach-o/loader.h>
 #import <mach-o/nlist.h>
+#import <limits.h>
 #import <math.h>
 #import <objc/message.h>
 #import <objc/runtime.h>
 #import <stdarg.h>
+#import <stdio.h>
 
 // PurpleWorkspacePort mach message IDs / GSEvent type constants.
 // Reverse-engineered from Simulator.app ARM64 (Xcode 26.2) — see idb's
@@ -20,7 +22,6 @@
 #define DFGSEventTypeDeviceOrientationChanged 50
 
 static NSString * const DFPrivateSimulatorErrorDomain = @"SimDeck.PrivateSimulator";
-static NSString * const DFSimulatorKitPath = @"/Applications/Xcode.app/Contents/Developer/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit";
 static NSString * const DFCoreSimulatorPath = @"/Library/Developer/PrivateFrameworks/CoreSimulator.framework/CoreSimulator";
 static NSString * const DFPrivateSimulatorLogPath = @"/tmp/simdeck-private-bridge.log";
 static const void *DFPrivateSimulatorCallbackQueueKey = &DFPrivateSimulatorCallbackQueueKey;
@@ -104,6 +105,29 @@
 static const NSUInteger DFKeyboardModifierCommand = 1 << 3;
 static const NSUInteger DFKeyboardModifierCapsLock = 1 << 4;
 
+static NSString *DFSimulatorKitExecutablePath(void) {
+    const char *developerDir = getenv("DEVELOPER_DIR");
+    if (developerDir != NULL && developerDir[0] != '\0') {
+        return [[NSString stringWithUTF8String:developerDir] stringByAppendingPathComponent:@"Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit"];
+    }
+
+    FILE *pipe = popen("/usr/bin/xcode-select -p 2>/dev/null", "r");
+    if (pipe != NULL) {
+        char buffer[PATH_MAX] = {0};
+        if (fgets(buffer, sizeof(buffer), pipe) != NULL) {
+            NSString *selected = [[NSString stringWithUTF8String:buffer] stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];
+            pclose(pipe);
+            if (selected.length > 0) {
+                return [selected stringByAppendingPathComponent:@"Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit"];
+            }
+        } else {
+            pclose(pipe);
+        }
+    }
+
+    return @"/Applications/Xcode.app/Contents/Developer/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit";
+}
+
 typedef struct {
     __unsafe_unretained id unit;
     double value;
@@ -298,6 +322,7 @@ static void DFTrieDescend(DFTrieContext *ctx, const uint8_t *node, size_t nameLe
     }
 
     const struct linkedit_data_command *exportsTrie = NULL;
+    const struct symtab_command *symtab = NULL;
     const struct segment_command_64 *linkedit = NULL;
     uint64_t dyldInfoExportOff = 0;
     uint64_t dyldInfoExportSize = 0;
@@ -315,6 +340,9 @@ static void DFTrieDescend(DFTrieContext *ctx, const uint8_t *node, size_t nameLe
                 dyldInfoExportSize = info->export_size;
                 break;
             }
+            case LC_SYMTAB:
+                symtab = (const struct symtab_command *)lc;
+                break;
             case LC_SEGMENT_64: {
                 const struct segment_command_64 *seg = (const struct segment_command_64 *)lc;
                 if (strcmp(seg->segname, "__LINKEDIT") == 0) {
@@ -356,20 +384,51 @@ static void DFTrieDescend(DFTrieContext *ctx, const uint8_t *node, size_t nameLe
         return NULL;
     }
 
-    DFTrieContext ctx = {0};
-    ctx.trie = trie;
-    ctx.trieEnd = trie + trieSize;
-    ctx.prefix = prefixedBuf;
-    ctx.prefixLen = (size_t)written;
-    ctx.suffix = suffix ?: "";
-    ctx.suffixLen = suffix ? strlen(suffix) : 0;
+    if (trieFileOff > 0 && trieSize > 0) {
+        DFTrieContext ctx = {0};
+        ctx.trie = trie;
+        ctx.trieEnd = trie + trieSize;
+        ctx.prefix = prefixedBuf;
+        ctx.prefixLen = (size_t)written;
+        ctx.suffix = suffix ?: "";
+        ctx.suffixLen = suffix ? strlen(suffix) : 0;
 
-    DFTrieDescend(&ctx, trie, 0);
+        DFTrieDescend(&ctx, trie, 0);
 
-    if (!ctx.found) {
-        return NULL;
+        if (ctx.found) {
+            return (void *)((uintptr_t)gSimulatorKitImage + (uintptr_t)ctx.address);
+        }
+    }
+
+    // Some SimulatorKit Swift accessors are global symbols but are absent from
+    // the dyld exports trie on GitHub's hosted Xcode images. Fall back to the
+    // symbol table so prefix lookups still find those private Swift getters.
+    if (symtab != NULL && symtab->nsyms > 0 && symtab->symoff > 0 && symtab->stroff > 0) {
+        const struct nlist_64 *symbols = (const struct nlist_64 *)(linkeditMapped + (uintptr_t)symtab->symoff);
+        const char *strings = (const char *)(linkeditMapped + (uintptr_t)symtab->stroff);
+        size_t prefixLen = (size_t)written;
+        size_t suffixLen = suffix ? strlen(suffix) : 0;
+        for (uint32_t i = 0; i < symtab->nsyms; i++) {
+            const struct nlist_64 *entry = &symbols[i];
+            if ((entry->n_type & N_STAB) != 0 || entry->n_un.n_strx == 0 || entry->n_value == 0) {
+                continue;
+            }
+            const char *name = strings + entry->n_un.n_strx;
+            size_t nameLen = strlen(name);
+            if (nameLen < prefixLen + suffixLen) {
+                continue;
+            }
+            if (memcmp(name, prefixedBuf, prefixLen) != 0) {
+                continue;
+            }
+            if (suffixLen > 0 && memcmp(name + nameLen - suffixLen, suffix, suffixLen) != 0) {
+                continue;
+            }
+            return (void *)((uintptr_t)entry->n_value + (uintptr_t)gSimulatorKitSlide);
+        }
     }
-    return (void *)((uintptr_t)gSimulatorKitImage + (uintptr_t)ctx.address);
+
+    return NULL;
 }
 
 // Cache resolved function pointers per (prefix, suffix). Logs once per missing
@@ -542,18 +601,34 @@ static id DFInitSimDeviceScreen(Class screenClass, id device, uint32_t screenID,
 }
 
 static NSDictionary<NSNumber *, id> * DFReadAdapterScreens(id adapter) {
+    if (adapter == nil || ![NSStringFromClass([adapter class]) containsString:@"SimDeviceScreenAdapter"]) {
+        return @{};
+    }
+
     // The full mangled tail of `SimDeviceScreenAdapter.screens.getter` drifts
     // across Xcode releases (Xcode 26.4 retyped it from
     // `[UInt32: SimScreen]` (ObjC) to `[UInt32: SimDeviceScreen]` (Swift)).
     // Resolve by stable prefix instead. If the values are now SimDeviceScreen
     // wrappers, unwrap each via `.screen` so callers keep talking to a
     // SimScreen-shaped object.
-    id screens = DFCallSwiftSelfGetterByPattern(
+    id screens = DFCallSwiftSelfGetter(
         adapter,
-        "$s12SimulatorKit22SimDeviceScreenAdapterC7screens",
-        "vg",
-        "SimDeviceScreenAdapter.screens.getter"
+        "$s12SimulatorKit22SimDeviceScreenAdapterC7screensSDys6UInt32VSo0cE0_pGvg"
     );
+    if (screens == nil) {
+        screens = DFCallSwiftSelfGetter(
+            adapter,
+            "$s12SimulatorKit22SimDeviceScreenAdapterC7screensSDys6UInt32VAA0cdE0CGvg"
+        );
+    }
+    if (screens == nil) {
+        screens = DFCallSwiftSelfGetterByPattern(
+            adapter,
+            "$s12SimulatorKit22SimDeviceScreenAdapterC7screens",
+            "vg",
+            "SimDeviceScreenAdapter.screens.getter"
+        );
+    }
     if (![screens isKindOfClass:[NSDictionary class]]) {
         return @{};
     }
@@ -2025,10 +2100,11 @@ + (BOOL)loadPrivateFrameworks:(NSError **)error {
             return;
         }
 
-        if (!dlopen(DFSimulatorKitPath.fileSystemRepresentation, RTLD_NOW | RTLD_GLOBAL)) {
+        NSString *simulatorKitPath = DFSimulatorKitExecutablePath();
+        if (!dlopen(simulatorKitPath.fileSystemRepresentation, RTLD_NOW | RTLD_GLOBAL)) {
             loadError = DFMakeError(
                 DFPrivateSimulatorErrorCodeFrameworkLoadFailed,
-                [NSString stringWithFormat:@"Unable to load SimulatorKit from %@.", DFSimulatorKitPath]
+                [NSString stringWithFormat:@"Unable to load SimulatorKit from %@.", simulatorKitPath]
             );
         }
     });

client/src/api/client.ts

@@ -1,5 +1,15 @@
 import { API_ROOT } from "../shared/constants";
 
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
 export function accessTokenFromLocation(): string {
   if (typeof window === "undefined") {
     return "";
@@ -35,7 +45,7 @@ export async function apiRequest<T>(
     } else {
       message = await response.text();
     }
-    throw new Error(message);
+    throw new ApiError(message, response.status);
   }
 
   if (response.status === 204) {
@@ -48,3 +58,10 @@ export async function apiRequest<T>(
 
   return (await response.text()) as T;
 }
+
+export async function pairBrowser(code: string): Promise<void> {
+  await apiRequest<{ ok: boolean }>("/api/pair", {
+    body: JSON.stringify({ code }),
+    method: "POST",
+  });
+}

client/src/app/AppShell.tsx

@@ -5,9 +5,10 @@ import {
   useRef,
   useState,
   type CSSProperties,
+  type FormEvent,
 } from "react";
 
-import { accessTokenFromLocation } from "../api/client";
+import { ApiError, accessTokenFromLocation, pairBrowser } from "../api/client";
 import {
   bootSimulator,
   dismissKeyboard,
@@ -86,6 +87,7 @@ const ACCESSIBILITY_REFRESH_MS = 1500;
 const REACT_NATIVE_ACCESSIBILITY_REFRESH_MS = 500;
 const DEFAULT_ACCESSIBILITY_MAX_DEPTH = 10;
 const LOGICAL_INSPECTOR_MAX_DEPTH = 80;
+const AUTH_REQUIRED_MESSAGE = "SimDeck API access token is required.";
 
 clearLegacyVolatileUiState();
 
@@ -192,6 +194,9 @@ export function AppShell() {
   );
   const [menuOpen, setMenuOpen] = useState(false);
   const [localError, setLocalError] = useState("");
+  const [pairingCode, setPairingCode] = useState("");
+  const [pairingError, setPairingError] = useState("");
+  const [pairingBusy, setPairingBusy] = useState(false);
   const [simulatorTransition, setSimulatorTransition] =
     useState<SimulatorTransition | null>(null);
   const [rotationQuarterTurns, setRotationQuarterTurns] = useState(
@@ -325,6 +330,8 @@ export function AppShell() {
     runtimeInfo,
     stats,
     status: streamStatus,
+    streamBackend,
+    streamCanvasKey,
   } = useLiveStream({
     canvasElement: streamCanvasElement,
     simulator: selectedSimulator,
@@ -749,7 +756,11 @@ export function AppShell() {
     setPan,
   });
 
-  const error = localError || streamError || listError;
+  const pairingRequired =
+    listError === AUTH_REQUIRED_MESSAGE && !accessTokenFromLocation();
+  const error = pairingRequired
+    ? localError || streamError
+    : localError || streamError || listError;
   const deviceTransform = `translate(${pan.x}px, ${pan.y + autoViewportOffsetY}px) scale(${effectiveZoom})`;
   const chromeScreenRect = computeChromeScreenRect(
     viewportChromeProfile,
@@ -898,7 +909,11 @@ export function AppShell() {
   }
 
   useEffect(() => {
-    if (selectedSimulator?.isBooted && !isWebRtcStreamMode()) {
+    if (
+      selectedSimulator?.isBooted &&
+      !isWebRtcStreamMode() &&
+      streamBackend !== "webrtc"
+    ) {
       ensureControlSocket(selectedSimulator.udid);
     } else {
       closeControlSocket();
@@ -908,6 +923,7 @@ export function AppShell() {
     ensureControlSocket,
     selectedSimulator?.isBooted,
     selectedSimulator?.udid,
+    streamBackend,
   ]);
 
   useEffect(() => closeControlSocket, [closeControlSocket]);
@@ -1117,8 +1133,58 @@ export function AppShell() {
     );
   }
 
+  async function submitPairing(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const code = pairingCode.trim();
+    if (!code) {
+      setPairingError("Enter the pairing code from the SimDeck terminal.");
+      return;
+    }
+    setPairingBusy(true);
+    setPairingError("");
+    try {
+      await pairBrowser(code);
+      setPairingCode("");
+      await refresh();
+    } catch (error) {
+      setPairingError(
+        error instanceof ApiError && error.status === 401
+          ? "Pairing code did not match."
+          : error instanceof Error
+            ? error.message
+            : "Pairing failed.",
+      );
+    } finally {
+      setPairingBusy(false);
+    }
+  }
+
   return (
     <div className="app">
+      {pairingRequired ? (
+        <div className="pairing-gate" role="dialog" aria-modal="true">
+          <form className="pairing-panel" onSubmit={submitPairing}>
+            <h2>Pair SimDeck</h2>
+            <p>Enter the pairing code shown in the SimDeck terminal.</p>
+            <input
+              autoComplete="one-time-code"
+              autoFocus
+              inputMode="numeric"
+              onChange={(event) => setPairingCode(event.target.value)}
+              placeholder="000 000"
+              value={pairingCode}
+            />
+            {pairingError ? <span>{pairingError}</span> : null}
+            <button
+              className="tbtn accent"
+              disabled={pairingBusy}
+              type="submit"
+            >
+              Pair
+            </button>
+          </form>
+        </div>
+      ) : null}
       <Toolbar
         closeMenu={() => setMenuOpen(false)}
         debugVisible={debugVisible}
@@ -1314,6 +1380,8 @@ export function AppShell() {
         selectedSimulator={selectedSimulator}
         shellStyle={shellStyle}
         streamCanvasRef={handleStreamCanvasRef}
+        streamBackend={streamBackend}
+        streamCanvasKey={streamCanvasKey}
         statusOverlayLabel={simulatorStatusOverlayLabel}
         touchIndicators={touchIndicators}
         touchOverlayVisible={touchOverlayVisible}