serve-sim 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serve-sim",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "author": {
     "name": "Evan Bacon",
@@ -27,6 +27,8 @@
     "dist/serve-sim.js",
     "dist/middleware.js",
     "dist/middleware.cjs",
+    "src/ax-shared.ts",
+    "src/ax.ts",
     "src/middleware.ts",
     "src/state.ts",
     "bin/serve-sim-bin"

package/src/ax-shared.ts

@@ -0,0 +1,26 @@
+export const AXE_INSTALL_URL = "https://github.com/cameroncooke/AXe";
+export const AXE_NOT_INSTALLED_ERROR = `AXe is not installed. Install it from ${AXE_INSTALL_URL}.`;
+
+export interface AxRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface AxElement {
+  id: string;
+  path: string;
+  label: string;
+  value: string;
+  role: string;
+  type: string;
+  enabled: boolean;
+  frame: AxRect;
+}
+
+export interface AxSnapshot {
+  screen: { width: number; height: number };
+  elements: AxElement[];
+  errors?: string[];
+}

package/src/ax.ts

@@ -0,0 +1,223 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { AXE_NOT_INSTALLED_ERROR } from "./ax-shared";
+import type { AxElement, AxRect, AxSnapshot } from "./ax-shared";
+
+export type { AxElement, AxRect, AxSnapshot } from "./ax-shared";
+
+const SNAPSHOT_TIMEOUT_MS = 3500;
+const MAX_ELEMENTS = 500;
+const POLL_INTERVAL_MS = 500;
+const MAX_POLL_INTERVAL_MS = 2000;
+const UNAVAILABLE_RETRY_INTERVAL_MS = 15_000;
+const execFileAsync = promisify(execFile);
+
+interface RawAxeNode {
+  AXUniqueId: string | null;
+  AXLabel: string | null;
+  AXValue: string | null;
+  enabled: boolean;
+  frame: AxRect;
+  role_description: string;
+  type: string;
+  children: RawAxeNode[];
+}
+
+async function execFileText(command: string, args: string[]) {
+  const { stdout } = await execFileAsync(command, args, {
+    timeout: SNAPSHOT_TIMEOUT_MS,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return stdout.toString();
+}
+
+function chooseScreenFrame(roots: RawAxeNode[]) {
+  return roots[0]?.frame ?? {
+    x: 0,
+    y: 0,
+    width: 1,
+    height: 1,
+  };
+}
+
+function sameRect(a: AxRect, b: AxRect) {
+  return (
+    Math.abs(a.x - b.x) < 0.5 &&
+    Math.abs(a.y - b.y) < 0.5 &&
+    Math.abs(a.width - b.width) < 0.5 &&
+    Math.abs(a.height - b.height) < 0.5
+  );
+}
+
+function normalizeAxTree(roots: RawAxeNode[]): AxSnapshot {
+  const screen = chooseScreenFrame(roots);
+  const elements: AxElement[] = [];
+
+  const visit = (node: RawAxeNode, path: string) => {
+    if (elements.length >= MAX_ELEMENTS) return;
+
+    const frame = node.frame;
+    const isScreenSized = sameRect(frame, screen);
+
+    if (!isScreenSized) {
+      elements.push({
+        id: node.AXUniqueId ?? path,
+        path,
+        label: node.AXLabel ?? "",
+        value: node.AXValue ?? "",
+        role: node.role_description,
+        type: node.type,
+        enabled: node.enabled !== false,
+        frame,
+      });
+    }
+
+    for (let index = 0; index < node.children.length && elements.length < MAX_ELEMENTS; index++) {
+      visit(node.children[index], `${path}.${index}`);
+    }
+  };
+
+  for (let index = 0; index < roots.length && elements.length < MAX_ELEMENTS; index++) {
+    visit(roots[index], String(index));
+  }
+
+  return {
+    screen: {
+      width: screen.width,
+      height: screen.height,
+    },
+    elements,
+  };
+}
+
+async function snapshotWithAxe(udid: string) {
+  const output = await execFileText("axe", ["describe-ui", "--udid", udid]);
+  return normalizeAxTree(JSON.parse(output) as RawAxeNode[]);
+}
+
+function isAxeNotInstalledError(error: unknown) {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}
+
+function isAxeUnavailableSnapshot(snapshot: AxSnapshot | null) {
+  return snapshot?.errors?.includes(AXE_NOT_INSTALLED_ERROR) ?? false;
+}
+
+function isUsableAxSnapshot(snapshot: AxSnapshot) {
+  return (
+    snapshot.elements.length > 0 &&
+    snapshot.screen.width > 1 &&
+    snapshot.screen.height > 1
+  );
+}
+
+async function collectAxSnapshot(udid: string) {
+  const errors: string[] = [];
+
+  try {
+    const snapshot = await snapshotWithAxe(udid);
+    if (!isUsableAxSnapshot(snapshot)) {
+      throw new Error(
+        `axe returned ${snapshot.elements.length} elements in ${snapshot.screen.width}x${snapshot.screen.height} AX space`,
+      );
+    }
+    return {
+      ...snapshot,
+      errors,
+    };
+  } catch (error) {
+    const err = error as Error & { stderr?: string };
+    errors.push(
+      isAxeNotInstalledError(error)
+        ? AXE_NOT_INSTALLED_ERROR
+        : err.stderr || err.message || String(error),
+    );
+  }
+
+  return {
+    screen: { width: 1, height: 1 },
+    elements: [],
+    errors,
+  };
+}
+
+function sseMessage(payload: unknown) {
+  return `data: ${JSON.stringify(payload)}\n\n`;
+}
+
+function createAxStreamer({
+  udid,
+}: {
+  udid: string;
+}) {
+  const clients = new Set<{ write(chunk: string): void }>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let latestMessage: string | null = null;
+  let pollIntervalMs = POLL_INTERVAL_MS;
+  let polling = false;
+
+  const schedule = () => {
+    if (clients.size === 0 || timer) return;
+    timer = setTimeout(poll, pollIntervalMs);
+  };
+
+  const poll = async () => {
+    timer = null;
+    if (polling || clients.size === 0) {
+      schedule();
+      return;
+    }
+
+    polling = true;
+    try {
+      const next = await collectAxSnapshot(udid);
+      const nextMessage = sseMessage(next);
+      if (nextMessage !== latestMessage) {
+        for (const client of clients) client.write(nextMessage);
+        pollIntervalMs = POLL_INTERVAL_MS;
+      } else {
+        pollIntervalMs = Math.min(pollIntervalMs * 2, MAX_POLL_INTERVAL_MS);
+      }
+      latestMessage = nextMessage;
+      // Back off aggressively while axe is missing so we don't spawn a
+      // subprocess every 2s, but keep polling so we recover automatically
+      // once the user installs it.
+      if (isAxeUnavailableSnapshot(next)) {
+        pollIntervalMs = UNAVAILABLE_RETRY_INTERVAL_MS;
+      }
+    } finally {
+      polling = false;
+      schedule();
+    }
+  };
+
+  return {
+    addClient(res: { write(chunk: string): void }) {
+      clients.add(res);
+      if (latestMessage) res.write(latestMessage);
+      void poll();
+      return () => {
+        clients.delete(res);
+        if (clients.size === 0 && timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      };
+    },
+  };
+}
+
+export function createAxStreamerCache() {
+  const streamers = new Map<string, ReturnType<typeof createAxStreamer>>();
+
+  return {
+    get(udid: string) {
+      const existing = streamers.get(udid);
+      if (existing) return existing;
+
+      const streamer = createAxStreamer({ udid });
+      streamers.set(udid, streamer);
+      return streamer;
+    },
+  };
+}

package/src/middleware.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, existsSync, unlinkSync } from "fs";
 import { execSync, spawn, exec, execFile, type ChildProcess } from "child_process";
 import { tmpdir } from "os";
 import { join } from "path";
+import { createAxStreamerCache } from "./ax";
 
 // Injected at build time as a base64-encoded string via `define`
 declare const __PREVIEW_HTML_B64__: string;
@@ -16,6 +17,8 @@ export interface ServeSimState {
   wsUrl: string;
 }
 
+const axStreamerCache = createAxStreamerCache();
+
 // Known bundle IDs that are always React Native shells (used as a fallback
 // before the app-container path resolves, since simctl can lag after launch).
 const RN_BUNDLE_IDS = new Set<string>([
@@ -168,6 +171,7 @@ export interface SimMiddlewareOptions {
  *   GET  {basePath}         — the preview HTML page
  *   GET  {basePath}/api     — serve-sim state JSON
  *   GET  {basePath}/logs    — SSE stream of simctl logs
+ *   GET  {basePath}/ax      — SSE stream of normalized accessibility snapshots
  */
 export function simMiddleware(options?: SimMiddlewareOptions) {
   const base = (options?.basePath ?? "/.sim").replace(/\/+$/, "");
@@ -190,8 +194,10 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
         // and connects to the WS directly (WS has no CORS).
         const config = JSON.stringify({
           ...state,
+          basePath: base,
           logsEndpoint: endpoint(base, "/logs", state.device),
           appStateEndpoint: endpoint(base, "/appstate", state.device),
+          axEndpoint: endpoint(base, "/ax", state.device),
         });
         const configScript = `<script>window.__SIM_PREVIEW__=${config}</script>`;
         html = html.replace("<!--__SIM_PREVIEW_CONFIG__-->", configScript);
@@ -217,6 +223,28 @@ export function simMiddleware(options?: SimMiddlewareOptions) {
       return;
     }
 
+    // SSE: normalized accessibility snapshot stream
+    if (url === base + "/ax") {
+      const states = readServeSimStates();
+      const state = selectServeSimState(states, selectedDevice);
+      if (!state) {
+        res.writeHead(404);
+        res.end("No serve-sim device");
+        return;
+      }
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+      });
+      res.write(":\n\n");
+      const ax = axStreamerCache.get(state.device);
+      const removeClient = ax.addClient(res);
+      req.on("close", removeClient);
+      return;
+    }
+
     // POST /exec — run a shell command on the host. The preview server binds
     // to localhost only and is meant for local dev, so we shell through
     // /bin/sh and return stdout/stderr/exitCode.