@unotest/mobile 0.1.1 → 0.8.1

package/dist/runner/cli.js

@@ -17,7 +17,7 @@ __export(pg_client_exports, {
 async function create(databaseUrl) {
   const pgMod = await import("pg").catch(() => {
     throw new Error(
-      `'pg' driver requested by DATABASE_URL but the 'pg' package is not installed. Run: pnpm add -D pg @types/pg`
+      `'pg' driver requested by DATABASE_URL but the 'pg' package is not installed. Install it (npm i -D pg @types/pg, or your package manager's equivalent).`
     );
   });
   const PoolCtor = pgMod.default?.Pool ?? pgMod.Pool;
@@ -66,7 +66,7 @@ function isWriteSql(sql) {
 async function create2(databaseUrl) {
   const mod = await import("mysql2/promise").catch(() => {
     throw new Error(
-      `'mysql' driver requested by DATABASE_URL but the 'mysql2' package is not installed. Run: pnpm add -D mysql2`
+      `'mysql' driver requested by DATABASE_URL but the 'mysql2' package is not installed. Install it (npm i -D mysql2, or your package manager's equivalent).`
     );
   });
   const pool = mod.createPool(databaseUrl);
@@ -116,7 +116,7 @@ function parseSqlitePath(databaseUrl) {
 async function create3(databaseUrl) {
   const mod = await import("better-sqlite3").catch(() => {
     throw new Error(
-      `'sqlite' driver requested by DATABASE_URL but the 'better-sqlite3' package is not installed. Run: pnpm add -D better-sqlite3 @types/better-sqlite3`
+      `'sqlite' driver requested by DATABASE_URL but the 'better-sqlite3' package is not installed. Install it (npm i -D better-sqlite3 @types/better-sqlite3, or your package manager's equivalent).`
     );
   });
   const Database = mod.default ?? mod;
@@ -170,33 +170,65 @@ function ensureLoaded() {
 }
 __name(ensureLoaded, "ensureLoaded");
 var EnvSchema = z.object({
-  APP_BUNDLE_ID: z.string().min(1),
-  APP_URL_SCHEME: z.string().min(1),
-  INVITE_DEEPLINK_PREFIX: z.string().min(1),
-  API_BASE_URL: z.string().url(),
+  // APP_BUNDLE_ID — required at appLaunch / install time. We let the schema
+  // accept it as optional so commands that don't touch the app (`doctor`,
+  // `lint`) work without it. Use-site (WdaDriver) validates and errors with
+  // a clear message if missing.
+  APP_BUNDLE_ID: z.string().min(1).optional(),
+  // APP_URL_SCHEME — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  APP_URL_SCHEME: z.string().min(1).optional(),
+  // APP_PERMISSIONS — comma-separated `simctl privacy` services that
+  // `install --clean` (CLI + MCP) auto-grants before launch. Populated
+  // by `install --update-env` from detected NS*UsageDescription keys in
+  // the .app's Info.plist (P4 / S4). Optional — apps that don't request
+  // privacy services leave this unset.
+  // Example: APP_PERMISSIONS=location,motion
+  APP_PERMISSIONS: z.string().optional(),
+  // API_BASE_URL — only required if scenarios call `apiCall(...)`. Lazy:
+  // the ApiClient is constructed at first use, not at startup.
+  API_BASE_URL: z.string().url().optional(),
   // PROJECT_ROOT — optional default cwd for the `shell(...)` DSL primitive.
   // When unset, shell commands run from process.cwd(). Set to the absolute
   // path of the project-under-test when its CLI must be invoked from a
-  // specific directory (e.g. monorepo root for `pnpm --filter ...`).
+  // specific directory (e.g. monorepo root).
   PROJECT_ROOT: z.string().optional(),
-  // DATABASE_URL — connection string for native pg/mysql/sqlite client
-  // (Stage 0 plugin DbClient). Format examples:
+  // DATABASE_URL — only required if scenarios call `dbQuery(...)` /
+  // `dbExec(...)`. Lazy: the DbClient is constructed at first use, not at
+  // startup. Format examples:
   //   postgresql://user:pass@host:5432/dbname
   //   mysql://user:pass@host:3306/dbname
   //   sqlite:./e2e.db
   //   sqlite::memory:
-  DATABASE_URL: z.string().min(1),
-  SIM_A_NAME: z.string().min(1),
-  SIM_B_NAME: z.string().min(1),
+  DATABASE_URL: z.string().min(1).optional(),
+  // SIM_A_NAME / SIM_B_NAME — schema-optional so non-UI commands work
+  // without them. Pool-aware validation in loadEnv() below requires the
+  // names for slots actually present in SIM_POOL.
+  SIM_A_NAME: z.string().min(1).optional(),
+  SIM_B_NAME: z.string().min(1).optional(),
   SIM_POOL: z.string().default("A,B"),
-  METRO_URL: z.string().url(),
+  // METRO_URL — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  METRO_URL: z.string().url().optional(),
   // Expo dev-client builds show a "Development Servers" launcher after a clean
-  // launch (clearState wipes the remembered Metro URL). When true, the driver
-  // auto-opens `exp+<APP_URL_SCHEME>://expo-development-client/?url=<METRO_URL>`
-  // after `app_launch clean: true` to bypass the launcher.
+  // launch. When true, the driver auto-opens
+  // `exp+<APP_URL_SCHEME>://expo-development-client/?url=<METRO_URL>` after
+  // `app_launch clean: true` to bypass the launcher. (Flow not yet wired.)
   EXPO_DEV_CLIENT: z.string().optional().transform((v) => v === "true" || v === "1"),
-  SESSION_LOG_PATH: z.string().default("sessions/current.jsonl"),
-  ARTIFACTS_DIR: z.string().default("artifacts"),
+  SESSION_LOG_PATH: z.string().default("unotest/sessions/current.jsonl"),
+  // Explicit kill-switch for session recording. When "1"/"true", or when
+  // SESSION_LOG_PATH is empty, buildApp wires a NoopSessionRecorder. Used
+  // by evals harness and any consumer that wants the MCP server to make
+  // no on-disk session log.
+  SESSION_LOG_DISABLE: z.string().optional().transform((v) => v === "1" || v === "true"),
+  // When true, recorder writes the FULL tool result alongside the
+  // truncated preview. Off by default — snapshots can be megabytes.
+  SESSION_LOG_FULL: z.string().optional().transform((v) => v === "1" || v === "true"),
+  ARTIFACTS_DIR: z.string().default("unotest/artifacts"),
+  // Where ExplorationService persists per-session JSONL recording logs.
+  // Default: <ARTIFACTS_DIR>/explorations. Folded into the gitignored
+  // `unotest/artifacts/` tree by the init template.
+  EXPLORATIONS_DIR: z.string().optional(),
   // WDA per-slot port mapping (D-13 parallel multi-device). Stored as a
   // comma-separated `slot=port` list, e.g. "A=8100,B=8101". Each slot present
   // in SIM_POOL needs a port.
@@ -227,7 +259,7 @@ ${issues}`
     const value = process.env[key];
     if (!value) {
       throw new Error(
-        `SIM_POOL lists slot "${slot}" but ${key} is not set in unotest/.env`
+        `SIM_POOL lists slot "${slot}" but ${key} is not set in unotest/.env. Either add ${key}=<simulator-name> or shrink SIM_POOL to omit slot "${slot}".`
       );
     }
     simBySlot[slot] = value;
@@ -258,7 +290,8 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
-    pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS
+    pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
+    explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
   return cached;
 }
@@ -397,27 +430,84 @@ async function listSimulators() {
   return out;
 }
 __name(listSimulators, "listSimulators");
-async function resolveSimByName(name) {
+function friendlyRuntime(runtime) {
+  const m = runtime.match(/SimRuntime\.([A-Za-z]+)-(\d+)-(\d+)$/);
+  if (!m) return runtime;
+  return `${m[1]} ${m[2]}.${m[3]}`;
+}
+__name(friendlyRuntime, "friendlyRuntime");
+async function resolveSimByName(spec) {
+  const { name, runtimeHint } = parseSimSpec(spec);
   const all = await listSimulators();
-  const matches = all.filter((s) => s.name === name);
+  let matches = all.filter((s) => s.name === name);
+  if (runtimeHint) {
+    matches = matches.filter((s) => friendlyRuntime(s.runtime).toLowerCase().includes(runtimeHint.toLowerCase()));
+  }
   if (matches.length === 0) {
-    const available = all.map((s) => s.name).join(", ") || "(none)";
-    throw new Error(`Sim "${name}" not found. Available: ${available}`);
+    const available = all.map((s) => `${s.name} @ ${friendlyRuntime(s.runtime)}`).join(", ") || "(none)";
+    throw new Error(
+      `Sim "${spec}" not found. Available: ${available}. If you have multiple sims with the same name, disambiguate via "<name> @ <runtime>" (e.g. "iPhone 16 @ iOS 17.5").`
+    );
   }
   const booted = matches.find((s) => s.state === "Booted");
   return booted ?? matches[0];
 }
 __name(resolveSimByName, "resolveSimByName");
+function parseSimSpec(spec) {
+  const idx = spec.lastIndexOf("@");
+  if (idx === -1) return { name: spec.trim() };
+  return {
+    name: spec.slice(0, idx).trim(),
+    runtimeHint: spec.slice(idx + 1).trim()
+  };
+}
+__name(parseSimSpec, "parseSimSpec");
 async function bootSim(udid) {
   try {
     await exec2("xcrun", ["simctl", "boot", udid]);
+    if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+    return;
   } catch (e) {
     const msg = e.stderr ?? String(e);
-    if (msg.includes("Booted") || msg.includes("current state: Booted")) return;
-    throw e;
+    if (msg.includes("Booted") || msg.includes("current state: Booted")) {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    const state = await currentSimState(udid).catch(() => null);
+    if (state === "Booted") {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    if (state && state !== "Shutdown") {
+      throw new Error(
+        `simctl boot ${udid} failed and sim is in transitional state "${state}". Wait a few seconds and retry, or force-shutdown: \`xcrun simctl shutdown ${udid}\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+      );
+    }
+    throw new Error(
+      `simctl boot ${udid} failed. Sim is "${state ?? "unknown"}".
+Common fixes:
+  \u2022 Open Simulator.app, pick this device manually, ensure it boots.
+  \u2022 Erase: \`xcrun simctl erase ${udid}\` (wipes content & settings).
+  \u2022 Restart CoreSimulator: \`sudo killall -9 com.apple.CoreSimulator.CoreSimulatorService\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+    );
   }
 }
 __name(bootSim, "bootSim");
+async function currentSimState(udid) {
+  const sims = await listSimulators();
+  const sim = sims.find((s) => s.udid === udid);
+  return sim ? sim.state : null;
+}
+__name(currentSimState, "currentSimState");
+async function openSimulatorApp() {
+  try {
+    await exec2("open", ["-a", "Simulator"]);
+  } catch {
+  }
+}
+__name(openSimulatorApp, "openSimulatorApp");
 async function shutdownSim(udid) {
   try {
     await exec2("xcrun", ["simctl", "shutdown", udid]);
@@ -445,9 +535,37 @@ async function terminateApp(udid, bundleId) {
 }
 __name(terminateApp, "terminateApp");
 async function launchApp(udid, bundleId, args = []) {
-  await exec2("xcrun", ["simctl", "launch", udid, bundleId, ...args]);
+  const { stdout } = await exec2("xcrun", ["simctl", "launch", udid, bundleId, ...args]);
+  const m = stdout.match(/:\s*(\d+)/);
+  const pid = m ? Number.parseInt(m[1], 10) : 0;
+  return { pid };
 }
 __name(launchApp, "launchApp");
+async function isPidAlive(pid) {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isPidAlive, "isPidAlive");
+async function assertLaunchedAndStable(udid, bundleId, pid, options = {}) {
+  const settleMs = options.settleMs ?? 1500;
+  await new Promise((r) => setTimeout(r, settleMs));
+  const alive = await isPidAlive(pid);
+  if (alive) return;
+  const procName = bundleId.split(".").pop() ?? bundleId;
+  throw new Error(
+    `App "${bundleId}" started (PID ${pid}) but exited within ${settleMs}ms \u2014 looks like a crash on launch.
+See the crash reason:
+  xcrun simctl spawn ${udid} log show --predicate 'process == "${procName}" OR senderImagePath CONTAINS "${bundleId}"' --last 30s --info
+Or open Console.app, filter by your app name.
+Common causes: missing native module (rebuild after changing native deps), JS bundle baked against wrong workspace/env, signing issues.`
+  );
+}
+__name(assertLaunchedAndStable, "assertLaunchedAndStable");
 async function uninstallApp(udid, bundleId) {
   try {
     await exec2("xcrun", ["simctl", "uninstall", udid, bundleId]);
@@ -459,6 +577,63 @@ async function installApp(udid, appPath) {
   await exec2("xcrun", ["simctl", "install", udid, appPath]);
 }
 __name(installApp, "installApp");
+async function isAppInstalled(udid, bundleId) {
+  try {
+    await exec2("xcrun", ["simctl", "get_app_container", udid, bundleId]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isAppInstalled, "isAppInstalled");
+async function eraseSim(udid) {
+  await exec2("xcrun", ["simctl", "erase", udid]);
+}
+__name(eraseSim, "eraseSim");
+async function keychainResetSim(udid) {
+  await exec2("xcrun", ["simctl", "keychain", udid, "reset"]);
+}
+__name(keychainResetSim, "keychainResetSim");
+async function privacyGrantSim(udid, service, bundleId) {
+  await exec2("xcrun", ["simctl", "privacy", udid, "grant", service, bundleId]);
+}
+__name(privacyGrantSim, "privacyGrantSim");
+async function pinEnglishKeyboardSim(udid) {
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleKeyboards",
+    "-array",
+    "en_US@hw=US;sw=QWERTY"
+  ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLanguages",
+    "-array",
+    "en"
+  ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLocale",
+    "-string",
+    "en_US"
+  ]);
+}
+__name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
 // src/driver/simctl/adapter.ts
 var SimctlAdapter = class {
@@ -483,6 +658,9 @@ var SimctlAdapter = class {
   async launch(udid, bundleId, args) {
     return launchApp(udid, bundleId, args);
   }
+  async assertLaunchedAndStable(udid, bundleId, pid, settleMs) {
+    return assertLaunchedAndStable(udid, bundleId, pid, settleMs !== void 0 ? { settleMs } : {});
+  }
   async terminate(udid, bundleId) {
     return terminateApp(udid, bundleId);
   }
@@ -492,12 +670,51 @@ var SimctlAdapter = class {
   async screenshot(udid) {
     return screenshotPng(udid);
   }
+  async isInstalled(udid, bundleId) {
+    return isAppInstalled(udid, bundleId);
+  }
+  async erase(udid) {
+    return eraseSim(udid);
+  }
+  /** B5 — wipes simulator keychain so auth tokens don't survive `clean`
+   *  launches. Used by `installApp({clean})` and `WdaDriver.appLaunch({clean})`. */
+  async keychainReset(udid) {
+    return keychainResetSim(udid);
+  }
+  /** S4 — pre-grant an iOS privacy service to a bundle so the app skips
+   *  the SpringBoard permission dialog on first launch. */
+  async privacyGrant(udid, service, bundleId) {
+    return privacyGrantSim(udid, service, bundleId);
+  }
+  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
+   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  async pinEnglishKeyboard(udid) {
+    return pinEnglishKeyboardSim(udid);
+  }
+  async openSimulatorApp() {
+    return openSimulatorApp();
+  }
 };
 
-// src/driver/wda/session.ts
-import { setTimeout as delay } from "timers/promises";
-
 // src/driver/wda/http-client.ts
+var NoAlertPresentError = class extends Error {
+  static {
+    __name(this, "NoAlertPresentError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "NoAlertPresentError";
+  }
+};
+var WdaSessionGoneError = class extends Error {
+  static {
+    __name(this, "WdaSessionGoneError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "WdaSessionGoneError";
+  }
+};
 var WdaHttpClient = class {
   static {
     __name(this, "WdaHttpClient");
@@ -574,6 +791,39 @@ var WdaHttpClient = class {
   async openUrl(sessionId, url) {
     await this.post(`/session/${encodeURIComponent(sessionId)}/url`, { url });
   }
+  // ---- Alerts (native SpringBoard) ---------------------------------------
+  //
+  // These hit WDA's /alert/* endpoints which talk to the *system* alert
+  // hierarchy (SpringBoard process), NOT the app's a11y tree. Use for
+  // UIAlertController-backed dialogs: permission prompts, ATT, Sign Out
+  // confirms, iOS update banners. App-level Modals belong to regular tap.
+  //
+  // `name` in WdaAcceptAlertRequest taps a specific button by label.
+  // Omitted = WDA's position-based fallback, which is kind-dependent (see
+  // FBAlert.m): UIAlertController accept = LAST button, dismiss = FIRST;
+  // action sheet is reversed. Pass `name` whenever the alert isn't a plain
+  // 1-button modal — it's the only label-stable path.
+  async acceptAlert(sessionId, req = {}) {
+    await mapNoAlert(
+      this.post(
+        `/session/${encodeURIComponent(sessionId)}/alert/accept`,
+        req.name ? { name: req.name } : {}
+      )
+    );
+  }
+  async dismissAlert(sessionId) {
+    await mapNoAlert(this.post(`/session/${encodeURIComponent(sessionId)}/alert/dismiss`, {}));
+  }
+  async alertText(sessionId) {
+    return mapNoAlert(
+      this.get(`/session/${encodeURIComponent(sessionId)}/alert/text`)
+    );
+  }
+  async alertButtons(sessionId) {
+    return mapNoAlert(
+      this.get(`/session/${encodeURIComponent(sessionId)}/alert/buttons`)
+    );
+  }
   // ---- internals ---------------------------------------------------------
   async get(path) {
     return this.request("GET", path);
@@ -593,12 +843,32 @@ var WdaHttpClient = class {
     const resp = await this.fetchFn(`${this.baseUrl}${path}`, init);
     if (!resp.ok) {
       const text = await resp.text().catch(() => "<no body>");
-      throw new Error(`WDA ${method} ${path} failed: HTTP ${resp.status} \u2014 ${text.slice(0, 500)}`);
+      const snippet = text.slice(0, 500);
+      if (resp.status === 404 && /no such session|could not find session|invalid session id/i.test(snippet)) {
+        throw new WdaSessionGoneError(
+          `WDA ${method} ${path} reports session is gone: ${snippet}`
+        );
+      }
+      throw new Error(`WDA ${method} ${path} failed: HTTP ${resp.status} \u2014 ${snippet}`);
     }
     if (resp.status === 204) return void 0;
     return await resp.json();
   }
 };
+async function mapNoAlert(p) {
+  try {
+    return await p;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/HTTP 404/.test(msg) && /alert/i.test(msg)) {
+      throw new NoAlertPresentError(
+        `No active iOS alert on this device. WDA: ${msg.slice(msg.indexOf("HTTP"))}`
+      );
+    }
+    throw err;
+  }
+}
+__name(mapNoAlert, "mapNoAlert");
 function extractElementId(h) {
   const id = h["element-6066-11e4-a52e-4f735466cecf"] ?? h.ELEMENT;
   if (!id) {
@@ -608,6 +878,9 @@ function extractElementId(h) {
 }
 __name(extractElementId, "extractElementId");
 
+// src/driver/wda/session.ts
+import { setTimeout as delay } from "timers/promises";
+
 // src/driver/wda/probe.ts
 async function tryProbeWda(port, timeoutMs, fetchFn = (input, init) => fetch(input, init)) {
   const ctrl = new AbortController();
@@ -746,6 +1019,7 @@ var WdaSession = class {
       });
       this.sessionId = created.sessionId ?? created.value.sessionId;
       this.deps.logger.debug(`wda session started: ${this.deps.slot} (${this.sessionId})`);
+      await this.warmupTree();
     } catch (e) {
       if (this.runnerHandle) {
         try {
@@ -780,6 +1054,45 @@ var WdaSession = class {
       }
     }
   }
+  /**
+   * Warm up the accessibility tree after a fresh session by polling
+   * `/source` until two consecutive readings agree on node count. iOS
+   * XCTest's a11y discovery is asynchronous: the first `/source` after
+   * createSession can return a partial tree (often only the application
+   * root) for ~150-300ms while attributes are still being populated. A
+   * caller's first `a11yTree()` would then see that partial state and
+   * the agent acts on a half-built screen. Caps at 4 attempts so a
+   * truly animating screen (rare at start time) doesn't hang the boot.
+   */
+  async warmupTree() {
+    if (this.deps.skipWarmup) return;
+    const delayMs = this.deps.warmupDelayMs ?? 150;
+    let prevCount = -1;
+    for (let i = 0; i < 4; i++) {
+      let count = 0;
+      try {
+        const resp = await this.client.source(this.sessionId);
+        count = countWdaSource(resp.value);
+      } catch (e) {
+        this.deps.logger.warn(
+          `WdaSession[${this.deps.slot}] warmup /source attempt ${i + 1} failed: ${e.message}`
+        );
+      }
+      if (i > 0 && count > 0 && count === prevCount) {
+        this.deps.logger.debug(
+          `WdaSession[${this.deps.slot}] warmup settled at attempt ${i + 1} (${count} nodes)`
+        );
+        return;
+      }
+      prevCount = count;
+      if (i < 3 && delayMs > 0) {
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+    }
+    this.deps.logger.warn(
+      `WdaSession[${this.deps.slot}] warmup did not settle in 4 attempts \u2014 proceeding with possibly-partial tree`
+    );
+  }
   async waitUntilReady(timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let lastErr;
@@ -797,6 +1110,13 @@ var WdaSession = class {
     );
   }
 };
+function countWdaSource(n) {
+  if (!n || typeof n !== "object") return 0;
+  let total = 1;
+  for (const c of n.children ?? []) total += countWdaSource(c);
+  return total;
+}
+__name(countWdaSource, "countWdaSource");
 async function defaultStartWdaRunner(handle, port, binaryProvider, simctl, logger) {
   const probe = await tryProbeWda(port, 1500);
   if (probe?.ready) {
@@ -831,7 +1151,7 @@ function mapNode(raw) {
   if (name) out.testId = name;
   if (text) out.text = text;
   if (labelOut) out.label = labelOut;
-  if (raw.type) out.role = raw.type;
+  if (raw.type) out.role = shortRole(raw.type);
   const bounds = parseRect(raw.rect);
   if (bounds) out.bounds = bounds;
   const enabled = parseBool(raw.isEnabled);
@@ -841,6 +1161,11 @@ function mapNode(raw) {
   return out;
 }
 __name(mapNode, "mapNode");
+function shortRole(t) {
+  if (!t) return void 0;
+  return t.replace(/^XCUIElementType/, "").toLowerCase();
+}
+__name(shortRole, "shortRole");
 function nonEmpty(s) {
   if (s == null) return void 0;
   const trimmed = s.trim();
@@ -913,10 +1238,24 @@ var WdaDriver = class _WdaDriver {
   async appLaunch(slot, opts) {
     const h = await this.boot(slot);
     const bundleId = opts.bundleId ?? this.deps.appBundleId;
+    if (!bundleId) {
+      throw new Error(
+        `appLaunch needs a bundle id \u2014 set APP_BUNDLE_ID in unotest/.env or pass it explicitly.`
+      );
+    }
+    const installed = await this.simctl.isInstalled(h.udid, bundleId);
+    if (!installed) {
+      throw new Error(
+        `App "${bundleId}" is not installed on ${h.name} (slot ${slot}).
+Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH in unotest/.env and run \`unotest-mobile install\`).`
+      );
+    }
     if (opts.clean) {
       await this.simctl.terminate(h.udid, bundleId);
+      await this.simctl.keychainReset(h.udid);
     }
-    await this.simctl.launch(h.udid, bundleId);
+    const { pid } = await this.simctl.launch(h.udid, bundleId);
+    await this.simctl.assertLaunchedAndStable(h.udid, bundleId, pid);
   }
   async openDeeplink(slot, url) {
     const h = await this.boot(slot);
@@ -924,53 +1263,59 @@ var WdaDriver = class _WdaDriver {
   }
   // ---- UiDriver ----------------------------------------------------------
   async tap(slot, selector) {
-    const session = await this.getSession(slot);
-    const bounds = await this.resolveBounds(slot, selector);
-    const { cx, cy } = center(bounds);
-    await session.client.tap(session.getSessionId(), { x: cx, y: cy });
+    await this.withFreshSession(slot, async (session) => {
+      const bounds = await this.resolveBounds(slot, selector);
+      const { cx, cy } = center(bounds);
+      await session.client.tap(session.getSessionId(), { x: cx, y: cy });
+    });
   }
   async type(slot, selector, text) {
-    const session = await this.getSession(slot);
-    const elementId = await this.resolveElementId(slot, selector);
-    await session.client.setElementValue(session.getSessionId(), elementId, {
-      value: Array.from(text)
+    await this.withFreshSession(slot, async (session) => {
+      const elementId = await this.resolveElementId(slot, selector);
+      await session.client.setElementValue(session.getSessionId(), elementId, {
+        value: Array.from(text)
+      });
     });
   }
   async swipe(slot, direction, from) {
-    const session = await this.getSession(slot);
-    const size = await session.client.windowSize(session.getSessionId());
-    const w = size.value.width;
-    const h = size.value.height;
-    let fromX, fromY;
-    if (from) {
-      const b = await this.resolveBounds(slot, from);
-      const c = center(b);
-      fromX = c.cx;
-      fromY = c.cy;
-    } else {
-      fromX = w / 2;
-      fromY = h / 2;
-    }
-    const dist2 = Math.min(w, h) * 0.4;
-    const toX = direction === "left" ? fromX - dist2 : direction === "right" ? fromX + dist2 : fromX;
-    const toY = direction === "up" ? fromY - dist2 : direction === "down" ? fromY + dist2 : fromY;
-    await session.client.drag(session.getSessionId(), { fromX, fromY, toX, toY, duration: 0.3 });
+    await this.withFreshSession(slot, async (session) => {
+      const size = await session.client.windowSize(session.getSessionId());
+      const w = size.value.width;
+      const h = size.value.height;
+      let fromX, fromY;
+      if (from) {
+        const b = await this.resolveBounds(slot, from);
+        const c = center(b);
+        fromX = c.cx;
+        fromY = c.cy;
+      } else {
+        fromX = w / 2;
+        fromY = h / 2;
+      }
+      const dist2 = Math.min(w, h) * 0.4;
+      const toX = direction === "left" ? fromX - dist2 : direction === "right" ? fromX + dist2 : fromX;
+      const toY = direction === "up" ? fromY - dist2 : direction === "down" ? fromY + dist2 : fromY;
+      await session.client.drag(session.getSessionId(), { fromX, fromY, toX, toY, duration: 0.3 });
+    });
   }
   async pressKey(slot, key) {
     const session = await this.getSession(slot);
-    if (key === "home") {
-      await session.client.pressKey(session.getSessionId(), "home");
-      return;
-    }
-    if (key === "enter") {
-      await session.client.typeText(session.getSessionId(), { value: ["\n"] });
-      return;
-    }
-    if (key === "escape") {
-      await session.client.typeText(session.getSessionId(), { value: ["\x1B"] });
-      return;
+    if (key !== "home" && key !== "enter" && key !== "escape") {
+      throw new Error(
+        "pressKey('back') is not supported on iOS - use swipe-back or app-specific control"
+      );
     }
-    throw new Error(`pressKey('back') is not supported on iOS \u2014 use swipe-back or app-specific control`);
+    await this.withFreshSession(slot, async (session2) => {
+      if (key === "home") {
+        await session2.client.pressKey(session2.getSessionId(), "home");
+        return;
+      }
+      if (key === "enter") {
+        await session2.client.typeText(session2.getSessionId(), { value: ["\n"] });
+        return;
+      }
+      await session2.client.typeText(session2.getSessionId(), { value: [""] });
+    });
   }
   async waitFor(slot, selector, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 1e4;
@@ -986,13 +1331,64 @@ var WdaDriver = class _WdaDriver {
   }
   // ---- InspectionDriver --------------------------------------------------
   async screenshot(slot) {
-    const session = await this.getSession(slot);
-    return session.client.screenshot(session.getSessionId());
+    return this.withFreshSession(
+      slot,
+      (session) => session.client.screenshot(session.getSessionId())
+    );
   }
   async a11yTree(slot, _opts = {}) {
-    const session = await this.getSession(slot);
-    const resp = await session.client.source(session.getSessionId());
-    return parseWdaSource(resp.value);
+    return this.withFreshSession(slot, async (session) => {
+      const resp = await session.client.source(session.getSessionId());
+      return parseWdaSource(resp.value);
+    });
+  }
+  async windowSize(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      const size = await session.client.windowSize(session.getSessionId());
+      return { width: size.value.width, height: size.value.height };
+    });
+  }
+  // ---- AlertController ---------------------------------------------------
+  //
+  // Native UIAlertController dialogs live in SpringBoard, outside the app's
+  // a11y tree. Resolver-driven `tap()` cannot reach them: even when a
+  // selector "matches" by ordinal, the actions API targets app-process
+  // coordinates and the SpringBoard alert stays put. WDA's /alert/*
+  // endpoints know to talk to the active system alert.
+  async acceptAlert(slot, button) {
+    await this.withFreshSession(slot, async (session) => {
+      await session.client.acceptAlert(
+        session.getSessionId(),
+        button !== void 0 ? { name: button } : {}
+      );
+    });
+  }
+  async dismissAlert(slot) {
+    await this.withFreshSession(
+      slot,
+      (session) => session.client.dismissAlert(session.getSessionId())
+    );
+  }
+  async readAlert(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      const resp = await session.client.alertText(session.getSessionId());
+      return { text: resp.value };
+    });
+  }
+  // `null` on no-alert keeps the A11yTreeTool probe branch-free; the
+  // outline pipeline only renders the `alert:` section when readAlert
+  // succeeded first, so a second NoAlertPresentError here would be a
+  // SpringBoard race anyway — quieter to drop than throw.
+  async readAlertButtons(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      try {
+        const resp = await session.client.alertButtons(session.getSessionId());
+        return resp.value;
+      } catch (e) {
+        if (e instanceof NoAlertPresentError) return null;
+        throw e;
+      }
+    });
   }
   // ---- ContextController stub (D-9) --------------------------------------
   async listContexts(_slot) {
@@ -1007,6 +1403,42 @@ var WdaDriver = class _WdaDriver {
     return _WdaDriver.NATIVE_CONTEXT;
   }
   // ---- internals ---------------------------------------------------------
+  /**
+   * B6 — run `fn` against the cached session for `slot`. If WDA reports
+   * the session is gone (sim erase / app crash / runner killed) we
+   * silently drop the dead session, create a fresh one, and retry the
+   * call ONCE. Persistent failures bubble up to the caller as usual.
+   *
+   * Why ONCE: a single retry covers the "stale handle in cache" case
+   * (the common one — `--erase` between an MCP eval setup and the first
+   * tool call, runner restart, etc). If a second attempt also dies, the
+   * underlying WDA is genuinely broken and a retry loop would just
+   * waste 10+ seconds per call before the harness times out.
+   *
+   * Pre-existing `getSession` flow stays unchanged for ad-hoc internal
+   * calls (resolveBounds / resolveElementId) — those use the cached
+   * session directly and ride the retry of their outer caller.
+   */
+  async withFreshSession(slot, fn) {
+    const session = await this.getSession(slot);
+    try {
+      return await fn(session);
+    } catch (e) {
+      const isSessionGone = e instanceof WdaSessionGoneError || e instanceof Error && e.name === "WdaSessionGoneError";
+      if (!isSessionGone) throw e;
+      const msg = e instanceof Error ? e.message : String(e);
+      this.deps.logger.child(`wda:${slot}`).warn(
+        `WDA session ${session.getSessionId()} is gone (${msg.slice(0, 200)}); dropping cached session and retrying once.`
+      );
+      try {
+        await session.stop();
+      } catch {
+      }
+      this.sessions.delete(slot);
+      const fresh = await this.getSession(slot);
+      return fn(fresh);
+    }
+  }
   async getSession(slot) {
     const existing = this.sessions.get(slot);
     if (existing) return existing;
@@ -1017,6 +1449,23 @@ var WdaDriver = class _WdaDriver {
         `No WDA port configured for slot "${slot}". Set EnvConfig.wdaPortBySlot or add WDA_PORT_${slot} to .env.`
       );
     }
+    if (!this.deps.sessionFactory && !this.deps.appBundleId) {
+      throw new Error(
+        `WDA session needs APP_BUNDLE_ID \u2014 set it in unotest/.env. WebDriverAgent attaches to a specific app via the bundle id.`
+      );
+    }
+    if (!this.deps.sessionFactory && this.deps.appBundleId) {
+      const installed = await this.simctl.isInstalled(handle.udid, this.deps.appBundleId);
+      if (!installed) {
+        throw new Error(
+          `App "${this.deps.appBundleId}" is not installed on ${handle.name} (slot ${slot}).
+Install it first:
+  npx unotest-mobile install <path-to-.app>           # if you have the .app
+  npx unotest-mobile install                          # if APP_PATH is set in unotest/.env
+In an MCP session, call the \`app_install\` tool \u2014 it will read APP_PATH or ask you for the path.`
+        );
+      }
+    }
     const session = this.deps.sessionFactory ? this.deps.sessionFactory(slot, handle, port) : new WdaSession({
       slot,
       handle,
@@ -1486,59 +1935,74 @@ function dist(a, b) {
 __name(dist, "dist");
 
 // src/inspection/tree-inspector.ts
-var INTERACTIVE_ROLE_HINTS = [
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
   "button",
   "textfield",
-  "securefield",
-  "secureinput",
-  "input",
-  "link",
+  "securetextfield",
   "switch",
+  "checkbox",
+  "link",
   "slider",
   "picker",
-  "checkbox",
   "tab",
   "menuitem"
-];
+]);
 function isInteractiveRole(role) {
-  if (!role) return false;
-  const r = role.toLowerCase();
-  return INTERACTIVE_ROLE_HINTS.some((hint) => r.includes(hint));
+  return role !== void 0 && INTERACTIVE_ROLES.has(role);
 }
 __name(isInteractiveRole, "isInteractiveRole");
 function isNoise(n) {
   return !n.testId && !n.text && !n.label && !isInteractiveRole(n.role);
 }
 __name(isNoise, "isNoise");
-function stripAttrs(n, children) {
-  const out = { children };
+function dedupeFields(n) {
+  const out = { children: n.children };
+  if (n.role) out.role = n.role;
   if (n.testId) out.testId = n.testId;
   if (n.text) out.text = n.text;
   if (n.label) out.label = n.label;
-  if (isInteractiveRole(n.role)) out.role = n.role;
-  return out;
-}
-__name(stripAttrs, "stripAttrs");
-function compactSubtree(n) {
-  let totalSeen = 1;
-  const newChildren = [];
-  for (const c of n.children) {
-    const r = compactSubtree(c);
-    totalSeen += r.totalSeen;
-    newChildren.push(...r.kept);
+  if (n.clipped) out.clipped = n.clipped;
+  if (out.text && out.label && out.text === out.label) {
+    delete out.label;
   }
-  if (isNoise(n)) {
-    return { totalSeen, kept: newChildren };
+  const interactive = isInteractiveRole(out.role);
+  if (out.testId && !interactive && (out.testId === out.text || out.testId === out.label)) {
+    delete out.testId;
   }
-  return { totalSeen, kept: [stripAttrs(n, newChildren)] };
+  return out;
 }
-__name(compactSubtree, "compactSubtree");
-function countNodes(n) {
-  let total = 1;
-  for (const c of n.children) total += countNodes(c);
-  return total;
+__name(dedupeFields, "dedupeFields");
+function classify(bounds, viewport) {
+  if (!bounds) return "on-screen";
+  const { x, y, width, height } = bounds;
+  const yMax = y + height;
+  const xMax = x + width;
+  if (yMax <= 0) return "top";
+  if (y >= viewport.height) return "bottom";
+  if (xMax <= 0) return "left";
+  if (x >= viewport.width) return "right";
+  if (y < 0) return "clipped:top";
+  if (yMax > viewport.height) return "clipped:bottom";
+  if (x < 0) return "clipped:left";
+  if (xMax > viewport.width) return "clipped:right";
+  return "on-screen";
+}
+__name(classify, "classify");
+function clippedSide(c) {
+  switch (c) {
+    case "clipped:top":
+      return "top";
+    case "clipped:bottom":
+      return "bottom";
+    case "clipped:left":
+      return "left";
+    case "clipped:right":
+      return "right";
+    default:
+      return void 0;
+  }
 }
-__name(countNodes, "countNodes");
+__name(clippedSide, "clippedSide");
 function collectTestIds(n, counts) {
   if (n.testId) counts.set(n.testId, (counts.get(n.testId) ?? 0) + 1);
   for (const c of n.children) collectTestIds(c, counts);
@@ -1553,45 +2017,102 @@ function applyIndex(n, counts, running) {
   for (const c of n.children) applyIndex(c, counts, running);
 }
 __name(applyIndex, "applyIndex");
-function indexDuplicates(tree) {
+function indexOnScreenDuplicates(nodes) {
   const counts = /* @__PURE__ */ new Map();
-  collectTestIds(tree, counts);
-  applyIndex(tree, counts, /* @__PURE__ */ new Map());
-  return tree;
+  for (const n of nodes) collectTestIds(n, counts);
+  const running = /* @__PURE__ */ new Map();
+  for (const n of nodes) applyIndex(n, counts, running);
+}
+__name(indexOnScreenDuplicates, "indexOnScreenDuplicates");
+function countSemanticNodes(nodes) {
+  let total = 0;
+  for (const n of nodes) {
+    total += 1;
+    total += countSemanticNodes(n.children);
+  }
+  return total;
+}
+__name(countSemanticNodes, "countSemanticNodes");
+function countOffScreen(off) {
+  return off.top.length + off.bottom.length + off.left.length + off.right.length;
+}
+__name(countOffScreen, "countOffScreen");
+function buildSemanticTree(raw, viewport) {
+  const onScreenRoots = [];
+  const offScreen = { top: [], bottom: [], left: [], right: [] };
+  let totalSeen = 0;
+  function makeKept(n, clipped) {
+    const base = { children: [] };
+    if (n.role) base.role = n.role;
+    if (n.testId) base.testId = n.testId;
+    if (n.text) base.text = n.text;
+    if (n.label) base.label = n.label;
+    if (clipped) base.clipped = clipped;
+    return dedupeFields(base);
+  }
+  __name(makeKept, "makeKept");
+  function makeOffScreen(n) {
+    const out = {};
+    if (n.role) out.role = n.role;
+    if (n.testId) out.testId = n.testId;
+    if (n.text) out.text = n.text;
+    if (n.label) out.label = n.label;
+    const deduped = dedupeFields({ ...out, children: [] });
+    const flat = {};
+    if (deduped.role) flat.role = deduped.role;
+    if (deduped.testId) flat.testId = deduped.testId;
+    if (deduped.text) flat.text = deduped.text;
+    if (deduped.label) flat.label = deduped.label;
+    return flat;
+  }
+  __name(makeOffScreen, "makeOffScreen");
+  function walk2(node, onScreenParent) {
+    totalSeen += 1;
+    const c = classify(node.bounds, viewport);
+    const onSide = c === "on-screen" || c.startsWith("clipped:");
+    if (onSide) {
+      if (isNoise(node)) {
+        for (const child of node.children) walk2(child, onScreenParent);
+        return;
+      }
+      const kept = makeKept(node, clippedSide(c));
+      if (onScreenParent) onScreenParent.children.push(kept);
+      else onScreenRoots.push(kept);
+      for (const child of node.children) walk2(child, kept);
+      return;
+    }
+    const side = c;
+    if (!isNoise(node)) {
+      offScreen[side].push(makeOffScreen(node));
+    }
+    for (const child of node.children) walk2(child, null);
+  }
+  __name(walk2, "walk");
+  walk2(raw, null);
+  indexOnScreenDuplicates(onScreenRoots);
+  return {
+    on_screen: onScreenRoots,
+    off_screen: offScreen,
+    _meta: {
+      totalNodes: totalSeen,
+      onScreen: countSemanticNodes(onScreenRoots),
+      offScreen: countOffScreen(offScreen),
+      viewport: { width: viewport.width, height: viewport.height }
+    }
+  };
 }
-__name(indexDuplicates, "indexDuplicates");
+__name(buildSemanticTree, "buildSemanticTree");
 var TreeInspector = class {
   static {
     __name(this, "TreeInspector");
   }
   /**
-   * D-16-aware compaction:
-   *   - drop wrappers with no identifying signal,
-   *   - strip layout-only attributes (bounds, enabled, focused, non-interactive role),
-   *   - keep text-only and label-only leaves,
-   *   - report `_meta` at the root.
-   */
-  compactTree(root) {
-    const result = compactSubtree(root);
-    const out = result.kept.length === 1 ? result.kept[0] : { children: result.kept };
-    const shown = countNodes(out);
-    out._meta = { totalNodes: result.totalSeen, shown, mode: "compact" };
-    return out;
-  }
-  /**
-   * Convenience: compact + index duplicates. The shape most MCP-tools want.
+   * Partition a raw a11y tree against a viewport. The P1 entry — outline
+   * renderer (in `outline-renderer.ts`) consumes the returned
+   * `SemanticTree` directly.
    */
-  compactWithIds(root) {
-    return indexDuplicates(this.compactTree(root));
-  }
-  /**
-   * Annotate the raw tree as `full` (carries _meta for symmetry, no shape
-   * changes). Useful for MCP tools whose only choice is compact vs full.
-   */
-  withMode(root, mode) {
-    if (mode === "compact") return this.compactWithIds(root);
-    const total = countNodes(root);
-    return { ...root, _meta: { totalNodes: total, shown: total, mode: "full" } };
+  semanticTree(raw, viewport) {
+    return buildSemanticTree(raw, viewport);
   }
   /**
    * DFS path from root to `target`, encoded as "child-index/child-index/...".
@@ -2863,6 +3384,10 @@ var AstExecutor = class {
       }
       return;
     }
+    if (stmt instanceof MetaBlockStatement) {
+      yield* this.execStatement(stmt.body, runtime, opts, getSteps, setSteps, runStartMs, userFns, callStack);
+      return;
+    }
     if (stmt instanceof ReturnStatement) {
       const expr = stmt.expression;
       const value = yield* this.evalExpression(expr, runtime, opts, getSteps, setSteps, runStartMs, userFns, callStack);
@@ -3274,6 +3799,11 @@ var DslLinter = class {
     if (!this.deps.registry.has(name) && !userFns.has(name)) {
       diags.push(diag("error", "E1", `Unknown DSL function "${name}"`, call));
     }
+    const fn = this.deps.registry.get(name);
+    if (fn) {
+      this.checkArity(call, fn, diags);
+      this.checkArgTypes(call, fn, diags);
+    }
     if (name === "setDevice" && call.arguments.length > 0) {
       const arg0 = call.arguments[0];
       if (arg0 instanceof ValueExpression) {
@@ -3309,6 +3839,77 @@ var DslLinter = class {
       this.checkExpression(arg, diags, recordCall, isFirstUiSeen, userFns, allowReturn);
     }
   }
+  checkArity(call, fn, diags) {
+    const max = fn.argTypes.length;
+    const min = fn.minArgs ?? max;
+    const got = call.arguments.length;
+    if (got < min) {
+      diags.push(
+        diag(
+          "error",
+          "E5",
+          `${fn.name}(): expected ${min === max ? `${min}` : `at least ${min}`} arg${min === 1 ? "" : "s"}, got ${got}`,
+          call
+        )
+      );
+      return;
+    }
+    if (!fn.variadic && got > max) {
+      diags.push(
+        diag(
+          "error",
+          "E5",
+          `${fn.name}(): expected at most ${max} arg${max === 1 ? "" : "s"}, got ${got}`,
+          call
+        )
+      );
+    }
+  }
+  /**
+   * For each provided arg up to argTypes.length, infer its static type and
+   * compare to the declared signature. Only emits E6 when the inferred type
+   * is UNAMBIGUOUS — we never flag "any" sources (variables, helper-call
+   * results, BinaryExpression, ArrayExpression).
+   */
+  checkArgTypes(call, fn, diags) {
+    const limit = Math.min(call.arguments.length, fn.argTypes.length);
+    for (let i = 0; i < limit; i++) {
+      const expected = fn.argTypes[i];
+      if (expected === "any") continue;
+      const inferred = this.inferExprType(call.arguments[i]);
+      if (inferred === "any") continue;
+      if (inferred === expected) continue;
+      if (expected === "boolean" && inferred === "number" || expected === "number" && inferred === "boolean") {
+        continue;
+      }
+      diags.push(
+        diag(
+          "error",
+          "E6",
+          `${fn.name}(): arg ${i} expected ${expected}, got ${describeInferred(call.arguments[i], inferred)}`,
+          call
+        )
+      );
+    }
+  }
+  /** Best-effort static type for an expression node. "any" = unknown. */
+  inferExprType(expr) {
+    if (expr instanceof ValueExpression) {
+      const v = expr.value;
+      if (v instanceof StringValue) return "string";
+      if (v instanceof NumberValue) return "number";
+      return "any";
+    }
+    if (expr instanceof VariableExpression) {
+      if (expr.name === "true" || expr.name === "false") return "boolean";
+      return "any";
+    }
+    if (expr instanceof FunctionalExpression) {
+      const callee = this.deps.registry.get(expr.name);
+      return callee ? callee.returnType : "any";
+    }
+    return "any";
+  }
   isForbiddenStatement(stmt) {
     return stmt instanceof ForStatement || stmt instanceof WhileStatement || stmt instanceof DoWhileStatement || stmt instanceof VarStatement || stmt instanceof PrintStatement || stmt instanceof BreakStatement || stmt instanceof ContinueStatement || stmt instanceof IncrementStatement || stmt instanceof ArrayAssignmentStatement;
   }
@@ -3320,6 +3921,19 @@ function isBlockMappable2(name) {
   return name.startsWith("test_") || name.startsWith("flow_");
 }
 __name(isBlockMappable2, "isBlockMappable");
+function describeInferred(expr, inferred) {
+  if (expr instanceof FunctionalExpression) {
+    return `${inferred} (${expr.name}() returns ${inferred})`;
+  }
+  if (expr instanceof ValueExpression) {
+    return `${inferred} literal`;
+  }
+  if (expr instanceof VariableExpression && (expr.name === "true" || expr.name === "false")) {
+    return `boolean literal \`${expr.name}\``;
+  }
+  return inferred;
+}
+__name(describeInferred, "describeInferred");
 function diag(severity, code, message, node) {
   const tok = node.token;
   return {
@@ -3355,6 +3969,41 @@ var FunctionRegistry = class {
   }
 };
 
+// src/dsl/functions/alerts.ts
+function asString(x, fn, idx) {
+  if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
+  return x;
+}
+__name(asString, "asString");
+var acceptAlert = {
+  name: "acceptAlert",
+  argTypes: ["string"],
+  returnType: "void",
+  minArgs: 0,
+  invoke: /* @__PURE__ */ __name(async (runtime, buttonArg) => {
+    const button = buttonArg !== void 0 ? asString(buttonArg, "acceptAlert", 0) : void 0;
+    await runtime.driver.acceptAlert(runtime.currentDeviceSlot, button);
+  }, "invoke")
+};
+var dismissAlert = {
+  name: "dismissAlert",
+  argTypes: [],
+  returnType: "void",
+  invoke: /* @__PURE__ */ __name(async (runtime) => {
+    await runtime.driver.dismissAlert(runtime.currentDeviceSlot);
+  }, "invoke")
+};
+var readAlert = {
+  name: "readAlert",
+  argTypes: [],
+  returnType: "string",
+  invoke: /* @__PURE__ */ __name(async (runtime) => {
+    const { text } = await runtime.driver.readAlert(runtime.currentDeviceSlot);
+    return text;
+  }, "invoke")
+};
+var ALERT_FUNCTIONS = [acceptAlert, dismissAlert, readAlert];
+
 // src/dsl/functions/asserts.ts
 function asSelector(x, fn, idx) {
   if (typeof x !== "object" || x === null) {
@@ -3470,11 +4119,11 @@ var ASSERT_FUNCTIONS = [
 ];
 
 // src/dsl/functions/data.ts
-function asString(x, fn, idx) {
+function asString2(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString, "asString");
+__name(asString2, "asString");
 function toSqlParam(v) {
   if (v === null || v === void 0) return null;
   if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
@@ -3485,8 +4134,9 @@ var dbQuery = {
   name: "dbQuery",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, sqlArg, ...rest) => {
-    const sql = asString(sqlArg, "dbQuery", 0);
+    const sql = asString2(sqlArg, "dbQuery", 0);
     const params = rest.map((a, i) => {
       try {
         return toSqlParam(a);
@@ -3507,8 +4157,9 @@ var dbExec = {
   name: "dbExec",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, sqlArg, ...rest) => {
-    const sql = asString(sqlArg, "dbExec", 0);
+    const sql = asString2(sqlArg, "dbExec", 0);
     const params = rest.map((a, i) => {
       try {
         return toSqlParam(a);
@@ -3530,8 +4181,9 @@ var shell = {
   name: "shell",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, cmdArg, ...rest) => {
-    const cmd = asString(cmdArg, "shell", 0);
+    const cmd = asString2(cmdArg, "shell", 0);
     const args = rest.map((a, i) => {
       if (a === null || a === void 0) return "";
       if (typeof a === "string") return a;
@@ -3549,14 +4201,14 @@ var apiCall = {
   returnType: "string",
   minArgs: 2,
   invoke: /* @__PURE__ */ __name(async (runtime, methodArg, pathArg, bodyArg) => {
-    const method = asString(methodArg, "apiCall", 0).toUpperCase();
-    const path = asString(pathArg, "apiCall", 1);
+    const method = asString2(methodArg, "apiCall", 0).toUpperCase();
+    const path = asString2(pathArg, "apiCall", 1);
     if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") {
       throw new Error(`apiCall(): unsupported method "${method}"`);
     }
     let body;
     if (bodyArg !== void 0) {
-      const bodyJson = asString(bodyArg, "apiCall", 2);
+      const bodyJson = asString2(bodyArg, "apiCall", 2);
       try {
         body = JSON.parse(bodyJson);
       } catch (e) {
@@ -3576,11 +4228,11 @@ var apiCall = {
 var DATA_FUNCTIONS = [dbQuery, dbExec, apiCall, shell];
 
 // src/dsl/functions/device.ts
-function asString2(x, fn, idx) {
+function asString3(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString2, "asString");
+__name(asString3, "asString");
 function asBoolean(x, fn, idx) {
   if (typeof x !== "boolean") throw new Error(`${fn}(): arg ${idx} must be a boolean. Got ${typeof x}.`);
   return x;
@@ -3591,7 +4243,7 @@ var setDevice = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name((runtime, slotArg) => {
-    const slot = asString2(slotArg, "setDevice", 0);
+    const slot = asString3(slotArg, "setDevice", 0);
     runtime.setCurrentDeviceSlot(slot);
   }, "invoke")
 };
@@ -3610,7 +4262,7 @@ var openDeeplink = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, urlArg) => {
-    const url = asString2(urlArg, "openDeeplink", 0);
+    const url = asString3(urlArg, "openDeeplink", 0);
     await runtime.driver.openDeeplink(runtime.currentDeviceSlot, url);
   }, "invoke")
 };
@@ -3732,11 +4384,11 @@ function asSelector2(x, fn, idx) {
   return x;
 }
 __name(asSelector2, "asSelector");
-function asString3(x, fn, idx) {
+function asString4(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString3, "asString");
+__name(asString4, "asString");
 function asNumber2(x, fn, idx) {
   if (typeof x !== "number") throw new Error(`${fn}(): arg ${idx} must be a number. Got ${typeof x}.`);
   return x;
@@ -3775,7 +4427,7 @@ var type_ = {
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, selectorArg, textArg) => {
     const selector = asSelector2(selectorArg, "type", 0);
-    const text = asString3(textArg, "type", 1);
+    const text = asString4(textArg, "type", 1);
     await pollUntilFound(runtime, selector, runtime.envConfig.defaultActionWaitMs);
     await runtime.driver.type(runtime.currentDeviceSlot, selector, text);
   }, "invoke")
@@ -3786,7 +4438,7 @@ var swipe = {
   returnType: "void",
   minArgs: 1,
   invoke: /* @__PURE__ */ __name(async (runtime, directionArg, fromArg) => {
-    const direction = asString3(directionArg, "swipe", 0);
+    const direction = asString4(directionArg, "swipe", 0);
     if (direction !== "up" && direction !== "down" && direction !== "left" && direction !== "right") {
       throw new Error(`swipe(): direction must be 'up'|'down'|'left'|'right'. Got "${direction}".`);
     }
@@ -3803,7 +4455,7 @@ var pressKey = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, keyArg) => {
-    const key = asString3(keyArg, "pressKey", 0);
+    const key = asString4(keyArg, "pressKey", 0);
     if (key !== "back" && key !== "home" && key !== "enter" && key !== "escape") {
       throw new Error(`pressKey(): key must be 'back'|'home'|'enter'|'escape'. Got "${key}".`);
     }
@@ -3837,6 +4489,7 @@ var ALL_DSL_FUNCTIONS = [
   ...DEVICE_FUNCTIONS,
   ...UI_FUNCTIONS,
   ...SELECTOR_FUNCTIONS,
+  ...ALERT_FUNCTIONS,
   ...DATA_FUNCTIONS,
   ...ASSERT_FUNCTIONS,
   ...TIME_FUNCTIONS
@@ -4017,9 +4670,9 @@ var TestRuntimeManager = class {
 };
 
 // src/runner/fs-scenario-repository.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync } from "fs";
 import { readdir } from "fs/promises";
-import { resolve, join as join2, sep } from "path";
+import { dirname as dirname2, resolve, join as join2, sep } from "path";
 var FileSystemScenarioRepository = class {
   static {
     __name(this, "FileSystemScenarioRepository");
@@ -4047,13 +4700,28 @@ var FileSystemScenarioRepository = class {
     }
   }
   async load(name) {
+    const path = this.pathFor(name);
+    const source = readFileSync2(path, "utf8");
+    return { name, source };
+  }
+  async has(name) {
+    return existsSync2(this.pathFor(name));
+  }
+  async save(name, source, opts) {
+    const path = this.pathFor(name);
+    if (existsSync2(path) && !opts?.overwrite) {
+      throw new Error(`scenario "${name}" already exists at ${path}`);
+    }
+    mkdirSync2(dirname2(path), { recursive: true });
+    writeFileSync(path, source);
+    return path;
+  }
+  pathFor(name) {
     if (name.includes("..") || name.startsWith("/") || name.includes("\\")) {
       throw new Error(`Invalid scenario name "${name}"`);
     }
     const relPath = name.split("/").join(sep) + ".js";
-    const path = join2(this.scenariosDir, relPath);
-    const source = readFileSync2(path, "utf8");
-    return { name, source };
+    return join2(this.scenariosDir, relPath);
   }
 };
 
@@ -4882,7 +5550,7 @@ __name(collectOrigins, "collectOrigins");
 
 // src/runner/helper-repository.ts
 import { readdir as readdir2, readFile } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { join as join3, relative } from "path";
 var FileSystemHelperRepository = class {
   static {
@@ -4895,7 +5563,7 @@ var FileSystemHelperRepository = class {
     this.helpersDir = join3(deps.scenariosDir, "_helpers");
   }
   async loadAll() {
-    if (!existsSync2(this.helpersDir)) return [];
+    if (!existsSync3(this.helpersDir)) return [];
     const files = await collectJsFiles(this.helpersDir);
     const out = [];
     for (const absolutePath of files) {
@@ -4928,28 +5596,373 @@ async function collectJsFiles(dir) {
 __name(collectJsFiles, "collectJsFiles");
 
 // src/mcp/session-recorder.ts
-import { appendFileSync, mkdirSync as mkdirSync2, writeFileSync } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { appendFileSync, mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 var SessionRecorder = class {
   static {
     __name(this, "SessionRecorder");
   }
   path;
-  constructor(path) {
+  full;
+  constructor(path, opts = {}) {
     this.path = resolve2(process.cwd(), path);
-    mkdirSync2(dirname2(this.path), { recursive: true });
+    this.full = opts.full ?? false;
+    mkdirSync3(dirname3(this.path), { recursive: true });
   }
   record(action) {
-    const entry = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...action };
+    const { full_result, ...rest } = action;
+    const entry = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...rest };
+    if (this.full && full_result !== void 0) entry.full_result = full_result;
     appendFileSync(this.path, JSON.stringify(entry) + "\n");
   }
   reset() {
-    writeFileSync(this.path, "");
+    writeFileSync2(this.path, "");
   }
   getPath() {
     return this.path;
   }
 };
+var NoopSessionRecorder = class {
+  static {
+    __name(this, "NoopSessionRecorder");
+  }
+  record(_action) {
+  }
+  reset() {
+  }
+  getPath() {
+    return "(disabled)";
+  }
+};
+
+// src/mcp/exploration/exploration.service.ts
+import { mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync as readFileSync3, appendFileSync as appendFileSync2, statSync } from "fs";
+import { join as join4 } from "path";
+import { randomUUID } from "crypto";
+
+// src/mcp/exploration/stability.ts
+function classifyStability(selector) {
+  if (!selector) return "stable";
+  if (selector.testId) return "stable";
+  if (selector.label && selector.ordinal === void 0) return "stable";
+  if (selector.text && selector.ordinal === void 0) return "stable";
+  return "fragile";
+}
+__name(classifyStability, "classifyStability");
+
+// src/mcp/exploration/exploration.service.ts
+var ExplorationService = class {
+  static {
+    __name(this, "ExplorationService");
+  }
+  sessions = /* @__PURE__ */ new Map();
+  logs = /* @__PURE__ */ new Map();
+  dir;
+  clock;
+  generateId;
+  constructor(deps) {
+    this.dir = deps.explorationsDir;
+    this.clock = deps.clock ?? (() => /* @__PURE__ */ new Date());
+    this.generateId = deps.generateId ?? (() => randomUUID());
+    mkdirSync4(this.dir, { recursive: true });
+    this.restore();
+  }
+  startSession(params) {
+    const explorationId = `exp-${this.generateId()}`;
+    const actionLogId = `log-${this.generateId()}`;
+    const startedAt = this.clock().toISOString();
+    const session = {
+      explorationId,
+      scenarioName: params.scenarioName,
+      device: params.device,
+      status: "active",
+      startedAt,
+      actionLogId,
+      ...params.title !== void 0 ? { title: params.title } : {},
+      ...params.description !== void 0 ? { description: params.description } : {}
+    };
+    this.sessions.set(explorationId, session);
+    this.logs.set(actionLogId, { logId: actionLogId, createdAt: startedAt, entries: [] });
+    this.append(explorationId, { kind: "session_started", session });
+    return session;
+  }
+  getSession(explorationId) {
+    return this.sessions.get(explorationId);
+  }
+  getLog(explorationId) {
+    const s = this.sessions.get(explorationId);
+    return s ? this.logs.get(s.actionLogId) : void 0;
+  }
+  addEntry(explorationId, params) {
+    const session = this.requireActive(explorationId);
+    const log = this.logs.get(session.actionLogId);
+    const entry = {
+      entryId: `e-${this.generateId()}`,
+      performedAt: this.clock().toISOString(),
+      action: params.action,
+      device: params.device,
+      description: params.description,
+      section: params.section,
+      stability: classifyStability(params.selector),
+      ...params.selector !== void 0 ? { selector: params.selector } : {},
+      ...params.value !== void 0 ? { value: params.value } : {},
+      ...params.key !== void 0 ? { key: params.key } : {},
+      ...params.direction !== void 0 ? { direction: params.direction } : {},
+      ...params.from !== void 0 ? { from: params.from } : {},
+      ...params.url !== void 0 ? { url: params.url } : {},
+      ...params.bundleId !== void 0 ? { bundleId: params.bundleId } : {},
+      ...params.clean !== void 0 ? { clean: params.clean } : {},
+      ...params.timeoutMs !== void 0 ? { timeoutMs: params.timeoutMs } : {},
+      ...params.optional !== void 0 ? { optional: params.optional } : {},
+      ...params.button !== void 0 ? { button: params.button } : {}
+    };
+    log.entries.push(entry);
+    this.append(explorationId, { kind: "entry_added", entry });
+    return entry;
+  }
+  removeEntry(explorationId, entryId) {
+    const session = this.requireKnown(explorationId);
+    const log = this.logs.get(session.actionLogId);
+    const idx = log.entries.findIndex((e) => e.entryId === entryId);
+    if (idx < 0) return false;
+    log.entries.splice(idx, 1);
+    this.append(explorationId, { kind: "entry_removed", entryId });
+    return true;
+  }
+  stopSession(explorationId) {
+    const session = this.requireKnown(explorationId);
+    if (session.status === "stopped") return session;
+    session.status = "stopped";
+    this.append(explorationId, { kind: "session_stopped", stoppedAt: this.clock().toISOString() });
+    return session;
+  }
+  listSessions() {
+    return [...this.sessions.values()];
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  requireKnown(explorationId) {
+    const s = this.sessions.get(explorationId);
+    if (!s) throw new ExplorationNotFoundError(explorationId);
+    return s;
+  }
+  requireActive(explorationId) {
+    const s = this.requireKnown(explorationId);
+    if (s.status !== "active") {
+      throw new ExplorationStoppedError(explorationId);
+    }
+    return s;
+  }
+  append(explorationId, record) {
+    appendFileSync2(join4(this.dir, `${explorationId}.jsonl`), JSON.stringify(record) + "\n");
+  }
+  restore() {
+    let files;
+    try {
+      files = readdirSync2(this.dir).filter((f) => f.endsWith(".jsonl"));
+    } catch {
+      return;
+    }
+    for (const file of files) {
+      const full = join4(this.dir, file);
+      try {
+        if (!statSync(full).isFile()) continue;
+        const text = readFileSync3(full, "utf8");
+        this.replayFile(text);
+      } catch {
+      }
+    }
+  }
+  replayFile(jsonl) {
+    const lines = jsonl.split("\n").filter((l) => l.length > 0);
+    let session = null;
+    let log = null;
+    for (const line of lines) {
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      switch (rec.kind) {
+        case "session_started": {
+          session = { ...rec.session };
+          log = { logId: session.actionLogId, createdAt: session.startedAt, entries: [] };
+          this.sessions.set(session.explorationId, session);
+          this.logs.set(session.actionLogId, log);
+          break;
+        }
+        case "entry_added": {
+          if (log) log.entries.push(rec.entry);
+          break;
+        }
+        case "entry_removed": {
+          if (log) {
+            const idx = log.entries.findIndex((e) => e.entryId === rec.entryId);
+            if (idx >= 0) log.entries.splice(idx, 1);
+          }
+          break;
+        }
+        case "session_stopped": {
+          if (session) session.status = "stopped";
+          break;
+        }
+      }
+    }
+  }
+};
+var ExplorationNotFoundError = class extends Error {
+  static {
+    __name(this, "ExplorationNotFoundError");
+  }
+  code = "EXPLORATION_NOT_FOUND";
+  constructor(explorationId) {
+    super(`exploration session not found: ${explorationId}`);
+    this.name = "ExplorationNotFoundError";
+  }
+};
+var ExplorationStoppedError = class extends Error {
+  static {
+    __name(this, "ExplorationStoppedError");
+  }
+  code = "EXPLORATION_STOPPED";
+  constructor(explorationId) {
+    super(`exploration session already stopped: ${explorationId}`);
+    this.name = "ExplorationStoppedError";
+  }
+};
+
+// src/mcp/exploration/format-selector.ts
+function formatSelector(selector) {
+  if (selector.ordinal !== void 0) {
+    const { ordinal: ordinal2, ...rest } = selector;
+    const inner = formatSelector(rest);
+    return inner === null ? null : `ordinal(${inner}, ${ordinal2})`;
+  }
+  if (selector.testId !== void 0) return `getByTestId(${JSON.stringify(selector.testId)})`;
+  if (selector.text !== void 0) return `getByText(${JSON.stringify(selector.text)})`;
+  if (selector.label !== void 0) return `getByLabel(${JSON.stringify(selector.label)})`;
+  return null;
+}
+__name(formatSelector, "formatSelector");
+function describeShape(selector) {
+  const keys = Object.keys(selector).filter((k) => selector[k] !== void 0);
+  return keys.length === 0 ? "<empty>" : keys.sort().join("+");
+}
+__name(describeShape, "describeShape");
+
+// src/mcp/exploration/dsl-view.service.ts
+var DslViewService = class {
+  static {
+    __name(this, "DslViewService");
+  }
+  generate(session, log) {
+    const warnings = [];
+    const lines = [];
+    lines.push(renderHeader(session));
+    lines.push(`function test_${session.scenarioName.replace(/[^a-zA-Z0-9_]/g, "_")}() {`);
+    lines.push(`  setDevice(${JSON.stringify(session.device)});`);
+    let openSection = null;
+    for (const entry of log.entries) {
+      if (entry.section !== openSection) {
+        if (openSection !== null) lines.push("  //@endcollapse");
+        lines.push(`  //@collapse(${JSON.stringify(entry.section)})`);
+        openSection = entry.section;
+      }
+      const result = renderEntry(entry);
+      if (result.kind === "skip") {
+        warnings.push({
+          entryId: entry.entryId,
+          type: "NO_DSL_PRIMITIVE",
+          message: result.reason
+        });
+        lines.push(`  // SKIPPED (${result.reason}) \u2014 replace with getByTestId/getByText/getByLabel`);
+        continue;
+      }
+      if (entry.stability === "fragile") {
+        warnings.push({
+          entryId: entry.entryId,
+          type: "FRAGILE_LOCATOR",
+          message: `${entry.action} selector lacks a stable identifier \u2014 add a testId in the app`
+        });
+      }
+      for (const w of result.warnings ?? []) {
+        warnings.push({ ...w, entryId: entry.entryId });
+      }
+      lines.push("  " + result.stmt);
+    }
+    if (openSection !== null) lines.push("  //@endcollapse");
+    lines.push("}");
+    return { draftDsl: lines.join("\n") + "\n", warnings };
+  }
+};
+function renderHeader(session) {
+  const title = session.title ?? session.scenarioName;
+  return [
+    `// id-${session.scenarioName}`,
+    `// ${title}`,
+    `// #4287f5`
+  ].join("\n");
+}
+__name(renderHeader, "renderHeader");
+function renderEntry(entry) {
+  const sel = /* @__PURE__ */ __name((s) => {
+    const out = formatSelector(s);
+    if (out === null) {
+      return { kind: "skip", reason: `selector shape ${describeShape(s)} has no DSL primitive` };
+    }
+    return out;
+  }, "sel");
+  switch (entry.action) {
+    case "tap": {
+      if (!entry.selector) return { kind: "skip", reason: "tap missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `tap(${s});` };
+    }
+    case "type": {
+      if (!entry.selector) return { kind: "skip", reason: "type missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `type(${s}, ${JSON.stringify(entry.value ?? "")});` };
+    }
+    case "swipe": {
+      const dir = JSON.stringify(entry.direction ?? "up");
+      if (entry.from) {
+        const s = sel(entry.from);
+        if (typeof s !== "string") return s;
+        return { kind: "stmt", stmt: `swipe(${dir}, ${s});` };
+      }
+      return { kind: "stmt", stmt: `swipe(${dir});` };
+    }
+    case "wait_for": {
+      if (!entry.selector) return { kind: "skip", reason: "wait_for missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `waitFor(${s}, ${entry.timeoutMs ?? 5e3});` };
+    }
+    case "press_key":
+      return { kind: "stmt", stmt: `pressKey(${JSON.stringify(entry.key ?? "enter")});` };
+    case "app_launch": {
+      const warnings = entry.bundleId ? [
+        {
+          type: "BUNDLE_ID_IGNORED",
+          message: `app_launch recorded with bundleId="${entry.bundleId}" \u2014 DSL appLaunch() reads bundle from APP_BUNDLE_ID env; override at runtime if needed.`
+        }
+      ] : [];
+      return { kind: "stmt", stmt: `appLaunch(${entry.clean ? "true" : "false"});`, warnings };
+    }
+    case "open_deeplink":
+      return { kind: "stmt", stmt: `openDeeplink(${JSON.stringify(entry.url ?? "")});` };
+    case "accept_alert":
+      return {
+        kind: "stmt",
+        stmt: entry.button ? `acceptAlert(${JSON.stringify(entry.button)});` : `acceptAlert();`
+      };
+    case "dismiss_alert":
+      return { kind: "stmt", stmt: `dismissAlert();` };
+  }
+}
+__name(renderEntry, "renderEntry");
 
 // src/fixtures/db.ts
 async function createDbClient(databaseUrl) {
@@ -5155,9 +6168,13 @@ async function buildApp(opts = {}) {
   const scenarioRepository = opts.scenarioRepository ?? new FileSystemScenarioRepository({ scenariosDir: scenariosDirAbs });
   const helperRepository = opts.helperRepository ?? new FileSystemHelperRepository({ scenariosDir: scenariosDirAbs });
   const scenarioLoader = new ScenarioLoader(scenarioRepository, helperRepository);
-  const sessionRecorder = new SessionRecorder(envConfig.SESSION_LOG_PATH);
-  const db = opts.db ?? await createDbClient(envConfig.DATABASE_URL);
-  const api = createApiClient(envConfig.API_BASE_URL, logger.child("api"));
+  const sessionRecorder = envConfig.SESSION_LOG_DISABLE || envConfig.SESSION_LOG_PATH === "" ? new NoopSessionRecorder() : new SessionRecorder(envConfig.SESSION_LOG_PATH, { full: envConfig.SESSION_LOG_FULL });
+  const exploration = new ExplorationService({
+    explorationsDir: resolve3(envConfig.explorationsDir)
+  });
+  const dslView = new DslViewService();
+  const db = opts.db ?? (envConfig.DATABASE_URL ? await createDbClient(envConfig.DATABASE_URL) : missingEnvDbClient());
+  const api = envConfig.API_BASE_URL ? createApiClient(envConfig.API_BASE_URL, logger.child("api")) : missingEnvApiClient();
   const shell2 = opts.shell ?? new NodeShellExecutor({
     logger: logger.child("shell"),
     defaultCwd: envConfig.PROJECT_ROOT ?? process.cwd()
@@ -5181,6 +6198,8 @@ async function buildApp(opts = {}) {
     helperRepository,
     scenarioLoader,
     sessionRecorder,
+    exploration,
+    dslView,
     db,
     api,
     shell: shell2,
@@ -5196,6 +6215,32 @@ async function buildApp(opts = {}) {
   };
 }
 __name(buildApp, "buildApp");
+function missingEnvDbClient() {
+  const fail = /* @__PURE__ */ __name(() => {
+    throw new Error(
+      `DATABASE_URL is not set in unotest/.env \u2014 required for dbQuery / dbExec. Set it (postgresql://, mysql://, or sqlite:) or remove the dbQuery / dbExec call from the scenario.`
+    );
+  }, "fail");
+  return {
+    query: /* @__PURE__ */ __name(() => fail(), "query"),
+    exec: /* @__PURE__ */ __name(() => fail(), "exec"),
+    close: /* @__PURE__ */ __name(async () => {
+    }, "close")
+  };
+}
+__name(missingEnvDbClient, "missingEnvDbClient");
+function missingEnvApiClient() {
+  const fail = /* @__PURE__ */ __name(() => {
+    throw new Error(
+      `API_BASE_URL is not set in unotest/.env \u2014 required for apiCall. Set it or remove the apiCall call from the scenario.`
+    );
+  }, "fail");
+  return {
+    call: /* @__PURE__ */ __name(() => fail(), "call"),
+    login: /* @__PURE__ */ __name(() => fail(), "login")
+  };
+}
+__name(missingEnvApiClient, "missingEnvApiClient");
 
 // src/dsl/variable-scope.ts
 var VariableScope = class {
@@ -5377,6 +6422,24 @@ function truncate2(s, max) {
 }
 __name(truncate2, "truncate");
 
+// src/util/cli-entry.ts
+function runMain(main2, errorExitCode) {
+  main2().then(
+    (code) => process.exit(code),
+    (e) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`\u2717 ${msg}
+`);
+      if (process.env.UNOTEST_DEBUG === "1" && e instanceof Error && e.stack) {
+        process.stderr.write(`${e.stack}
+`);
+      }
+      process.exit(errorExitCode);
+    }
+  );
+}
+__name(runMain, "runMain");
+
 // src/runner/cli.ts
 var HELP = `unotest-mobile \u2014 iOS E2E harness (JS-DSL runner).
 
@@ -5588,11 +6651,4 @@ async function cmdLint() {
   });
 }
 __name(cmdLint, "cmdLint");
-main().then(
-  (code) => process.exit(code),
-  (e) => {
-    console.error("[cli] fatal:", e);
-    process.exit(2);
-  }
-);
-//# sourceMappingURL=cli.js.map
+runMain(main, 2);