driftx 0.1.0 → 0.1.2

package/dist/bin.js

@@ -3,10 +3,10 @@
 // src/cli.ts
 import { Command } from "commander";
 import { createRequire } from "module";
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync8, readdirSync as readdirSync2, symlinkSync, unlinkSync as unlinkSync3, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname4, join as join5, resolve } from "path";
-import { homedir } from "os";
-import { fileURLToPath } from "url";
+import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync10, readdirSync as readdirSync2, symlinkSync, unlinkSync as unlinkSync3, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname5, join as join7, resolve as resolve2 } from "path";
+import { homedir as homedir2 } from "os";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/shell.ts
 import { execFile } from "child_process";
@@ -14,7 +14,7 @@ var RealShell = class {
   async exec(cmd, args, options) {
     const controller = new AbortController();
     const timeout = options?.timeout;
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const child = execFile(
         cmd,
         args,
@@ -27,7 +27,7 @@ var RealShell = class {
           if (error) {
             reject(error);
           } else {
-            resolve2({ stdout, stderr });
+            resolve3({ stdout, stderr });
           }
         }
       );
@@ -120,6 +120,7 @@ var configSchema = z.object({
   regionMergeGap: z.number().int().nonnegative().optional(),
   regionMinArea: z.number().int().nonnegative().optional(),
   diffMaskColor: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+  companionPort: z.number().int().positive().optional(),
   analyses: analysesSchema
 });
 var DEFAULTS = {
@@ -145,6 +146,7 @@ var DEFAULTS = {
   regionMergeGap: 8,
   regionMinArea: 100,
   diffMaskColor: [255, 0, 0, 128],
+  companionPort: 8300,
   analyses: {
     default: [],
     disabled: [],
@@ -160,6 +162,7 @@ function parseConfig(raw) {
   return {
     ...defaults,
     ...parsed,
+    companionPort: parsed.companionPort ?? defaults.companionPort,
     viewport: { ...defaults.viewport, ...parsed.viewport },
     timeouts: { ...defaults.timeouts, ...parsed.timeouts },
     retry: { ...defaults.retry, ...parsed.retry },
@@ -249,14 +252,14 @@ async function checkOne(spec, shell) {
 }
 async function checkMetro(port) {
   try {
-    const { default: http2 } = await import("http");
-    const status = await new Promise((resolve2, reject) => {
-      const req = http2.get(`http://localhost:${port}/status`, { timeout: 2e3 }, (res) => {
+    const { default: http3 } = await import("http");
+    const status = await new Promise((resolve3, reject) => {
+      const req = http3.get(`http://localhost:${port}/status`, { timeout: 2e3 }, (res) => {
         let data = "";
         res.on("data", (chunk) => {
           data += chunk;
         });
-        res.on("end", () => resolve2(data));
+        res.on("end", () => resolve3(data));
       });
       req.on("error", reject);
       req.on("timeout", () => {
@@ -523,7 +526,7 @@ function isScreenSettled(buf1, buf2, maxDelta) {
   return diffPixels / totalPixels <= maxDelta;
 }
 function delay(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function captureScreenshot(shell, device, options) {
   const logger = getLogger();
@@ -622,12 +625,12 @@ function isRetryable(error, policy) {
   return policy.retryableErrors.some((pattern) => error.message.includes(pattern));
 }
 function delay2(ms, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (signal?.aborted) {
       reject(new Error("Aborted"));
       return;
     }
-    const timer = setTimeout(resolve2, ms);
+    const timer = setTimeout(resolve3, ms);
     signal?.addEventListener("abort", () => {
       clearTimeout(timer);
       reject(new Error("Aborted"));
@@ -667,6 +670,13 @@ async function withRetry(fn, policy, signal) {
 import { select } from "@inquirer/prompts";
 async function pickDevice(booted) {
   if (booted.length === 1) return booted[0];
+  if (!process.stdout.isTTY) {
+    const list = booted.map((d) => `  - "${d.name}" (${d.platform}, ${d.id})`).join("\n");
+    throw new Error(
+      `Multiple booted devices found. Use --device to specify one:
+${list}`
+    );
+  }
   const selected = await select({
     message: "Select a device",
     choices: booted.map((d) => ({
@@ -901,8 +911,133 @@ var FIBER_WALK_SCRIPT = `(function() {
     }
   }
 })()`;
+var MEASURE_FIND_SCRIPT = (text) => `(function() {
+  try {
+    globalThis.__driftx_measure = null;
+    var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook || !hook.renderers) return JSON.stringify({error: "no hook"});
+    var targetText = ${JSON.stringify(text)};
+    var found = null;
+    function searchFiber(fiber) {
+      if (!fiber || found) return;
+      var props = fiber.memoizedProps || {};
+      if (typeof props.children === 'string' && props.children === targetText) { found = fiber; return; }
+      var child = fiber.child;
+      while (child) { searchFiber(child); child = child.sibling; }
+    }
+    hook.renderers.forEach(function(renderer, id) {
+      var roots = hook.getFiberRoots(id);
+      if (!roots) return;
+      roots.forEach(function(root) { if (root.current) searchFiber(root.current); });
+    });
+    if (!found) return JSON.stringify({error: "not found"});
+    var host = found;
+    while (host) {
+      if (host.tag === 5 && host.stateNode != null) break;
+      host = host.return;
+    }
+    if (!host || !host.stateNode) return JSON.stringify({error: "no host"});
+    var sn = host.stateNode;
+    if (typeof sn.measureInWindow === 'function') {
+      sn.measureInWindow(function(x, y, w, h) {
+        globalThis.__driftx_measure = {x: x, y: y, width: w, height: h};
+      });
+      return JSON.stringify({status: "measuring"});
+    }
+    return JSON.stringify({error: "no measureInWindow"});
+  } catch(e) { return JSON.stringify({error: e.message}); }
+})()`;
+var MEASURE_READ_SCRIPT = `(function() {
+  var r = globalThis.__driftx_measure;
+  globalThis.__driftx_measure = null;
+  return r ? JSON.stringify(r) : JSON.stringify(null);
+})()`;
+async function measureElementByText(metroPort, text, deviceName, timeoutMs = 1e4) {
+  const logger = getLogger();
+  const targets = await discoverTargets(metroPort);
+  const target = findRuntimeTarget(targets, deviceName);
+  if (!target) return null;
+  return new Promise((resolve3) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve3(null);
+    }, timeoutMs);
+    let ws;
+    function cleanup() {
+      try {
+        ws?.close();
+      } catch {
+      }
+    }
+    try {
+      ws = new WebSocket(target.webSocketDebuggerUrl);
+    } catch {
+      clearTimeout(timer);
+      return resolve3(null);
+    }
+    ws.on("open", () => {
+      ws.send(JSON.stringify({
+        id: 1,
+        method: "Runtime.evaluate",
+        params: { expression: MEASURE_FIND_SCRIPT(text), returnByValue: true }
+      }));
+    });
+    ws.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg.id === 1) {
+          const val = msg.result?.result?.value;
+          if (typeof val === "string") {
+            const parsed = JSON.parse(val);
+            if (parsed?.status === "measuring") {
+              setTimeout(() => {
+                ws.send(JSON.stringify({
+                  id: 2,
+                  method: "Runtime.evaluate",
+                  params: { expression: MEASURE_READ_SCRIPT, returnByValue: true }
+                }));
+              }, 200);
+              return;
+            }
+          }
+          clearTimeout(timer);
+          cleanup();
+          resolve3(null);
+        }
+        if (msg.id === 2) {
+          clearTimeout(timer);
+          const val = msg.result?.result?.value;
+          if (typeof val === "string") {
+            const parsed = JSON.parse(val);
+            if (parsed && typeof parsed.x === "number" && parsed.width > 0) {
+              logger.debug(`CDP measure '${text}': ${JSON.stringify(parsed)}`);
+              cleanup();
+              return resolve3(parsed);
+            }
+          }
+          cleanup();
+          resolve3(null);
+        }
+      } catch {
+      }
+    });
+    ws.on("error", () => {
+      clearTimeout(timer);
+      cleanup();
+      resolve3(null);
+    });
+  });
+}
+async function detectBundleId(metroPort, deviceName) {
+  const targets = await discoverTargets(metroPort);
+  const target = findRuntimeTarget(targets, deviceName);
+  if (!target) return null;
+  if (target.appId) return target.appId;
+  if (target.description && /^[a-zA-Z][a-zA-Z0-9._-]+$/.test(target.description)) return target.description;
+  return null;
+}
 async function discoverTargets(metroPort) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const req = http.get(`http://localhost:${metroPort}/json/list`, { timeout: 2e3 }, (res) => {
       let data = "";
       res.on("data", (chunk) => {
@@ -910,23 +1045,21 @@ async function discoverTargets(metroPort) {
       });
       res.on("end", () => {
         try {
-          resolve2(JSON.parse(data));
+          resolve3(JSON.parse(data));
         } catch {
-          resolve2([]);
+          resolve3([]);
         }
       });
     });
-    req.on("error", () => resolve2([]));
+    req.on("error", () => resolve3([]));
     req.on("timeout", () => {
       req.destroy();
-      resolve2([]);
+      resolve3([]);
     });
   });
 }
 function findRuntimeTarget(targets, deviceName) {
-  const rnTargets = targets.filter(
-    (t) => t.reactNative && t.description.includes("React Native")
-  );
+  const rnTargets = targets.filter((t) => !!t.reactNative);
   if (deviceName) {
     return rnTargets.find(
       (t) => t.deviceName?.toLowerCase().includes(deviceName.toLowerCase())
@@ -948,16 +1081,16 @@ var CdpClient = class {
       return [];
     }
     logger.debug(`Found CDP target: ${target.title} (${target.description})`);
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const timer = setTimeout(() => {
         this.cleanup();
-        resolve2([]);
+        resolve3([]);
       }, timeoutMs);
       try {
         this.ws = new WebSocket(target.webSocketDebuggerUrl);
       } catch {
         clearTimeout(timer);
-        resolve2([]);
+        resolve3([]);
         return;
       }
       this.ws.on("open", async () => {
@@ -965,10 +1098,10 @@ var CdpClient = class {
         try {
           const result = await this.evaluate(FIBER_WALK_SCRIPT);
           clearTimeout(timer);
-          resolve2(this.parseResult(result));
+          resolve3(this.parseResult(result));
         } catch {
           clearTimeout(timer);
-          resolve2([]);
+          resolve3([]);
         }
       });
       this.ws.on("message", (data) => {
@@ -986,7 +1119,7 @@ var CdpClient = class {
       });
       this.ws.on("error", () => {
         clearTimeout(timer);
-        resolve2([]);
+        resolve3([]);
       });
       this.ws.on("close", () => {
         this.connected = false;
@@ -995,8 +1128,8 @@ var CdpClient = class {
   }
   evaluate(expression) {
     const id = ++this.msgId;
-    return new Promise((resolve2, reject) => {
-      this.pending.set(id, { resolve: resolve2, reject });
+    return new Promise((resolve3, reject) => {
+      this.pending.set(id, { resolve: resolve3, reject });
       this.ws.send(JSON.stringify({
         id,
         method: "Runtime.evaluate",
@@ -1163,13 +1296,56 @@ var StrategyCache = class {
   }
 };
 
+// src/ios-companion/hierarchy-parser.ts
+function cleanElementType(elementType) {
+  const prefix = "XCUIElementType";
+  if (elementType.startsWith(prefix)) {
+    return elementType.slice(prefix.length);
+  }
+  return elementType.charAt(0).toUpperCase() + elementType.slice(1);
+}
+function isZeroSize(frame) {
+  return frame.width === 0 && frame.height === 0;
+}
+function convertNode(node, idCounter) {
+  const children = [];
+  for (const child of node.children) {
+    const converted = convertNode(child, idCounter);
+    if (converted) children.push(converted);
+  }
+  if (children.length === 0 && isZeroSize(node.frame)) {
+    return null;
+  }
+  return {
+    id: String(idCounter.n++),
+    name: cleanElementType(node.elementType),
+    nativeName: node.elementType,
+    testID: node.identifier || void 0,
+    bounds: { x: node.frame.x, y: node.frame.y, width: node.frame.width, height: node.frame.height },
+    text: node.label || void 0,
+    children,
+    inspectionTier: "basic"
+  };
+}
+function parseCompanionHierarchy(nodes) {
+  const idCounter = { n: 0 };
+  const result = [];
+  for (const node of nodes) {
+    const converted = convertNode(node, idCounter);
+    if (converted) result.push(converted);
+  }
+  return result;
+}
+
 // src/inspect/tree-inspector.ts
 var TreeInspector = class {
   shell;
   fileCache;
-  constructor(shell, projectRoot) {
+  companionLauncher;
+  constructor(shell, projectRoot, companionLauncher) {
     this.shell = shell;
     this.fileCache = projectRoot ? new StrategyCache(projectRoot) : null;
+    this.companionLauncher = companionLauncher ?? null;
   }
   invalidateCache(deviceId) {
     if (!this.fileCache) return;
@@ -1195,6 +1371,9 @@ var TreeInspector = class {
     if (device.platform === "android") {
       return { method: "uiautomator", reason: "Android native inspection" };
     }
+    if (this.companionLauncher) {
+      return { method: "xcuitest", reason: "iOS native inspection via XCUITest companion" };
+    }
     return { method: "idb", reason: "iOS native inspection via idb" };
   }
   async inspect(device, options) {
@@ -1252,13 +1431,30 @@ var TreeInspector = class {
         logger.debug(`UIAutomator failed: ${err instanceof Error ? err.message : err}`);
       }
     }
-    if (strategy.method === "idb" || strategy.method === "cdp" && device.platform === "ios") {
+    if (strategy.method === "xcuitest" || strategy.method === "cdp" && device.platform === "ios" && this.companionLauncher) {
+      try {
+        const client = await this.companionLauncher.ensureRunning(device.id, options.bundleId);
+        const rawNodes = await client.hierarchy();
+        const tree = parseCompanionHierarchy(rawNodes);
+        logger.debug(`xcuitest: got ${tree.length} root nodes for ${device.name}`);
+        return {
+          ...base,
+          strategy: { method: "xcuitest", reason: strategy.method === "cdp" ? "CDP fallback to native" : strategy.reason },
+          tree,
+          capabilities: { tree: "basic", sourceMapping: "none", styles: "none", protocol: "xcuitest" },
+          hints
+        };
+      } catch (err) {
+        logger.debug(`XCUITest companion failed: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+    if (strategy.method === "idb" || strategy.method === "cdp" && device.platform === "ios" || strategy.method === "xcuitest") {
       try {
         const tree = await dumpIosAccessibility(this.shell, device.id, options.timeoutMs);
         logger.debug(`idb: got ${tree.length} root nodes for ${device.name}`);
         return {
           ...base,
-          strategy: { method: "idb", reason: strategy.method === "cdp" ? "CDP fallback to native" : strategy.reason },
+          strategy: { method: "idb", reason: strategy.method === "xcuitest" ? "XCUITest fallback to idb" : strategy.method === "cdp" ? "CDP fallback to native" : strategy.reason },
           tree,
           capabilities: { tree: "basic", sourceMapping: "none", styles: "none", protocol: "idb" },
           hints
@@ -2318,12 +2514,12 @@ async function copyToClipboard(text) {
     logger.debug(`Clipboard not supported on ${process.platform}`);
     return;
   }
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const proc = exec(cmd, (err) => {
       if (err) {
         logger.debug(`Clipboard copy failed: ${err.message}`);
       }
-      resolve2();
+      resolve3();
     });
     proc.stdin?.write(text);
     proc.stdin?.end();
@@ -2563,35 +2759,35 @@ var AndroidBackend = class {
 
 // src/interact/ios.ts
 var IosBackend = class {
-  constructor(shell) {
+  constructor(shell, companion) {
     this.shell = shell;
+    this.companion = companion;
   }
-  async tap(device, point) {
-    await this.simctlIo(device, ["tap", String(point.x), String(point.y)]);
+  async tap(_device, point) {
+    await this.companion.tap(point.x, point.y);
   }
-  async longPress(device, point, _durationMs) {
-    await this.simctlIo(device, ["longpress", String(point.x), String(point.y)]);
+  async longPress(_device, point, durationMs) {
+    await this.companion.longPress(point.x, point.y, durationMs);
   }
-  async swipe(device, from, to, _durationMs) {
-    await this.simctlIo(device, ["swipe", String(from.x), String(from.y), String(to.x), String(to.y)]);
+  async swipe(_device, from, to, durationMs) {
+    await this.companion.swipe(from.x, from.y, to.x, to.y, durationMs);
   }
-  async type(device, text) {
-    await this.simctlIo(device, ["type", text]);
+  async type(_device, text) {
+    await this.companion.type(text);
   }
-  async keyEvent(device, key) {
-    await this.simctlIo(device, ["sendkey", key]);
+  async keyEvent(_device, key) {
+    await this.companion.keyEvent(key);
   }
   async openUrl(device, url) {
     await this.shell.exec("xcrun", ["simctl", "openurl", device.id, url]);
   }
-  async simctlIo(device, args) {
-    await this.shell.exec("xcrun", ["simctl", "io", device.id, ...args]);
-  }
 };
 
 // src/interact/backend.ts
-function createBackend(shell, platform) {
-  return platform === "android" ? new AndroidBackend(shell) : new IosBackend(shell);
+function createBackend(shell, platform, companion) {
+  if (platform === "android") return new AndroidBackend(shell);
+  if (!companion) throw new Error("iOS interactions require the XCUITest companion. Run on a simulator with Xcode installed.");
+  return new IosBackend(shell, companion);
 }
 
 // src/interact/resolver.ts
@@ -2603,6 +2799,17 @@ function resolveTarget(tree, query) {
   if (byName) return centerOf(byName, `name:${query}`);
   const byText = nodes.find((n) => n.text === query && hasSize(n));
   if (byText) return centerOf(byText, `text:${query}`);
+  const lowerQuery = query.toLowerCase();
+  const startsWithMatches = nodes.filter(
+    (n) => n.text && hasSize(n) && (n.text.toLowerCase().startsWith(lowerQuery + ",") || n.text.toLowerCase().startsWith(lowerQuery + " "))
+  );
+  const byTextStartsWith = smallest(startsWithMatches);
+  if (byTextStartsWith) return centerOf(byTextStartsWith, `text~:${query}`);
+  const containsMatches = nodes.filter(
+    (n) => n.text && hasSize(n) && n.text.toLowerCase().includes(lowerQuery)
+  );
+  const byTextContains = smallest(containsMatches);
+  if (byTextContains) return centerOf(byTextContains, `text~:${query}`);
   return null;
 }
 function flattenTree(nodes) {
@@ -2618,6 +2825,13 @@ function flattenTree(nodes) {
 function hasSize(node) {
   return node.bounds.width > 0 && node.bounds.height > 0;
 }
+function area(node) {
+  return node.bounds.width * node.bounds.height;
+}
+function smallest(nodes) {
+  if (nodes.length === 0) return void 0;
+  return nodes.reduce((best, n) => area(n) < area(best) ? n : best);
+}
 function centerOf(node, resolvedFrom) {
   return {
     x: Math.round(node.bounds.x + node.bounds.width / 2),
@@ -2667,13 +2881,15 @@ var GestureExecutor = class {
       return { success: false, action: "longPress", durationMs: Date.now() - start, error: String(e) };
     }
   }
-  async swipe(device, direction, distance = 600, durationMs = 300) {
+  async swipe(device, direction, distance, durationMs = 300) {
     const start = Date.now();
     try {
-      const cx = device.screenSize?.width ? Math.round(device.screenSize.width / 2) : 540;
-      const cy = device.screenSize?.height ? Math.round(device.screenSize.height / 2) : 960;
+      const isIos = device.platform === "ios";
+      const cx = device.screenSize?.width ? Math.round(device.screenSize.width / 2) : isIos ? 197 : 540;
+      const cy = device.screenSize?.height ? Math.round(device.screenSize.height / 2) : isIos ? 426 : 960;
+      const actualDistance = distance ?? (isIos ? 300 : 600);
       const from = { x: cx, y: cy };
-      const half = Math.round(distance / 2);
+      const half = Math.round(actualDistance / 2);
       const to = direction === "up" ? { x: cx, y: cy - half } : direction === "down" ? { x: cx, y: cy + half } : direction === "left" ? { x: cx - half, y: cy } : { x: cx + half, y: cy };
       await this.backend.swipe(device, from, to, durationMs);
       return { success: true, action: "swipe", durationMs: Date.now() - start };
@@ -2716,6 +2932,470 @@ var GestureExecutor = class {
   }
 };
 
+// src/ios-companion/launcher.ts
+import { spawn } from "child_process";
+import { resolve, dirname as dirname4, join as join5 } from "path";
+import { fileURLToPath } from "url";
+import { existsSync as existsSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { tmpdir as tmpdir3 } from "os";
+
+// src/ios-companion/client.ts
+import http2 from "http";
+var CompanionClient = class {
+  constructor(port) {
+    this.port = port;
+  }
+  async status() {
+    return this.request("GET", "/status");
+  }
+  async configure(bundleId) {
+    await this.request("POST", "/configure", { bundleId }, 3e4);
+  }
+  async tap(x, y) {
+    await this.request("POST", "/tap", { x, y });
+  }
+  async longPress(x, y, durationMs) {
+    await this.request("POST", "/longPress", { x, y, durationMs });
+  }
+  async swipe(fromX, fromY, toX, toY, durationMs) {
+    await this.request("POST", "/swipe", { fromX, fromY, toX, toY, durationMs });
+  }
+  async type(text) {
+    await this.request("POST", "/type", { text });
+  }
+  async keyEvent(key) {
+    await this.request("POST", "/keyEvent", { key });
+  }
+  async find(text) {
+    try {
+      const res = await this.request("POST", "/find", { text }, 3e4);
+      const frame = res.frame;
+      return frame ?? null;
+    } catch {
+      return null;
+    }
+  }
+  async hierarchy() {
+    return this.requestRaw("GET", "/hierarchy", void 0, 3e4);
+  }
+  requestRaw(method, path6, body, timeoutMs = 1e4) {
+    return new Promise((resolve3, reject) => {
+      const payload = body !== void 0 ? JSON.stringify(body) : void 0;
+      const req = http2.request(
+        {
+          hostname: "localhost",
+          port: this.port,
+          path: path6,
+          method,
+          timeout: timeoutMs,
+          headers: payload ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) } : void 0
+        },
+        (res) => {
+          let data = "";
+          res.on("data", (chunk) => {
+            data += chunk;
+          });
+          res.on("end", () => {
+            if (res.statusCode !== 200) {
+              reject(new Error(`Companion ${method} ${path6} returned ${res.statusCode}: ${data}`));
+              return;
+            }
+            try {
+              resolve3(JSON.parse(data));
+            } catch {
+              reject(new Error(`Companion ${method} ${path6} returned invalid JSON: ${data}`));
+            }
+          });
+        }
+      );
+      req.on("error", (err) => reject(new Error(`Companion ${method} ${path6}: ${err.message}`)));
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error(`Companion ${method} ${path6} timed out after ${timeoutMs}ms`));
+      });
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+  request(method, path6, body, timeoutMs = 3e4) {
+    return new Promise((resolve3, reject) => {
+      const payload = body !== void 0 ? JSON.stringify(body) : void 0;
+      const req = http2.request(
+        {
+          hostname: "localhost",
+          port: this.port,
+          path: path6,
+          method,
+          timeout: timeoutMs,
+          headers: payload ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) } : void 0
+        },
+        (res) => {
+          let data = "";
+          res.on("data", (chunk) => {
+            data += chunk;
+          });
+          res.on("end", () => {
+            if (res.statusCode !== 200) {
+              reject(new Error(`Companion ${method} ${path6} returned ${res.statusCode}: ${data}`));
+              return;
+            }
+            let parsed;
+            try {
+              parsed = JSON.parse(data);
+            } catch {
+              reject(new Error(`Companion ${method} ${path6} returned invalid JSON: ${data}`));
+              return;
+            }
+            if (parsed.success === false) {
+              reject(new Error(`Companion ${method} ${path6} failed: ${parsed.error ?? "unknown error"}`));
+              return;
+            }
+            resolve3(parsed);
+          });
+        }
+      );
+      req.on("error", (err) => reject(new Error(`Companion ${method} ${path6}: ${err.message}`)));
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error(`Companion ${method} ${path6} timed out after ${timeoutMs}ms`));
+      });
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+};
+
+// src/ios-companion/xctestrun.ts
+function rewriteXctestrun(content, prebuiltDir, port) {
+  let result = content;
+  const rootMatch = result.match(/((?:__TESTROOT__|[^<\s]+?))\/Debug-/);
+  if (rootMatch) {
+    const originalRoot = rootMatch[1];
+    const escaped = originalRoot.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    result = result.replace(new RegExp(escaped, "g"), prebuiltDir);
+  }
+  const envTag = "<key>TestingEnvironmentVariables</key>";
+  const envIdx = result.indexOf(envTag);
+  if (envIdx !== -1) {
+    const dictOpenIdx = result.indexOf("<dict>", envIdx);
+    if (dictOpenIdx !== -1) {
+      const insertPos = dictOpenIdx + "<dict>".length;
+      const portEntry = `
+			<key>DRIFTX_PORT</key>
+			<string>${port}</string>`;
+      result = result.slice(0, insertPos) + portEntry + result.slice(insertPos);
+    }
+  } else {
+    const testConfigKey = "<key>DriftxCompanionUITests</key>";
+    const configIdx = result.indexOf(testConfigKey);
+    if (configIdx !== -1) {
+      const closingDict = result.indexOf("</dict>", configIdx);
+      if (closingDict !== -1) {
+        const envBlock = `		<key>TestingEnvironmentVariables</key>
+		<dict>
+			<key>DRIFTX_PORT</key>
+			<string>${port}</string>
+		</dict>
+	`;
+        result = result.slice(0, closingDict) + envBlock + result.slice(closingDict);
+      }
+    }
+  }
+  return result;
+}
+
+// src/ios-companion/launcher.ts
+var PKG_ROOT = resolve(dirname4(fileURLToPath(import.meta.url)), "..");
+var PREBUILT_DIR = join5(PKG_ROOT, "ios-companion", "prebuilt");
+var SOURCE_DIR = join5(PKG_ROOT, "ios-companion");
+var POLL_INTERVAL_MS = 500;
+var PREBUILT_LAUNCH_TIMEOUT_MS = 3e4;
+var SOURCE_LAUNCH_TIMEOUT_MS = 12e4;
+function resolveLaunchStrategy(input) {
+  if (input.localXcodeMajor === null && !input.prebuiltExists) {
+    return { type: "error", reason: "Xcode is required for iOS simulator support" };
+  }
+  if (!input.prebuiltExists) {
+    return { type: "source", sourceDir: input.sourceDir, reason: "prebuilt not found" };
+  }
+  if (input.buildInfoXcodeMajor === null) {
+    return { type: "source", sourceDir: input.sourceDir, reason: "build-info.json missing or invalid" };
+  }
+  if (input.localXcodeMajor !== null && input.buildInfoXcodeMajor !== input.localXcodeMajor) {
+    return {
+      type: "source",
+      sourceDir: input.sourceDir,
+      reason: `Xcode major version mismatch: prebuilt=${input.buildInfoXcodeMajor}, local=${input.localXcodeMajor}`
+    };
+  }
+  return { type: "prebuilt", prebuiltDir: input.prebuiltDir };
+}
+function readBuildInfo(prebuiltDir) {
+  try {
+    const raw = readFileSync8(join5(prebuiltDir, "build-info.json"), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function getLocalXcodeMajor() {
+  try {
+    const { execSync } = await import("child_process");
+    const output = execSync("xcodebuild -version", { encoding: "utf-8", timeout: 5e3 });
+    const match = output.match(/Xcode\s+(\d+)/);
+    return match ? parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}
+var CompanionLauncher = class {
+  processes = /* @__PURE__ */ new Map();
+  clients = /* @__PURE__ */ new Map();
+  portIndex = 0;
+  basePort;
+  constructor(basePort = 8300) {
+    this.basePort = basePort;
+    const cleanup = () => this.stop();
+    process.on("exit", cleanup);
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  }
+  async ensureRunning(deviceId, bundleId) {
+    const existing = this.clients.get(deviceId);
+    if (existing) {
+      try {
+        await existing.status();
+        return existing;
+      } catch {
+        this.clients.delete(deviceId);
+        this.killProcess(deviceId);
+      }
+    }
+    const port = this.getPort(deviceId);
+    const client = new CompanionClient(port);
+    try {
+      await client.status();
+      this.clients.set(deviceId, client);
+      return client;
+    } catch {
+    }
+    const logger = getLogger();
+    const buildInfo = readBuildInfo(PREBUILT_DIR);
+    const localXcodeMajor = await getLocalXcodeMajor();
+    const strategy = resolveLaunchStrategy({
+      prebuiltDir: PREBUILT_DIR,
+      prebuiltExists: existsSync6(join5(PREBUILT_DIR, "DriftxCompanionUITests.xctestrun")),
+      buildInfoXcodeMajor: buildInfo?.xcodeMajor ?? null,
+      localXcodeMajor,
+      sourceDir: SOURCE_DIR,
+      sourceExists: existsSync6(join5(SOURCE_DIR, "DriftxCompanion.xcodeproj"))
+    });
+    logger.debug(`Companion launch strategy: ${strategy.type}${strategy.reason ? ` (${strategy.reason})` : ""}`);
+    if (strategy.type === "error") {
+      throw new Error(strategy.reason ?? "Cannot launch iOS companion");
+    }
+    let launched = false;
+    if (strategy.type === "prebuilt") {
+      try {
+        this.launchPrebuilt(deviceId, port);
+        await this.waitForReadyWithEarlyExit(deviceId, client, PREBUILT_LAUNCH_TIMEOUT_MS);
+        launched = true;
+      } catch (err) {
+        logger.debug(`Pre-built launch failed, falling back to source: ${err}`);
+        this.killProcess(deviceId);
+      }
+    }
+    if (!launched) {
+      logger.debug(`Launching companion from source for device ${deviceId} on port ${port}`);
+      this.launchSource(deviceId, port);
+      await this.waitForReadyWithEarlyExit(deviceId, client, SOURCE_LAUNCH_TIMEOUT_MS);
+    }
+    if (bundleId) {
+      logger.debug(`Configuring companion for bundle ${bundleId}`);
+      await client.configure(bundleId);
+    }
+    this.clients.set(deviceId, client);
+    return client;
+  }
+  stop(deviceId) {
+    if (deviceId) {
+      this.killProcess(deviceId);
+      this.clients.delete(deviceId);
+      return;
+    }
+    for (const id of this.processes.keys()) {
+      this.killProcess(id);
+    }
+    this.clients.clear();
+  }
+  getPort(deviceId) {
+    const existing = [...this.processes.keys()].indexOf(deviceId);
+    if (existing >= 0) return this.basePort + existing;
+    return this.basePort + this.portIndex++;
+  }
+  launchPrebuilt(deviceId, port) {
+    const xctestrunPath = join5(PREBUILT_DIR, "DriftxCompanionUITests.xctestrun");
+    const original = readFileSync8(xctestrunPath, "utf-8");
+    const rewritten = rewriteXctestrun(original, PREBUILT_DIR, port);
+    const tmpXctestrun = join5(tmpdir3(), `driftx-companion-${deviceId}-${port}.xctestrun`);
+    writeFileSync4(tmpXctestrun, rewritten);
+    const proc = spawn("xcodebuild", [
+      "test-without-building",
+      "-xctestrun",
+      tmpXctestrun,
+      "-destination",
+      `platform=iOS Simulator,id=${deviceId}`,
+      "-only-testing:DriftxCompanionUITests/DriftxCompanionUITests/testCompanionServer"
+    ], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const logger = getLogger();
+    proc.stdout?.on("data", (data) => {
+      logger.debug(`[companion:${deviceId}] ${data.toString().trimEnd()}`);
+    });
+    proc.stderr?.on("data", (data) => {
+      logger.debug(`[companion:${deviceId}] ${data.toString().trimEnd()}`);
+    });
+    proc.on("exit", (code) => {
+      logger.debug(`Companion (prebuilt) for ${deviceId} exited with code ${code}`);
+      this.processes.delete(deviceId);
+    });
+    this.processes.set(deviceId, proc);
+  }
+  launchSource(deviceId, port) {
+    const env = { ...process.env, DRIFTX_PORT: String(port) };
+    const proc = spawn("xcodebuild", [
+      "test",
+      "-project",
+      resolve(SOURCE_DIR, "DriftxCompanion.xcodeproj"),
+      "-scheme",
+      "DriftxCompanionUITests",
+      "-destination",
+      `platform=iOS Simulator,id=${deviceId}`,
+      "-only-testing:DriftxCompanionUITests/DriftxCompanionUITests/testCompanionServer"
+    ], {
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const logger = getLogger();
+    proc.stdout?.on("data", (data) => {
+      logger.debug(`[companion:${deviceId}] ${data.toString().trimEnd()}`);
+    });
+    proc.stderr?.on("data", (data) => {
+      logger.debug(`[companion:${deviceId}] ${data.toString().trimEnd()}`);
+    });
+    proc.on("exit", (code) => {
+      logger.debug(`Companion (source) for ${deviceId} exited with code ${code}`);
+      this.processes.delete(deviceId);
+    });
+    this.processes.set(deviceId, proc);
+  }
+  async waitForReadyWithEarlyExit(deviceId, client, timeoutMs) {
+    const proc = this.processes.get(deviceId);
+    let earlyExitCode = null;
+    const exitListener = (code) => {
+      earlyExitCode = code;
+    };
+    proc?.on("exit", exitListener);
+    const deadline = Date.now() + timeoutMs;
+    try {
+      while (Date.now() < deadline) {
+        if (earlyExitCode !== null) {
+          throw new Error(`xcodebuild exited early with code ${earlyExitCode}`);
+        }
+        try {
+          await client.status();
+          return;
+        } catch {
+          await this.sleep(POLL_INTERVAL_MS);
+        }
+      }
+      throw new Error(`Companion server did not become ready within ${timeoutMs}ms`);
+    } finally {
+      proc?.removeListener("exit", exitListener);
+    }
+  }
+  killProcess(deviceId) {
+    const proc = this.processes.get(deviceId);
+    if (proc) {
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+      }
+      this.processes.delete(deviceId);
+    }
+  }
+  sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+  }
+};
+
+// src/update-notifier.ts
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync5, mkdirSync as mkdirSync4 } from "fs";
+import { join as join6 } from "path";
+import { homedir } from "os";
+var CACHE_DIR = join6(homedir(), ".driftx");
+var CACHE_FILE = join6(CACHE_DIR, "update-check.json");
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function shouldCheck(cache) {
+  if (!cache) return true;
+  return Date.now() - cache.lastCheck > CHECK_INTERVAL_MS;
+}
+function formatUpdateMessage(current, latest) {
+  if (compareVersions(current, latest) >= 0) return null;
+  return `  Update available: ${current} \u2192 ${latest}
+  Run: npm install -g driftx`;
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function readCache() {
+  try {
+    return JSON.parse(readFileSync9(CACHE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeCache(cache) {
+  try {
+    mkdirSync4(CACHE_DIR, { recursive: true });
+    writeFileSync5(CACHE_FILE, JSON.stringify(cache));
+  } catch {
+  }
+}
+async function fetchLatestVersion() {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3e3);
+    const res = await fetch("https://registry.npmjs.org/driftx/latest", { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+async function checkForUpdate(currentVersion) {
+  const cache = readCache();
+  if (!shouldCheck(cache)) {
+    return cache ? formatUpdateMessage(currentVersion, cache.latestVersion) : null;
+  }
+  fetchLatestVersion().then((latest) => {
+    if (latest) {
+      writeCache({ lastCheck: Date.now(), latestVersion: latest });
+    }
+  }).catch(() => {
+  });
+  return cache ? formatUpdateMessage(currentVersion, cache.latestVersion) : null;
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -2727,8 +3407,27 @@ function getFormatterContext(opts) {
   };
 }
 function createProgram() {
+  let companionLauncher;
+  let resolvedBundleId;
+  function getCompanionLauncher(port) {
+    if (!companionLauncher) {
+      companionLauncher = new CompanionLauncher(port);
+    }
+    return companionLauncher;
+  }
+  async function getBundleId(program2, metroPort, deviceName) {
+    const explicit = program2.opts().bundleId;
+    if (explicit) return explicit;
+    if (resolvedBundleId) return resolvedBundleId;
+    const detected = await detectBundleId(metroPort, deviceName);
+    if (detected) {
+      resolvedBundleId = detected;
+      getLogger().debug(`Auto-detected bundle ID: ${detected}`);
+    }
+    return resolvedBundleId;
+  }
   const program = new Command();
-  program.name("driftx").description("Visual diff tool for React Native and Android development").version(pkg.version).option("--verbose", "enable debug logging").option("--quiet", "suppress all output except errors").option("--format <type>", "output format: terminal, markdown, json", "terminal").option("--copy", "copy output to clipboard");
+  program.name("driftx").description("Visual diff tool for React Native and Android development").version(pkg.version).option("--verbose", "enable debug logging").option("--quiet", "suppress all output except errors").option("--format <type>", "output format: terminal, markdown, json", "terminal").option("--copy", "copy output to clipboard").option("--bundle-id <id>", "iOS app bundle identifier for companion");
   program.hook("preAction", (_thisCommand, actionCommand) => {
     const opts = actionCommand.optsWithGlobals();
     const level = opts.verbose ? "debug" : opts.quiet ? "silent" : "info";
@@ -2747,13 +3446,13 @@ function createProgram() {
     const files = readdirSync2(cwd);
     let packageJson;
     try {
-      packageJson = JSON.parse(readFileSync8(join5(cwd, "package.json"), "utf-8"));
+      packageJson = JSON.parse(readFileSync10(join7(cwd, "package.json"), "utf-8"));
     } catch {
     }
     const framework = detectFramework(files, packageJson);
     const config = generateConfig(framework);
-    const configPath = join5(cwd, ".driftxrc.json");
-    writeFileSync4(configPath, JSON.stringify(config, null, 2) + "\n");
+    const configPath = join7(cwd, ".driftxrc.json");
+    writeFileSync6(configPath, JSON.stringify(config, null, 2) + "\n");
     console.log(`Created ${configPath} (framework: ${framework})`);
   });
   program.command("devices").description("List connected devices and simulators").action(async function() {
@@ -2809,13 +3508,15 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const inspector = new TreeInspector(shell, process.cwd());
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const inspector = new TreeInspector(shell, process.cwd(), launcher);
+    const globalOpts = this.optsWithGlobals();
     const result = await inspector.inspect(device, {
       metroPort: config.metroPort,
       devToolsPort: config.devToolsPort,
-      timeoutMs: config.timeouts.treeInspectionMs
+      timeoutMs: config.timeouts.treeInspectionMs,
+      bundleId: await getBundleId(program, config.metroPort, device.name)
     });
-    const globalOpts = this.optsWithGlobals();
     if (opts.json) globalOpts.format = "json";
     const ctx = getFormatterContext(globalOpts);
     await formatOutput(inspectFormatter, result, ctx);
@@ -2834,20 +3535,46 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const backend = createBackend(shell, device.platform);
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const companion = launcher ? await launcher.ensureRunning(device.id, await getBundleId(program, config.metroPort, device.name)) : void 0;
+    const backend = createBackend(shell, device.platform, companion);
     const executor = new GestureExecutor(backend);
     let result;
     if (opts.xy) {
       const [x, y] = target.split(",").map(Number);
       result = await executor.tapXY(device, x, y);
     } else {
-      const inspector = new TreeInspector(shell, process.cwd());
+      const inspector = new TreeInspector(shell, process.cwd(), launcher);
       const inspectResult = await inspector.inspect(device, {
         metroPort: config.metroPort,
         devToolsPort: config.devToolsPort,
-        timeoutMs: config.timeouts.treeInspectionMs
+        timeoutMs: config.timeouts.treeInspectionMs,
+        bundleId: await getBundleId(program, config.metroPort, device.name)
       });
       result = await executor.tap(device, inspectResult.tree, target);
+      if (!result.success && result.error?.includes("Target not found") && companion) {
+        const rawNodes = await companion.hierarchy();
+        const companionTree = parseCompanionHierarchy(rawNodes);
+        result = await executor.tap(device, companionTree, target);
+      }
+      if (!result.success && result.error?.includes("Target not found") && companion) {
+        const frame = await companion.find(target);
+        if (frame) {
+          const cx = Math.round(frame.x + frame.width / 2);
+          const cy = Math.round(frame.y + frame.height / 2);
+          result = await executor.tapXY(device, cx, cy);
+          result.target = { x: cx, y: cy, resolvedFrom: `xcuitest-find:${target}` };
+        }
+      }
+      if (!result.success && result.error?.includes("Target not found")) {
+        const bounds = await measureElementByText(config.metroPort, target, device.name);
+        if (bounds) {
+          const cx = Math.round(bounds.x + bounds.width / 2);
+          const cy = Math.round(bounds.y + bounds.height / 2);
+          result = await executor.tapXY(device, cx, cy);
+          result.target = { x: cx, y: cy, resolvedFrom: `cdp-measure:${target}` };
+        }
+      }
     }
     console.log(JSON.stringify(result, null, 2));
   });
@@ -2865,19 +3592,38 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const inspector = new TreeInspector(shell, process.cwd());
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const companion = launcher ? await launcher.ensureRunning(device.id, await getBundleId(program, config.metroPort, device.name)) : void 0;
+    const inspector = new TreeInspector(shell, process.cwd(), launcher);
     const inspectResult = await inspector.inspect(device, {
       metroPort: config.metroPort,
       devToolsPort: config.devToolsPort,
-      timeoutMs: config.timeouts.treeInspectionMs
+      timeoutMs: config.timeouts.treeInspectionMs,
+      bundleId: await getBundleId(program, config.metroPort, device.name)
     });
-    const backend = createBackend(shell, device.platform);
+    const backend = createBackend(shell, device.platform, companion);
     const executor = new GestureExecutor(backend);
-    const result = await executor.typeInto(device, inspectResult.tree, target, text);
+    let result = await executor.typeInto(device, inspectResult.tree, target, text);
+    if (!result.success && result.error?.includes("Target not found") && companion) {
+      const rawNodes = await companion.hierarchy();
+      const companionTree = parseCompanionHierarchy(rawNodes);
+      result = await executor.typeInto(device, companionTree, target, text);
+    }
+    if (!result.success && result.error?.includes("Target not found") && companion) {
+      const frame = await companion.find(target);
+      if (frame) {
+        const cx = Math.round(frame.x + frame.width / 2);
+        const cy = Math.round(frame.y + frame.height / 2);
+        await backend.tap(device, { x: cx, y: cy });
+        await backend.type(device, text);
+        result = { success: true, action: "typeInto", target: { x: cx, y: cy, resolvedFrom: `xcuitest-find:${target}` }, durationMs: Date.now() };
+      }
+    }
     console.log(JSON.stringify(result, null, 2));
   });
-  program.command("swipe <direction>").description("Swipe up, down, left, or right").option("-d, --device <id>", "device ID or name").action(async (direction, opts) => {
+  program.command("swipe <direction>").description("Swipe up, down, left, or right").option("-d, --device <id>", "device ID or name").option("--distance <n>", "swipe distance in points", parseInt).action(async (direction, opts) => {
     const shell = new RealShell();
+    const config = await loadConfig();
     const discovery = new DeviceDiscovery(shell);
     const devices = await discovery.list();
     const booted = devices.filter((d) => d.state === "booted");
@@ -2889,13 +3635,16 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const backend = createBackend(shell, device.platform);
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const companion = launcher ? await launcher.ensureRunning(device.id, await getBundleId(program, config.metroPort, device.name)) : void 0;
+    const backend = createBackend(shell, device.platform, companion);
     const executor = new GestureExecutor(backend);
-    const result = await executor.swipe(device, direction);
+    const result = await executor.swipe(device, direction, opts.distance);
     console.log(JSON.stringify(result, null, 2));
   });
   program.command("go-back").description("Press the back button").option("-d, --device <id>", "device ID or name").action(async (opts) => {
     const shell = new RealShell();
+    const config = await loadConfig();
     const discovery = new DeviceDiscovery(shell);
     const devices = await discovery.list();
     const booted = devices.filter((d) => d.state === "booted");
@@ -2907,13 +3656,16 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const backend = createBackend(shell, device.platform);
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const companion = launcher ? await launcher.ensureRunning(device.id, await getBundleId(program, config.metroPort, device.name)) : void 0;
+    const backend = createBackend(shell, device.platform, companion);
     const executor = new GestureExecutor(backend);
     const result = await executor.goBack(device);
     console.log(JSON.stringify(result, null, 2));
   });
   program.command("open-url <url>").description("Open a deep link or URL on the device").option("-d, --device <id>", "device ID or name").action(async (url, opts) => {
     const shell = new RealShell();
+    const config = await loadConfig();
     const discovery = new DeviceDiscovery(shell);
     const devices = await discovery.list();
     const booted = devices.filter((d) => d.state === "booted");
@@ -2925,25 +3677,27 @@ function createProgram() {
     } else {
       device = await pickDevice(booted);
     }
-    const backend = createBackend(shell, device.platform);
+    const launcher = device.platform === "ios" ? getCompanionLauncher(config.companionPort) : void 0;
+    const companion = launcher ? await launcher.ensureRunning(device.id, await getBundleId(program, config.metroPort, device.name)) : void 0;
+    const backend = createBackend(shell, device.platform, companion);
     const executor = new GestureExecutor(backend);
     const result = await executor.openUrl(device, url);
     console.log(JSON.stringify(result, null, 2));
   });
   program.command("setup-claude").description("Register driftx as a Claude Code plugin").action(() => {
-    const claudeDir = join5(homedir(), ".claude");
-    const pluginsDir = join5(claudeDir, "plugins");
-    const driftxPluginDir = join5(pluginsDir, "driftx");
-    const registryPath = join5(pluginsDir, "installed_plugins.json");
-    const packageRoot = resolve(dirname4(fileURLToPath(import.meta.url)), "..");
-    const skillSource = join5(packageRoot, "driftx-plugin");
-    if (!existsSync6(skillSource)) {
+    const claudeDir = join7(homedir2(), ".claude");
+    const pluginsDir = join7(claudeDir, "plugins");
+    const driftxPluginDir = join7(pluginsDir, "driftx");
+    const registryPath = join7(pluginsDir, "installed_plugins.json");
+    const packageRoot = resolve2(dirname5(fileURLToPath2(import.meta.url)), "..");
+    const skillSource = join7(packageRoot, "driftx-plugin");
+    if (!existsSync7(skillSource)) {
       console.error(`driftx-plugin directory not found at ${skillSource}`);
       process.exitCode = 1;
       return;
     }
-    mkdirSync4(pluginsDir, { recursive: true });
-    if (existsSync6(driftxPluginDir)) {
+    mkdirSync5(pluginsDir, { recursive: true });
+    if (existsSync7(driftxPluginDir)) {
       try {
         unlinkSync3(driftxPluginDir);
       } catch {
@@ -2955,7 +3709,7 @@ function createProgram() {
     symlinkSync(skillSource, driftxPluginDir);
     let registry = { version: 2, plugins: {} };
     try {
-      registry = JSON.parse(readFileSync8(registryPath, "utf-8"));
+      registry = JSON.parse(readFileSync10(registryPath, "utf-8"));
     } catch {
     }
     registry.plugins["driftx@local"] = [{
@@ -2965,7 +3719,7 @@ function createProgram() {
       installedAt: (/* @__PURE__ */ new Date()).toISOString(),
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
     }];
-    writeFileSync4(registryPath, JSON.stringify(registry, null, 2));
+    writeFileSync6(registryPath, JSON.stringify(registry, null, 2));
     console.log("driftx registered as Claude Code plugin.");
     console.log(`  Symlink: ${driftxPluginDir} -> ${skillSource}`);
     console.log(`  Registry: ${registryPath}`);
@@ -2975,6 +3729,10 @@ function createProgram() {
 }
 function run(argv) {
   const program = createProgram();
+  checkForUpdate(pkg.version).then((msg) => {
+    if (msg) process.stderr.write(msg + "\n");
+  }).catch(() => {
+  });
   program.parseAsync(argv);
 }