@unotest/mobile 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,86 @@ All notable changes to `@unotest/mobile` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.2] — 2026-05-18
+
+### Fixed — `type()` no longer drops 1-3 characters mid-string
+
+- **What broke.** `WdaDriver.type` issued `XCUIElement.typeText` at WDA's
+  default typing frequency (~60 letters/sec) into the simulator's iOS
+  keyboard. Under host contention (Claude Code + WDA build + Simulator
+  all running on the same Mac), the iOS keyboard layer couldn't keep
+  up and randomly dropped 1-3 characters from the middle of the string
+  — observed live as `petr@volkov.io` → `pr@volkov.io`, `Qwerty34##`
+  → `Qwery34##`. P4 / S8 had only addressed the unrelated *wrong-
+  keyboard-layout* failure (Cyrillic keyboard eating Latin chars
+  wholesale); this race is a separate failure mode that survived.
+- **Fix 1 — `ConnectHardwareKeyboard` pinned OFF on install.**
+  The `pinEnglishKeyboard` step (S8) now also writes
+  `ConnectHardwareKeyboard = false` into the Simulator.app preferences
+  on every install. When the toggle is ON (the default on a freshly
+  created sim, controlled by ⌘K inside the sim), iOS suppresses the
+  soft keyboard and routes keys through the host's physical keyboard
+  path — typeText then races against keyboard presentation. Pinning
+  OFF guarantees the soft keyboard renders and stays visible.
+  Idempotent. Reuses the existing `pinKeyboard: false` opt-out flag.
+- **Fix 2 — `WDA_TYPING_FREQUENCY` env (default `8`).** `WdaDriver.type`
+  now passes `frequency: <env>` in the POST `/element/{id}/value`
+  body, which WDA forwards to `fb_typeText:withFrequency:`. 8 cps is
+  conservative-but-still-usable: typical credentials (`petr@volkov.io`,
+  `Qwerty34##`) type in ~2s instead of the unreliable ~0.3s. Bump
+  higher if you trust your host's headroom; lower if you're seeing
+  drops in CI under heavy load. Validated as a positive integer at
+  `loadEnv` time.
+- **Why not pasteboard / per-char paste.** Researched approaches the
+  XCUITest community has tried (`UIPasteboard` + double-tap-menu paste,
+  per-char `typeKey:` calls, `setValue` direct-set): pasteboard paste
+  is **43% slower and flaky** (per iammike.org / 2022); per-char
+  `typeKey:` is only 3% faster than throttled `typeText`, complex to
+  wire reliably; `setValue` on native iOS text fields routes back to
+  `typeText` internally — there is no Apple-blessed "set text without
+  keyboard" API. WDA's own `maxTypingFrequency` is the documented knob.
+- **Tests:** +0 net. Modified 1 existing assertion to verify
+  `frequency: 8` lands in the request body. The hardware-keyboard
+  flip rides on the same `pinEnglishKeyboard` call site, so existing
+  call-sequence assertions still hold. Total 570.
+
+### Added — `WDA_TYPING_FREQUENCY` env var
+
+- Letters-per-second passed to WDA's `fb_typeText:withFrequency:` on
+  every `type(...)` call. Default `8`. See the fix entry above for
+  rationale on the conservative default.
+
+## [0.8.1] — 2026-05-18
+
+### Fixed — `init` pins the exact `@unotest/mobile` version in `.mcp.json`
+
+- **What broke.** The generated `.mcp.json` entry used a bare
+  `"args": ["-y", "@unotest/mobile"]` with no version pin. `npx` then
+  resolved that name against any **globally installed** copy first
+  (e.g. an old `npm i -g @unotest/mobile@0.1.x` from earlier
+  experimentation), bypassing the version the user just installed via
+  `npx @unotest/mobile@latest install ...`. The stale global frequently
+  had the pre-0.1.4 strict env schema, so the MCP server crashed at
+  startup with `Invalid environment. ... INVITE_DEEPLINK_PREFIX:
+  Required, API_BASE_URL: Required, ...`. Claude Code then surfaced
+  `-32000 Connection closed` and the agent fell back to draft-mode
+  scenario authoring — defeating the entire MCP-driven flow the
+  install just bootstrapped.
+- **Fix.** `init` now reads its own `package.json:version` and writes
+  the pinned form `"args": ["-y", "@unotest/mobile@<version>"]` into
+  `.mcp.json`. The MCP server Claude Code launches always matches the
+  `init`-running copy, so a stale global can no longer ambush startup.
+  Pre-release versions (e.g. `1.0.0-rc.3`) pass through verbatim.
+- **Migration.** Existing projects generated by `init` ≤ 0.8.0 keep
+  the bare entry. Run `npx @unotest/mobile@latest init --force` to
+  rewrite `.mcp.json` with the pinned form (preserves `.env`, only
+  rewrites templates).
+- Tests: +3 (`mcpServerEntry: pins to passed version`,
+  `pre-release versions pass through verbatim`,
+  `never emits a bare unversioned reference`). The third is the
+  belt-and-braces regression guard that fails loudly if anyone
+  reintroduces a bare `@unotest/mobile` arg in the template.
+
 ## [0.8.0] — 2026-05-18
 
 ### Fixed — WdaDriver auto-recovers from stale WDA sessions (B6)

package/README.md

@@ -1,123 +1,90 @@
 # `@unotest/mobile`
 
-**AI-native E2E testing for iOS React Native apps.** MCP server + CLI
-runner + JS-DSL scenarios. Project-agnostic — works with any RN/Expo app,
-not tied to a specific backend stack.
+**AI-native E2E testing for iOS apps.** An MCP server + CLI + JS-DSL
+that lets Claude (or any MCP client) drive your iOS Simulator and write
+real test scenarios for your app — works with any backend stack
+(Node/Python/Rails/Go/Java), no JS expertise required from you.
 
-Part of the `unotest` family. The web counterpart is a separate product.
-
-## Install
+## Quick start
 
 ```bash
-npm install --save-dev @unotest/mobile        # or yarn / pnpm — same effect
-npx @unotest/mobile init                      # bootstrap your project
-```
+# 1. Point us at your .app build. Auto-detects bundle ID, URL scheme,
+#    and required permissions from Info.plist; offers to bootstrap
+#    unotest/ and .mcp.json on first run.
+npx @unotest/mobile@latest install /path/to/Your.app --update-env
 
-`init` first runs an environment check (macOS / Xcode / iOS Simulator /
-Node 20+) and hard-fails on a non-macOS host before touching the
-filesystem. It then drops:
+# 2. Open Claude Code in this project. Ask: "write an e2e test for
+#    sign-in". The agent uses the MCP server to explore your app,
+#    record a scenario, and verify it runs end-to-end.
 
-- `unotest/e2e/` with a starter scenario, template, and `_helpers/` dir
-- `unotest/AGENTS.md` — short pointer for AI coding agents
-- `unotest/.env.example` (committed) and `unotest/.env` (gitignored)
-- `.claude/skills/write-e2e-test.md` — the Claude Code skill the agent
-  uses when asked to write a test
-- `.mcp.json` — project-scoped MCP registration (merges with existing)
-- `.gitignore` updates
+# 3. (Optional) Re-run any saved test from the CLI:
+npx @unotest/mobile@latest e2e <test-name>
+```
 
-`--force` overwrites existing files (except `unotest/.env`).
-`--allow-non-macos` lets you scaffold on a CI prep stage.
+That's it. You never edit DSL by hand — the agent writes the scenarios,
+you review the resulting `.js` files in `unotest/e2e/`.
 
-## Quick start
+## How it works
 
-```bash
-# 1. Edit unotest/.env — fill in DATABASE_URL, SIM_A_NAME, APP_BUNDLE_ID, ...
-# 2. Boot iOS simulators matching SIM_A_NAME / SIM_B_NAME (Xcode → Devices).
-# 3. Open Claude Code in this project — MCP server auto-registers via .mcp.json.
-#    Ask the agent to write a test; it follows the `write-e2e-test` skill.
-
-npx @unotest/mobile doctor               # re-check environment
-npx @unotest/mobile e2e smoke-welcome    # run the starter scenario
-npx @unotest/mobile lint                 # static check of all scenarios
 ```
-
-## What this gives you
-
-- **AI-driven authoring.** Claude (via MCP) sees your screen and
-  accessibility tree — it doesn't guess testIDs, it resolves them.
-- **Pause-on-failure debugger.** When a step fails, the runtime pauses;
-  use `inspect_runtime` / `step` / `resume` to fix and retry without
-  rerunning setup.
-- **Multi-device flows.** Two simulators in parallel — useful for
-  invite/share/handoff flows where one user's action must surface on
-  another user's device.
-- **Engine-agnostic.** Today's driver is WebDriverAgent (HTTP, no JVM);
-  swap to your own XCTest / idb backend without rewriting scenarios.
-
-## DSL — strict JS subset
-
-Scenarios are JS files (`unotest/e2e/*.js`) with one entry function per
-file. The full reference is bundled with the package as the
-`write-e2e-test` Claude Code skill — open
-`.claude/skills/write-e2e-test.md` after `init` for the cheat sheet.
-
-```js
-// id-smoke-welcome
-// First-run sanity: harness reaches sim, WDA, and app launch handshake
-// #00aa00
-function test_smoke_welcome() {
-  setDevice("A");
-  appLaunch(true);
-  waitFor(getByTestId("screen-welcome"), 15000);
-  assertVisible(getByTestId("btn-start"));
-}
+┌─────────────┐  MCP (stdio)   ┌──────────────────┐
+│ Claude Code │ ◀────────────▶ │ @unotest/mobile  │
+└─────────────┘   tool calls   │  (this package)  │
+                               └────────┬─────────┘
+                                        │ HTTP
+                               ┌────────▼──────────┐
+                               │  WebDriverAgent   │
+                               │  (Apple's XCUI    │
+                               │   driver, on sim) │
+                               └────────┬──────────┘
+                                        │
+                               ┌────────▼──────────┐
+                               │  iOS Simulator    │
+                               │  Your .app        │
+                               └───────────────────┘
 ```
 
-## MCP tools
-
-After `init`, Claude Code (or any MCP-aware client) gets:
+- **The agent sees the accessibility tree, not screenshots.** WDA
+  returns a structured tree (roles, testID, text, bounds); we render it
+  as a token-cheap text outline. Works on RN/Expo and on plain Swift
+  apps too, as long as they expose accessibility.
+- **Tests are plain `.js` files in your repo.** `unotest/e2e/*.js`.
+  Goes into git, into code review, into CI. No proprietary format, no
+  binary blob.
+- **The DSL is a sandboxed JS subset.** Scenarios run in a vendored AST
+  interpreter — they can't `require`, `fetch`, touch the filesystem, or
+  import anything. AI-generated tests are safe to run blindly.
+- **Pause-on-failure debugger.** When a step throws, the runtime
+  freezes mid-scenario. The agent (or you) calls `inspect_runtime`,
+  patches the scenario, and `resume`s from the same step — no full
+  simulator restart, no rerunning setup.
+- **Local-only.** Everything runs on your Mac. Your `.app` never leaves
+  the machine.
+
+**Life of a test:** the agent explores your app live (taps real
+buttons, reads the live a11y tree) → records the actions → emits a JS
+scenario → runs it through our interpreter → on failure, pauses,
+patches, resumes. Every step goes through one of ~15 MCP tools the
+agent already knows; you don't wire anything.
 
-**Discovery + lifecycle:**
-`devices_list`, `screenshot`, `a11y_tree`, `resolve_selector`,
-`app_install`, `session_reset`.
-
-**Exploration recording (P2):**
-`explore_start`, `explore_step`, `explore_record`, `explore_remove_step`,
-`explore_state`, `explore_stop`, `generate_dsl_from_exploration`,
-`save_exploration_as_test`. `explore_step` is the single execute-and-
-optionally-record entry point for all UI actions (tap, type, press_key,
-swipe, wait_for, app_launch, open_deeplink, accept_alert, dismiss_alert).
-Pass `explorationId` to record into a session, omit it for ad-hoc.
+## Requirements
 
-**Pause-on-failure debugger:**
-`run_test` (with `pauseOnFailure: true`), `step`, `resume`,
-`inspect_runtime`, `abort_runtime`, `list_runtimes`.
+- **macOS** with Xcode + iOS Simulator (Apple licensing — iOS
+  simulators don't run on Linux/Windows).
+- **Node 20+** (for `npx`; you don't need a Node project).
+- First run of WebDriverAgent compiles once and caches under
+  `~/.cache/unotest/mobile/wda/` — ~5–15 min, subsequent runs reuse it.
 
 ## CLI
 
 | Command | What it does |
 |---|---|
-| `npx @unotest/mobile init` | Bootstrap a consumer project. Idempotent. |
-| `npx @unotest/mobile doctor` | Re-run environment checks. |
-| `npx @unotest/mobile e2e <name>` | Run `unotest/e2e/<name>.js`. Supports nested paths. |
-| `npx @unotest/mobile lint` | Static check of all scenarios + helpers. |
-| `npx @unotest/mobile` (no args) | Run as MCP stdio server. |
-
-## Requirements
-
-- **macOS** with Xcode + iOS Simulator (Apple licensing — iOS simulators
-  cannot run on Linux/Windows hosts).
-- **Node 20+**.
-- **Xcode command-line tools** for the on-demand WebDriverAgent build.
-  WDA is compiled once and cached in
-  `~/.cache/unotest/mobile/wda/<version>/` — first build is ~5–15
-  minutes, subsequent runs reuse the cache.
-
-## Status
-
-`0.1.0` — initial public release. iOS-focused (RN, Expo, native Swift).
-Android driver is on the roadmap. Local execution only; cloud runners
-will follow.
+| `npx @unotest/mobile@latest install <path>` | Install a `.app` on the configured sim; auto-detect bundle ID + permissions; `--update-env` persists. |
+| `npx @unotest/mobile@latest init` | Just bootstrap `unotest/` + `.mcp.json` without installing an app. |
+| `npx @unotest/mobile@latest doctor` | Re-check the environment (Xcode, sim, Node, WDA cache). |
+| `npx @unotest/mobile@latest e2e <name>` | Run `unotest/e2e/<name>.js`. |
+| `npx @unotest/mobile@latest lint` | Static check of all scenarios + helpers. |
+| `npx @unotest/mobile@latest` (no args) | Run as MCP stdio server (this is what Claude Code launches). |
 
 ## License
 

package/dist/mcp/server.js

@@ -240,6 +240,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -287,6 +296,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -294,6 +308,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -636,6 +651,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -690,8 +716,11 @@ var SimctlAdapter = class {
   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. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -1277,7 +1306,8 @@ Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH
     await this.withFreshSession(slot, async (session) => {
       const elementId = await this.resolveElementId(slot, selector);
       await session.client.setElementValue(session.getSessionId(), elementId, {
-        value: Array.from(text)
+        value: Array.from(text),
+        frequency: this.deps.typingFrequency
       });
     });
   }
@@ -1578,6 +1608,7 @@ function createDriver(cfg) {
         simBySlot: cfg.env.simBySlot,
         wdaPortBySlot: cfg.env.wdaPortBySlot,
         appBundleId: cfg.env.APP_BUNDLE_ID,
+        typingFrequency: cfg.env.wdaTypingFrequency,
         binaryProvider
       });
     }
@@ -6819,7 +6850,7 @@ async function installApp2(opts, deps) {
       }
     }
     if (opts.pinKeyboard !== false) {
-      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      deps.logger.info(`[${slot}] pinning keyboard (en_US@QWERTY, soft only)`);
       await deps.simctl.pinEnglishKeyboard(sim.udid);
     }
     let launched = false;

package/dist/runner/cli.js

@@ -236,6 +236,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -283,6 +292,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -290,6 +304,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -632,6 +647,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -686,8 +712,11 @@ var SimctlAdapter = class {
   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. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -1273,7 +1302,8 @@ Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH
     await this.withFreshSession(slot, async (session) => {
       const elementId = await this.resolveElementId(slot, selector);
       await session.client.setElementValue(session.getSessionId(), elementId, {
-        value: Array.from(text)
+        value: Array.from(text),
+        frequency: this.deps.typingFrequency
       });
     });
   }
@@ -1574,6 +1604,7 @@ function createDriver(cfg) {
         simBySlot: cfg.env.simBySlot,
         wdaPortBySlot: cfg.env.wdaPortBySlot,
         appBundleId: cfg.env.APP_BUNDLE_ID,
+        typingFrequency: cfg.env.wdaTypingFrequency,
         binaryProvider
       });
     }

package/dist/runner/init.js

@@ -272,6 +272,11 @@ APP_BUNDLE_ID=com.example.myapp
 WDA_PORTS=A=8100,B=8101
 # WDA_DEFAULT_ACTION_WAIT_MS=2000
 # WDA_DEFAULT_WAITFOR_TIMEOUT_MS=10000
+# Letters/sec for type() \u2014 WDA's fb_typeText:withFrequency:. Conservative
+# default avoids char-drop races against the iOS keyboard layer when the
+# host is under load. Bump higher (e.g. 20) on a quiet machine; lower
+# (e.g. 4) if you still see drops in CI.
+# WDA_TYPING_FREQUENCY=8
 
 # --- Artifacts / sessions / paused-runtime TTL -----------------------------
 # Defaults are sensible \u2014 uncomment only to override.
@@ -290,10 +295,20 @@ WDA_PORTS=A=8100,B=8101
     "unotest/artifacts/",
     "unotest/sessions/"
   ],
-  mcpServerEntry: {
+  /**
+   * Build the `.mcp.json` entry for this package, pinned to the supplied
+   * version. Caller (`runInit`) reads its own `package.json:version` and
+   * passes it in, so the entry written into the consumer's project
+   * always matches the `init`-running copy. Pinning side-steps the
+   * `npx` stale-global / stale-cache ambush: a bare `@unotest/mobile`
+   * arg lets `npx` resolve to whatever globally-installed (often very
+   * old) copy a developer happens to have, which then crashes at
+   * startup against the current env schema.
+   */
+  mcpServerEntry: /* @__PURE__ */ __name((version) => ({
     command: "npx",
-    args: ["-y", "@unotest/mobile"]
-  }
+    args: ["-y", `@unotest/mobile@${version}`]
+  }), "mcpServerEntry")
 };
 
 // src/runner/init/mcp-config-merger.ts
@@ -391,6 +406,20 @@ function readPackageFile(relativePath) {
   return readFileSync(abs, "utf8");
 }
 __name(readPackageFile, "readPackageFile");
+function readOwnVersion() {
+  const pkgRaw = readPackageFile("package.json");
+  if (pkgRaw === null) {
+    throw new Error(
+      `package.json missing at ${packageRoot}. This is a packaging bug \u2014 reinstall \`@unotest/mobile\` or report the issue.`
+    );
+  }
+  const parsed = JSON.parse(pkgRaw);
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error(`package.json:version is not a non-empty string`);
+  }
+  return parsed.version;
+}
+__name(readOwnVersion, "readOwnVersion");
 function runInit(argv = process.argv.slice(2)) {
   const opts = parseInitArgs(argv);
   const target = process.cwd();
@@ -446,10 +475,7 @@ function runInit(argv = process.argv.slice(2)) {
     const merge = mergeMcpConfig(
       existing,
       "unotest-mobile",
-      {
-        command: templates.mcpServerEntry.command,
-        args: [...templates.mcpServerEntry.args]
-      },
+      templates.mcpServerEntry(readOwnVersion()),
       { force: opts.force }
     );
     if (merge.action !== "already-present") {

package/dist/runner/install.js

@@ -84,6 +84,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -131,6 +140,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -138,6 +152,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -364,6 +379,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -418,8 +444,11 @@ var SimctlAdapter = class {
   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. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -912,6 +941,11 @@ APP_BUNDLE_ID=com.example.myapp
 WDA_PORTS=A=8100,B=8101
 # WDA_DEFAULT_ACTION_WAIT_MS=2000
 # WDA_DEFAULT_WAITFOR_TIMEOUT_MS=10000
+# Letters/sec for type() \u2014 WDA's fb_typeText:withFrequency:. Conservative
+# default avoids char-drop races against the iOS keyboard layer when the
+# host is under load. Bump higher (e.g. 20) on a quiet machine; lower
+# (e.g. 4) if you still see drops in CI.
+# WDA_TYPING_FREQUENCY=8
 
 # --- Artifacts / sessions / paused-runtime TTL -----------------------------
 # Defaults are sensible \u2014 uncomment only to override.
@@ -930,10 +964,20 @@ WDA_PORTS=A=8100,B=8101
     "unotest/artifacts/",
     "unotest/sessions/"
   ],
-  mcpServerEntry: {
+  /**
+   * Build the `.mcp.json` entry for this package, pinned to the supplied
+   * version. Caller (`runInit`) reads its own `package.json:version` and
+   * passes it in, so the entry written into the consumer's project
+   * always matches the `init`-running copy. Pinning side-steps the
+   * `npx` stale-global / stale-cache ambush: a bare `@unotest/mobile`
+   * arg lets `npx` resolve to whatever globally-installed (often very
+   * old) copy a developer happens to have, which then crashes at
+   * startup against the current env schema.
+   */
+  mcpServerEntry: /* @__PURE__ */ __name((version) => ({
     command: "npx",
-    args: ["-y", "@unotest/mobile"]
-  }
+    args: ["-y", `@unotest/mobile@${version}`]
+  }), "mcpServerEntry")
 };
 
 // src/runner/init/mcp-config-merger.ts
@@ -1031,6 +1075,20 @@ function readPackageFile(relativePath) {
   return readFileSync(abs, "utf8");
 }
 __name(readPackageFile, "readPackageFile");
+function readOwnVersion() {
+  const pkgRaw = readPackageFile("package.json");
+  if (pkgRaw === null) {
+    throw new Error(
+      `package.json missing at ${packageRoot}. This is a packaging bug \u2014 reinstall \`@unotest/mobile\` or report the issue.`
+    );
+  }
+  const parsed = JSON.parse(pkgRaw);
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error(`package.json:version is not a non-empty string`);
+  }
+  return parsed.version;
+}
+__name(readOwnVersion, "readOwnVersion");
 function runInit(argv = process.argv.slice(2)) {
   const opts = parseInitArgs(argv);
   const target = process.cwd();
@@ -1086,10 +1144,7 @@ function runInit(argv = process.argv.slice(2)) {
     const merge = mergeMcpConfig(
       existing,
       "unotest-mobile",
-      {
-        command: templates.mcpServerEntry.command,
-        args: [...templates.mcpServerEntry.args]
-      },
+      templates.mcpServerEntry(readOwnVersion()),
       { force: opts.force }
     );
     if (merge.action !== "already-present") {
@@ -1303,7 +1358,7 @@ async function installApp2(opts, deps) {
       }
     }
     if (opts.pinKeyboard !== false) {
-      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      deps.logger.info(`[${slot}] pinning keyboard (en_US@QWERTY, soft only)`);
       await deps.simctl.pinEnglishKeyboard(sim.udid);
     }
     let launched = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/mobile",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "AI-native E2E testing for iOS React Native apps. MCP server + CLI runner + JS-DSL scenarios.",
   "license": "MIT",
   "type": "module",