@expo/serve-sim 0.1.35-canary.0

package/src/native.ts

@@ -0,0 +1,294 @@
+/**
+ * Typed loader + wrapper for serve-sim-native.node — the in-process N-API addon
+ * that replaces the spawned serve-sim-bin helper. HID is the first surface;
+ * frame capture + encoders land here next.
+ *
+ * The .node is resolved from disk (dist/native/) relative to either this module
+ * or the bun-compiled executable, so it loads under `npx serve-sim`, the
+ * compiled binary, and the mounted middleware alike.
+ */
+import { createRequire } from "module";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import {
+  DEFAULT_STREAM_ENCODER_SETTINGS,
+  type StreamEncoderSettings,
+} from "./stream-settings";
+
+const require = createRequire(import.meta.url);
+
+// The addon exposes two NodeClasses (SimHID, SimCapture) plus two async
+// functions. NodeClass instances clean up their native resources when the JS
+// handle is garbage-collected (Swift `deinit`), so there are no explicit
+// destroy/free calls here.
+interface SimHIDHandle {
+  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>;
+  buttonHid(page: number, usage: number, phase: ButtonPhase): Promise<void>;
+  key(type: KeyType, usage: number): Promise<void>;
+  scroll(dx: number, dy: number, anchorX: number, anchorY: number, w: number, hh: number): Promise<void>;
+  digitalCrown(delta: number): Promise<void>;
+  orientation(orientation: number): Promise<boolean>;
+  memoryWarning(): Promise<void>;
+  softwareKeyboard(): Promise<void>;
+  caDebug(name: string, enabled: boolean): Promise<boolean>;
+}
+
+interface SimCaptureHandle {
+  start(): Promise<void>;
+  updateStreamSettings(
+    mjpegFps: number,
+    mjpegQuality: number,
+    maxDimension: number,
+    h264Fps: number,
+    h264Bitrate: number,
+  ): Promise<void>;
+  handleWebRTCOffer(offerJson: string): Promise<string>;
+  closeWebRTCSession(sessionId: string): Promise<void>;
+  screenSize(): Promise<{ width: number; height: number }>;
+  stop(): Promise<void>;
+  subscribe(codec: number, onFrame: RawFrameCallback): Promise<NativeUnsubscribe>;
+}
+
+interface NativeAddon {
+  SimHID: new (udid: string) => SimHIDHandle;
+  SimCapture: new (
+    udid: string,
+    mjpegFps: number,
+    mjpegQuality: number,
+    maxDimension: number,
+    h264Fps: number,
+    h264Bitrate: number,
+  ) => SimCaptureHandle;
+  axDescribe(udid: string): Promise<string>;
+  axFrontmost(udid: string): Promise<string>;
+}
+
+// (codec, data, width, height, flags) — codec 0=MJPEG 1=AVCC; flags bit0=desc bit1=keyframe.
+type RawFrameCallback = (
+  data: Uint8Array,
+  width: number,
+  height: number,
+  flags: number,
+) => Promise<void>;
+
+const CODEC_MJPEG = 0;
+const CODEC_AVCC = 1;
+const FLAG_DESCRIPTION = 1 << 0;
+const FLAG_KEYFRAME = 1 << 1;
+
+export type MjpegFrame = {
+  data: Uint8Array;
+  width: number;
+  height: number;
+};
+
+export type AvccFrame = {
+  data: Uint8Array;
+  width: number;
+  height: number;
+  isDescription: boolean;
+  isKeyframe: boolean;
+};
+
+export type NativeCaptureOptions = StreamEncoderSettings;
+
+export type NativeUnsubscribe = () => Promise<void>;
+
+export type TouchType = "begin" | "move" | "end";
+export type KeyType = "down" | "up";
+export type ButtonPhase = "down" | "up" | "press";
+
+/** UIDeviceOrientation values the simulator's GraphicsServices accepts. */
+export const Orientation = {
+  portrait: 1,
+  portraitUpsideDown: 2,
+  landscapeRight: 3,
+  landscapeLeft: 4,
+} as const;
+
+function resolveAddon(): string {
+  const candidates = [
+    // Beside the bun-compiled executable (dist/serve-sim → dist/native/…).
+    // Arm64 macOS addon; loaded by path so it works under npx, the
+    // compiled binary, and the dev server alike.
+    join(dirname(process.execPath), "native", "serve-sim-native.node"),
+    // Beside the bundled JS (dist/serve-sim.js or dist/middleware.js).
+    join(dirname(fileURLToPath(import.meta.url)), "native", "serve-sim-native.node"),
+    // Dev: running from source (src/native.ts → ../dist/native/…).
+    join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "native", "serve-sim-native.node"),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    `serve-sim-native.node not found. Looked in:\n  ${candidates.join("\n  ")}\n` +
+      "Run `bun run build.ts` to build the native addon.",
+  );
+}
+
+let addon: NativeAddon | undefined;
+function load(): NativeAddon {
+  if (!addon) addon = require(resolveAddon()) as NativeAddon;
+  return addon;
+}
+
+/**
+ * In-process HID injector for one simulator. Mirrors the WebSocket HID protocol
+ * the spawned helper used to handle, but as direct native calls.
+ */
+export class NativeHid {
+  private readonly handle: SimHIDHandle;
+
+  constructor(udid: string) {
+    this.handle = new (load().SimHID)(udid);
+  }
+
+  // The N-API bindings throw synchronously when a JS value can't be coerced to
+  // the native parameter type (e.g. a touch with a non-string `type` →
+  // "Could not convert parameter 0 to type String"). HID now runs in-process,
+  // so an unhandled throw here crashes the whole server — and if it lands
+  // mid-gesture, the guest is left with a stuck finger that wedges input until
+  // 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> {
+    try {
+      return await fn();
+    } catch (err) {
+      console.error(`[hid] ${op} ignored bad input:`, err instanceof Error ? err.message : err);
+      return fallback;
+    }
+  }
+
+  touch(type: TouchType, x: number, y: number, w: number, h: number, edge = 0): Promise<void> {
+    return this.guard("touch", () => this.handle.touch(type, x, y, w, h, edge), undefined);
+  }
+
+  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);
+  }
+
+  button(button: string): Promise<void> {
+    return this.guard("button", () => this.handle.button(button), undefined);
+  }
+
+  buttonHid(page: number, usage: number, phase: ButtonPhase = "press"): Promise<void> {
+    return this.guard("buttonHid", () => this.handle.buttonHid(page, usage, phase), undefined);
+  }
+
+  key(type: KeyType, usage: number): Promise<void> {
+    return this.guard("key", () => this.handle.key(type, usage), undefined);
+  }
+
+  /** anchorX/anchorY default to screen center when omitted. */
+  scroll(dx: number, dy: number, w: number, h: number, anchorX?: number, anchorY?: number): Promise<void> {
+    return this.guard("scroll", () => this.handle.scroll(dx, dy, anchorX ?? NaN, anchorY ?? NaN, w, h), undefined);
+  }
+
+  digitalCrown(delta: number): Promise<void> {
+    return this.guard("digitalCrown", () => this.handle.digitalCrown(delta), undefined);
+  }
+
+  orientation(orientation: number): Promise<boolean> {
+    return this.guard("orientation", () => this.handle.orientation(orientation), false);
+  }
+
+  memoryWarning(): Promise<void> {
+    return this.guard("memoryWarning", () => this.handle.memoryWarning(), undefined);
+  }
+
+  softwareKeyboard(): Promise<void> {
+    return this.guard("softwareKeyboard", () => this.handle.softwareKeyboard(), undefined);
+  }
+
+  caDebug(name: string, enabled: boolean): Promise<boolean> {
+    return this.guard("caDebug", () => this.handle.caDebug(name, enabled), false);
+  }
+}
+
+/**
+ * In-process frame capture + encode for one simulator. Replaces the spawned
+ * helper's capture pipeline. MJPEG and H.264/AVCC frames are produced while
+ * callers hold codec-specific subscriptions; encoded frames arrive on the JS
+ * thread after being marshalled from the native encode thread.
+ */
+export class NativeCapture {
+  private readonly handle: SimCaptureHandle;
+
+  constructor(udid: string, options: NativeCaptureOptions = DEFAULT_STREAM_ENCODER_SETTINGS) {
+    this.handle = new (load().SimCapture)(
+      udid,
+      options.mjpegFps,
+      options.mjpegQuality,
+      options.maxDimension,
+      options.h264Fps,
+      options.h264Bitrate,
+    );
+  }
+
+  /** Begin capturing. Throws if the device isn't booted. */
+  start(): Promise<void> {
+    return this.handle.start();
+  }
+
+  updateStreamSettings(options: NativeCaptureOptions): Promise<void> {
+    return this.handle.updateStreamSettings(
+      options.mjpegFps,
+      options.mjpegQuality,
+      options.maxDimension,
+      options.h264Fps,
+      options.h264Bitrate,
+    );
+  }
+
+  subscribeMjpeg(onFrame: (frame: MjpegFrame) => Promise<void>): Promise<NativeUnsubscribe> {
+    return this.handle.subscribe(CODEC_MJPEG, (data, width, height, _flags) => {
+      return onFrame({ data, width, height });
+    });
+  }
+
+  subscribeAvcc(onFrame: (frame: AvccFrame) => Promise<void>): Promise<NativeUnsubscribe> {
+    return this.handle.subscribe(CODEC_AVCC, (data, width, height, flags) => {
+      return onFrame({
+        data,
+        width,
+        height,
+        isDescription: (flags & FLAG_DESCRIPTION) !== 0,
+        isKeyframe: (flags & FLAG_KEYFRAME) !== 0,
+      });
+    });
+  }
+
+  async handleWebRTCOffer(offer: unknown): Promise<unknown> {
+    return JSON.parse(await this.handle.handleWebRTCOffer(JSON.stringify(offer)));
+  }
+
+  closeWebRTCSession(sessionId: string): Promise<void> {
+    return this.handle.closeWebRTCSession(sessionId);
+  }
+
+  screenSize(): Promise<{ width: number; height: number }> {
+    return this.handle.screenSize();
+  }
+
+  /** Halt frame production. Full teardown happens when this object is GC'd. */
+  stop(): Promise<void> {
+    return this.handle.stop();
+  }
+}
+
+/**
+ * Async accessibility-tree dump for `udid`, as an axe-shaped JSON string (the
+ * src/ax.ts normalizer consumes it unchanged). Runs native AX work off the JS
+ * event loop. Rejects if the sim's AX service isn't reachable yet.
+ */
+export function axDescribeAsync(udid: string): Promise<string> {
+  return load().axDescribe(udid);
+}
+
+/** Async frontmost-app probe — JSON string `{ bundleId, pid }` for the visible app. */
+export function axFrontmostAsync(udid: string): Promise<string> {
+  return load().axFrontmost(udid);
+}

package/src/state.ts

@@ -0,0 +1,86 @@
+import { tmpdir } from "os";
+import { join } from "path";
+import { readdirSync, mkdirSync, writeFileSync, renameSync } from "fs";
+import type { StreamSettings } from "./stream-settings";
+export type {
+  HttpStreamCodec,
+  StreamSettings,
+  WebRtcIceServer,
+  WebRtcStreamCodec,
+} from "./stream-settings";
+
+/** Directory where serve-sim stores runtime state. */
+export const STATE_DIR = join(tmpdir(), "serve-sim");
+
+/** Path to the serve-sim server state file (JSON with pid, port, URLs).
+ *  @deprecated Use `stateFileForDevice(udid)` for multi-device support. Kept for backward compat. */
+export const STATE_FILE = join(STATE_DIR, "server.json");
+
+/** Per-device state file: `/tmp/serve-sim/server-{udid}.json` */
+export function stateFileForDevice(udid: string): string {
+  return join(STATE_DIR, `server-${udid}.json`);
+}
+
+/** Runtime record for a device streamed in-process by a preview server. */
+export interface ServeSimDeviceState {
+  pid: number;
+  port: number;
+  device: string;
+  url: string;
+  streamUrl: string;
+  wsUrl: string;
+  streamSettings?: StreamSettings;
+}
+
+/**
+ * Build the state for a device served in-process. There's no separate helper
+ * port — the URLs point at the preview server's own same-origin
+ * `{base}/helper/<device>/…` routes, which simMiddleware serves from a
+ * NativeCapture/NativeHid DeviceSession.
+ */
+export function inProcessServeSimState(
+  udid: string,
+  port: number,
+  base = "/",
+  host = "127.0.0.1",
+  streamSettings?: StreamSettings,
+): ServeSimDeviceState {
+  const h = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+  // Normalize to a leading-slash, no-trailing-slash prefix so a base without a
+  // leading slash (e.g. "foo") still yields well-formed `…:port/foo/helper/…`.
+  const trimmed = base.replace(/^\/+/, "").replace(/\/+$/, "");
+  const prefix = trimmed === "" ? "" : `/${trimmed}`;
+  return {
+    pid: process.pid,
+    port,
+    device: udid,
+    url: `http://${h}:${port}`,
+    streamUrl: `http://${h}:${port}${prefix}/helper/${udid}/stream.mjpeg`,
+    wsUrl: `ws://${h}:${port}${prefix}/helper/${udid}/ws`,
+    ...(streamSettings ? { streamSettings } : {}),
+  };
+}
+
+/** Persist a device's state so other processes / the grid can enumerate it.
+ *  Writes atomically (temp file + rename) so a concurrent reader never observes
+ *  a truncated or partially-written file. */
+export function writeServeSimState(state: ServeSimDeviceState): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const file = stateFileForDevice(state.device);
+  const tmp = `${file}.${process.pid}.tmp`;
+  // WebRTC state can contain short-lived TURN credentials. Keep the file
+  // readable only by the account running serve-sim.
+  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/** List all per-device state files in the state directory. */
+export function listStateFiles(): string[] {
+  try {
+    return readdirSync(STATE_DIR)
+      .filter((f) => f.startsWith("server-") && f.endsWith(".json"))
+      .map((f) => join(STATE_DIR, f));
+  } catch {
+    return [];
+  }
+}

package/src/stream-settings.ts

@@ -0,0 +1,202 @@
+export type HttpStreamCodec = "auto" | "mjpeg" | "h264";
+export type WebRtcStreamCodec = "vp8" | "vp9" | "h264";
+export type WebRtcIceServer = { urls: string[]; username?: string; credential?: string };
+
+export type StreamSettings =
+  | { transport: "http"; codec?: HttpStreamCodec }
+  | { transport: "webrtc"; codec: WebRtcStreamCodec; iceServers?: WebRtcIceServer[] };
+
+export interface StreamPlaybackSettings {
+  transport: "http" | "webrtc";
+  httpCodec: HttpStreamCodec;
+  webRtcCodec: WebRtcStreamCodec;
+  iceServers?: WebRtcIceServer[];
+}
+
+export interface StreamEncoderSettings {
+  mjpegFps: number;
+  mjpegQuality: number;
+  maxDimension: number;
+  h264Bitrate: number;
+  h264Fps: number;
+}
+
+export type StreamControlSettings = StreamPlaybackSettings & StreamEncoderSettings;
+
+export const DEFAULT_STREAM_ENCODER_SETTINGS: StreamEncoderSettings = {
+  mjpegFps: 60,
+  mjpegQuality: 0.7,
+  maxDimension: 0,
+  h264Bitrate: 6_000_000,
+  h264Fps: 60,
+};
+
+export const DEFAULT_STREAM_CONTROL_SETTINGS: StreamControlSettings = {
+  transport: "http",
+  httpCodec: "auto",
+  webRtcCodec: "h264",
+  ...DEFAULT_STREAM_ENCODER_SETTINGS,
+};
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function numberInRange(value: unknown, fallback: number, min: number, max: number): number {
+  const number = finiteNumber(value);
+  return number == null ? fallback : Math.min(max, Math.max(min, number));
+}
+
+function integerInRange(value: unknown, fallback: number, min: number, max: number): number {
+  return Math.round(numberInRange(value, fallback, min, max));
+}
+
+/** Invalid input returns null; an empty array is a valid explicit clear. */
+function normalizedIceServers(value: unknown): WebRtcIceServer[] | null {
+  if (!Array.isArray(value) || value.length > 16) return null;
+  const servers: WebRtcIceServer[] = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") return null;
+    const urls = (entry as { urls?: unknown }).urls;
+    if (
+      !Array.isArray(urls)
+      || urls.length === 0
+      || urls.length > 16
+      || !urls.every((url) =>
+        typeof url === "string"
+        && url.length <= 2_048
+        && /^(stun|stuns|turn|turns):/i.test(url)
+      )
+    ) {
+      return null;
+    }
+    const username = (entry as { username?: unknown }).username;
+    const credential = (entry as { credential?: unknown }).credential;
+    if (username !== undefined && typeof username !== "string") return null;
+    if (credential !== undefined && typeof credential !== "string") return null;
+    servers.push({
+      urls,
+      ...(typeof username === "string" ? { username } : {}),
+      ...(typeof credential === "string" ? { credential } : {}),
+    });
+  }
+  return servers;
+}
+
+const STREAM_ENCODER_SETTING_KEYS = new Set<keyof StreamEncoderSettings>([
+  "mjpegFps",
+  "mjpegQuality",
+  "maxDimension",
+  "h264Bitrate",
+  "h264Fps",
+]);
+
+/** Validate an untrusted PATCH body without silently accepting typos or wrong types. */
+export function parseStreamEncoderSettingsPatch(
+  input: unknown,
+): Partial<StreamEncoderSettings> | null {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const patch = input as Record<string, unknown>;
+  const keys = Object.keys(patch);
+  if (
+    keys.length === 0
+    || keys.some((key) => !STREAM_ENCODER_SETTING_KEYS.has(key as keyof StreamEncoderSettings))
+  ) {
+    return null;
+  }
+  for (const key of ["mjpegFps", "mjpegQuality", "maxDimension", "h264Bitrate", "h264Fps"] as const) {
+    if (key in patch && finiteNumber(patch[key]) == null) return null;
+  }
+  return patch as Partial<StreamEncoderSettings>;
+}
+
+export function normalizeStreamControlSettings(
+  input: Partial<StreamControlSettings> = {},
+  fallback: StreamControlSettings = DEFAULT_STREAM_CONTROL_SETTINGS,
+): StreamControlSettings {
+  const hasIceServers = Object.prototype.hasOwnProperty.call(input, "iceServers");
+  const normalized = hasIceServers ? normalizedIceServers(input.iceServers) : fallback.iceServers;
+  const iceServers = normalized === null
+    ? fallback.iceServers
+    : normalized && normalized.length > 0 ? normalized : undefined;
+  return {
+    transport: input.transport === "http" || input.transport === "webrtc"
+      ? input.transport
+      : fallback.transport,
+    httpCodec: input.httpCodec === "auto" || input.httpCodec === "mjpeg" || input.httpCodec === "h264"
+      ? input.httpCodec
+      : fallback.httpCodec,
+    webRtcCodec: input.webRtcCodec === "vp8" || input.webRtcCodec === "vp9" || input.webRtcCodec === "h264"
+      ? input.webRtcCodec
+      : fallback.webRtcCodec,
+    ...(iceServers ? { iceServers } : {}),
+    ...normalizeStreamEncoderSettings(input, fallback),
+  };
+}
+
+export function normalizeStreamEncoderSettings(
+  input: Partial<StreamEncoderSettings> = {},
+  fallback: StreamEncoderSettings = DEFAULT_STREAM_ENCODER_SETTINGS,
+): StreamEncoderSettings {
+  return {
+    mjpegFps: integerInRange(input.mjpegFps, fallback.mjpegFps, 1, 120),
+    mjpegQuality: numberInRange(input.mjpegQuality, fallback.mjpegQuality, 0.05, 1),
+    maxDimension: integerInRange(input.maxDimension, fallback.maxDimension, 0, 4096),
+    h264Bitrate: integerInRange(input.h264Bitrate, fallback.h264Bitrate, 100_000, 50_000_000),
+    h264Fps: integerInRange(input.h264Fps, fallback.h264Fps, 1, 120),
+  };
+}
+
+export function streamEncoderSettingsFrom(
+  settings: StreamControlSettings,
+): StreamEncoderSettings {
+  return {
+    mjpegFps: settings.mjpegFps,
+    mjpegQuality: settings.mjpegQuality,
+    maxDimension: settings.maxDimension,
+    h264Bitrate: settings.h264Bitrate,
+    h264Fps: settings.h264Fps,
+  };
+}
+
+export function streamControlSettingsFrom(
+  settings: StreamSettings | undefined,
+): StreamControlSettings {
+  if (settings?.transport === "webrtc") {
+    return normalizeStreamControlSettings({
+      transport: "webrtc",
+      webRtcCodec: settings.codec,
+      iceServers: settings.iceServers,
+    });
+  }
+  return normalizeStreamControlSettings({
+    transport: "http",
+    httpCodec: settings?.codec ?? "auto",
+  });
+}
+
+export function mergeStreamControlSettings(
+  current: StreamControlSettings,
+  patch: Partial<StreamControlSettings>,
+): StreamControlSettings {
+  return normalizeStreamControlSettings({ ...current, ...patch }, current);
+}
+
+/** Apply shared encoder controls without replacing viewer-local playback values. */
+export function mergeStreamEncoderSettings(
+  current: StreamControlSettings,
+  patch: Partial<StreamEncoderSettings>,
+): StreamControlSettings {
+  const previous = streamEncoderSettingsFrom(current);
+  const next = normalizeStreamEncoderSettings({ ...previous, ...patch }, previous);
+  if (
+    next.mjpegFps === previous.mjpegFps
+    && next.mjpegQuality === previous.mjpegQuality
+    && next.maxDimension === previous.maxDimension
+    && next.h264Bitrate === previous.h264Bitrate
+    && next.h264Fps === previous.h264Fps
+  ) {
+    return current;
+  }
+  return { ...current, ...next };
+}