Support embedded client expose URLs

DjDeveloperr · DjDeveloperr · commit b0df48c4ea2c · 2026-05-01T17:07:15.000-04:00
diff --git a/client/src/api/client.ts b/client/src/api/client.ts
@@ -1,4 +1,4 @@
-import { API_ROOT } from "../shared/constants";
+import { apiUrl } from "./config";
 import type { HealthResponse } from "./types";
 
 export class ApiError extends Error {
@@ -32,7 +32,7 @@ export async function apiRequest<T>(
   options: RequestInit = {},
 ): Promise<T> {
   const { headers, ...rest } = options;
-  const response = await fetch(`${API_ROOT}${path}`, {
+  const response = await fetch(apiUrl(path), {
     ...rest,
     headers: apiHeaders(headers),
   });
diff --git a/client/src/api/config.ts b/client/src/api/config.ts
@@ -0,0 +1,31 @@
+export interface SimDeckClientConfig {
+  apiRoot?: string;
+}
+
+let clientConfig: Required<SimDeckClientConfig> = {
+  apiRoot: "",
+};
+
+export function configureSimDeckClient(config: SimDeckClientConfig): void {
+  clientConfig = {
+    ...clientConfig,
+    ...config,
+    apiRoot: normalizeRoot(config.apiRoot ?? clientConfig.apiRoot),
+  };
+}
+
+export function apiRoot(): string {
+  return clientConfig.apiRoot;
+}
+
+export function apiUrl(path: string): string {
+  const root = apiRoot();
+  if (!root) {
+    return path;
+  }
+  return `${root}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+function normalizeRoot(root: string): string {
+  return root.replace(/\/+$/, "");
+}
diff --git a/client/src/api/controls.ts b/client/src/api/controls.ts
@@ -1,4 +1,5 @@
 import { accessTokenFromLocation, apiRequest } from "./client";
+import { apiUrl } from "./config";
 import type {
   KeyPayload,
   LaunchPayload,
@@ -58,7 +59,7 @@ export function sendKey(udid: string, payload: KeyPayload) {
 
 export function simulatorControlSocketUrl(udid: string) {
   const url = new URL(
-    `/api/simulators/${encodeURIComponent(udid)}/control`,
+    apiUrl(`/api/simulators/${encodeURIComponent(udid)}/control`),
     window.location.href,
   );
   const token = accessTokenFromLocation();
diff --git a/client/src/app/AppShell.tsx b/client/src/app/AppShell.tsx
@@ -9,6 +9,7 @@ import {
 } from "react";
 
 import { ApiError, accessTokenFromLocation, pairBrowser } from "../api/client";
+import { apiUrl, configureSimDeckClient } from "../api/config";
 import {
   bootSimulator,
   dismissKeyboard,
@@ -61,7 +62,6 @@ import {
 } from "../features/viewport/viewportMath";
 import {
   DEVICE_SCREEN_WIDTH,
-  STREAM_ORIGIN,
   ZOOM_ANIMATION_MS,
   ZOOM_STEP,
 } from "../shared/constants";
@@ -102,7 +102,7 @@ function buildScreenMaskUrl(udid: string, stamp: number): string {
 }
 
 function buildAuthenticatedAssetUrl(path: string, stamp: number): string {
-  const url = new URL(path, `${STREAM_ORIGIN || window.location.origin}/`);
+  const url = new URL(apiUrl(path), window.location.href);
   url.searchParams.set("stamp", String(stamp));
   const token = accessTokenFromLocation();
   if (token) {
@@ -172,10 +172,26 @@ type SimulatorTransition = {
   udid: string;
 };
 
-export function AppShell() {
+export interface AppShellProps {
+  apiRoot?: string;
+  fixedSimulatorUDID?: string | null;
+  hideSimulatorSelection?: boolean;
+  pairingEnabled?: boolean;
+}
+
+export function AppShell({
+  apiRoot = "",
+  fixedSimulatorUDID = null,
+  hideSimulatorSelection = false,
+  pairingEnabled = true,
+}: AppShellProps = {}) {
+  configureSimDeckClient({ apiRoot });
   const [initialUiState] = useState(readPersistedUiState);
   const [initialSelectedUDID] = useState(
-    () => readDeviceQueryParam() ?? initialUiState.selectedUDID,
+    () =>
+      fixedSimulatorUDID ??
+      readDeviceQueryParam() ??
+      initialUiState.selectedUDID,
   );
   const initialViewportState = initialSelectedUDID
     ? viewportStateForUDID(initialUiState, initialSelectedUDID)
@@ -301,6 +317,14 @@ export function AppShell() {
   });
 
   const selectedSimulator =
+    (fixedSimulatorUDID
+      ? (simulators.find(
+          (simulator) => simulator.udid === fixedSimulatorUDID,
+        ) ??
+        simulators.find((simulator) =>
+          simulatorMatchesIdentifier(simulator, fixedSimulatorUDID),
+        ))
+      : null) ??
     simulators.find((simulator) => simulator.udid === selectedUDID) ??
     simulators.find((simulator) =>
       simulatorMatchesIdentifier(simulator, selectedUDID),
@@ -354,6 +378,7 @@ export function AppShell() {
       !selectedSimulator ||
       !streamError ||
       readDeviceQueryParam() ||
+      fixedSimulatorUDID ||
       !isStreamAttachFailure(streamError)
     ) {
       return;
@@ -377,7 +402,13 @@ export function AppShell() {
         `${selectedSimulator.name} did not expose a live simulator screen. Switched to ${nextSimulator.name}.`,
       );
     }
-  }, [failedStreamUDIDs, selectedSimulator, simulators, streamError]);
+  }, [
+    failedStreamUDIDs,
+    fixedSimulatorUDID,
+    selectedSimulator,
+    simulators,
+    streamError,
+  ]);
   const shouldRenderChrome =
     selectedSimulator != null && shouldRenderNativeChrome(selectedSimulator);
   const viewportChromeProfile = shouldRenderChrome ? chromeProfile : null;
@@ -499,10 +530,14 @@ export function AppShell() {
   }, [accessibilitySelectedId, selectedSimulator?.udid]);
 
   useEffect(() => {
-    if (selectedSimulator && selectedSimulator.udid !== selectedUDID) {
+    if (
+      !fixedSimulatorUDID &&
+      selectedSimulator &&
+      selectedSimulator.udid !== selectedUDID
+    ) {
       setSelectedUDID(selectedSimulator.udid);
     }
-  }, [selectedSimulator, selectedUDID]);
+  }, [fixedSimulatorUDID, selectedSimulator, selectedUDID]);
 
   useEffect(() => {
     const nextViewportState = selectedSimulator
@@ -805,7 +840,9 @@ export function AppShell() {
   });
 
   const pairingRequired =
-    listError === AUTH_REQUIRED_MESSAGE && !accessTokenFromLocation();
+    pairingEnabled &&
+    listError === AUTH_REQUIRED_MESSAGE &&
+    !accessTokenFromLocation();
   const error = pairingRequired
     ? localError || streamError
     : localError || streamError || listError;
@@ -1221,6 +1258,7 @@ export function AppShell() {
         error={error}
         filteredSimulators={filteredSimulators}
         hierarchyVisible={hierarchyVisible}
+        hideSimulatorSelection={hideSimulatorSelection}
         isLoading={isLoading}
         menuOpen={menuOpen}
         menuRef={menuRef}
diff --git a/client/src/embedded.ts b/client/src/embedded.ts
@@ -0,0 +1,3 @@
+export { AppShell as SimDeckClient } from "./app/AppShell";
+export type { AppShellProps as SimDeckClientProps } from "./app/AppShell";
+export type { SimulatorMetadata } from "./api/types";
diff --git a/client/src/features/simulators/SimulatorMenu.tsx b/client/src/features/simulators/SimulatorMenu.tsx
@@ -6,6 +6,7 @@ import { SimulatorRow } from "./SimulatorRow";
 interface SimulatorMenuProps {
   debugVisible: boolean;
   filteredSimulators: SimulatorMetadata[];
+  hideSimulatorSelection?: boolean;
   isLoading: boolean;
   menuOpen: boolean;
   menuRef: RefObject<HTMLDivElement | null>;
@@ -23,6 +24,7 @@ interface SimulatorMenuProps {
 export function SimulatorMenu({
   debugVisible,
   filteredSimulators,
+  hideSimulatorSelection = false,
   isLoading,
   menuOpen,
   menuRef,
@@ -53,29 +55,33 @@ export function SimulatorMenu({
           className="menu-popover"
           onPointerDown={(event) => event.stopPropagation()}
         >
-          <input
-            className="sidebar-search"
-            onChange={(event) => onChangeSearch(event.target.value)}
-            placeholder="Search simulators…"
-            value={search}
-          />
-          <div className="sim-list">
-            {isLoading ? <p className="list-empty">Loading…</p> : null}
-            {!isLoading && filteredSimulators.length === 0 ? (
-              <p className="list-empty">No matches</p>
-            ) : null}
-            {filteredSimulators.map((simulator) => (
-              <SimulatorRow
-                isSelected={simulator.udid === selectedSimulator?.udid}
-                key={simulator.udid}
-                onSelect={() => {
-                  setSelectedUDID(simulator.udid);
-                  onCloseMenu();
-                }}
-                simulator={simulator}
+          {!hideSimulatorSelection ? (
+            <>
+              <input
+                className="sidebar-search"
+                onChange={(event) => onChangeSearch(event.target.value)}
+                placeholder="Search simulators..."
+                value={search}
               />
-            ))}
-          </div>
+              <div className="sim-list">
+                {isLoading ? <p className="list-empty">Loading...</p> : null}
+                {!isLoading && filteredSimulators.length === 0 ? (
+                  <p className="list-empty">No matches</p>
+                ) : null}
+                {filteredSimulators.map((simulator) => (
+                  <SimulatorRow
+                    isSelected={simulator.udid === selectedSimulator?.udid}
+                    key={simulator.udid}
+                    onSelect={() => {
+                      setSelectedUDID(simulator.udid);
+                      onCloseMenu();
+                    }}
+                    simulator={simulator}
+                  />
+                ))}
+              </div>
+            </>
+          ) : null}
           {selectedSimulator ? (
             <>
               <div className="menu-divider" />
diff --git a/client/src/features/stream/streamWorkerClient.ts b/client/src/features/stream/streamWorkerClient.ts
@@ -1,4 +1,5 @@
 import { apiHeaders, fetchHealth } from "../../api/client";
+import { apiUrl } from "../../api/config";
 import type { HealthResponse } from "../../api/types";
 import { createEmptyStreamStats } from "./stats";
 import type {
@@ -138,7 +139,10 @@ class WebRtcStreamClient implements StreamClientBackend {
         (video as HTMLVideoElement & { latencyHint?: string }).latencyHint =
           "interactive";
         video.srcObject = stream;
-        canvasElement.after(video);
+        canvasElement.parentElement?.insertBefore(
+          video,
+          canvasElement.nextSibling,
+        );
         this.video = video;
         const startPlayback = () => {
           if (generation !== this.connectGeneration) {
@@ -459,12 +463,15 @@ class WebRtcStreamClient implements StreamClientBackend {
       url: window.location.href,
       userAgent: window.navigator.userAgent,
     };
-    void fetch(new URL("/api/client-stream-stats", window.location.href), {
-      body: JSON.stringify(payload),
-      cache: "no-store",
-      headers: apiHeaders(),
-      method: "POST",
-    }).catch(() => {
+    void fetch(
+      new URL(apiUrl("/api/client-stream-stats"), window.location.href),
+      {
+        body: JSON.stringify(payload),
+        cache: "no-store",
+        headers: apiHeaders(),
+        method: "POST",
+      },
+    ).catch(() => {
       // Diagnostics only.
     });
   }
@@ -583,14 +590,17 @@ function postWebRtcOffer(
   udid: string,
   localDescription: RTCSessionDescription,
 ): Promise<Response> {
-  return fetch(`/api/simulators/${encodeURIComponent(udid)}/webrtc/offer`, {
-    body: JSON.stringify({
-      sdp: localDescription.sdp,
-      type: localDescription.type,
-    }),
-    headers: apiHeaders(),
-    method: "POST",
-  });
+  return fetch(
+    apiUrl(`/api/simulators/${encodeURIComponent(udid)}/webrtc/offer`),
+    {
+      body: JSON.stringify({
+        sdp: localDescription.sdp,
+        type: localDescription.type,
+      }),
+      headers: apiHeaders(),
+      method: "POST",
+    },
+  );
 }
 
 function configureLowLatencyReceiver(receiver: RTCRtpReceiver) {
diff --git a/client/src/features/stream/useLiveStream.ts b/client/src/features/stream/useLiveStream.ts
@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 
 import { apiHeaders } from "../../api/client";
+import { apiUrl } from "../../api/config";
 import type { SimulatorMetadata } from "../../api/types";
 import type { Size } from "../viewport/types";
 import { createEmptyStreamStats } from "./stats";
@@ -57,7 +58,10 @@ function createClientTelemetryId(): string {
 }
 
 function buildClientTelemetryUrl(): string {
-  return new URL("/api/client-stream-stats", window.location.href).toString();
+  return new URL(
+    apiUrl("/api/client-stream-stats"),
+    window.location.href,
+  ).toString();
 }
 
 export function useLiveStream({
diff --git a/client/src/features/toolbar/Toolbar.tsx b/client/src/features/toolbar/Toolbar.tsx
@@ -8,6 +8,7 @@ interface ToolbarProps {
   error: string;
   filteredSimulators: SimulatorMetadata[];
   hierarchyVisible: boolean;
+  hideSimulatorSelection?: boolean;
   isLoading: boolean;
   onBoot: () => void;
   onChangeSearch: (value: string) => void;
@@ -40,6 +41,7 @@ export function Toolbar({
   error,
   filteredSimulators,
   hierarchyVisible,
+  hideSimulatorSelection = false,
   isLoading,
   menuOpen,
   menuRef,
@@ -98,6 +100,7 @@ export function Toolbar({
         <SimulatorMenu
           debugVisible={debugVisible}
           filteredSimulators={filteredSimulators}
+          hideSimulatorSelection={hideSimulatorSelection}
           isLoading={isLoading}
           menuOpen={menuOpen}
           menuRef={menuRef}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export { AppShell as SimDeckClient } from "./app/AppShell";`
	`2`	`+export type { AppShellProps as SimDeckClientProps } from "./app/AppShell";`
	`3`	`+export type { SimulatorMetadata } from "./api/types";`