@ait-co/devtools 0.1.136 → 0.1.138

package/dist/test-runner/config.d.ts

@@ -1,4 +1,4 @@
-import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-C6TgrcyW.js";
+import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-CrP5CPvU.js";
 
 //#region src/test-runner/relay-factory.d.ts
 /** Options for {@link createRelayConnectionFactory}. */
@@ -7,8 +7,36 @@ interface RelayConnectionFactoryOptions {
    * intoss-private:// scheme URL from `ait deploy --scheme-only` (env3). The
    * phone cold-loads the candidate bundle this URL points at. SECRET-HANDLING:
    * never logged.
+   *
+   * Ignored when {@link attachLauncher} is `true` — the env-2 launcher path
+   * builds its attach URL from {@link appUrl} + the relay wss, not a scheme URL.
+   * Pass `''` in that case.
    */
   schemeUrl: string;
+  /**
+   * env-2 (AITC Sandbox PWA) attach mode (devtools#774). When `true`, `open()`
+   * builds the attach URL as a **launcher deep-link**
+   * (`buildLauncherAttachUrl(appUrl, wssUrl, totp)` — the same env-2 path the
+   * MCP daemon takes via `prepareAttach(deps, 'relay-mobile', …)`, issue #378)
+   * instead of an intoss-private scheme deep-link. The relay boot, QR
+   * rendering, dashboard, and attach-wait are byte-for-byte identical to env 3;
+   * only the URL family differs. Omitted/false keeps the env-3 scheme path
+   * unchanged (zero behavior change).
+   */
+  attachLauncher?: boolean;
+  /**
+   * The consumer dev server's HTTP tunnel URL (e.g. an sdk-example
+   * `dev:phone:cdp` `*.trycloudflare.com` URL) that the launcher PWA frames.
+   * REQUIRED when {@link attachLauncher} is `true`; ignored otherwise.
+   *
+   * Threaded to the `relay-mobile` `prepareAttach` branch via the
+   * `AIT_TUNNEL_BASE_URL` env var (the same key the MCP daemon reads), so the
+   * exact same env-2 assembly runs — no divergent code path.
+   *
+   * SECRET-HANDLING: this is a tunnel host at the same sensitivity as the relay
+   * wss — NEVER logged. It rides only inside the QR/dashboard attach capsule.
+   */
+  appUrl?: string;
   /**
    * Project root for the `.ait_relay` secret lookup (read-only). Defaults to
    * `process.cwd()`.
@@ -35,6 +63,40 @@ interface RelayConnectionFactoryOptions {
     sdkLine: string;
     platform: string;
   };
+  /**
+   * When `true`, injects `__AIT_STUB_BLOCKING__ = true` before the first test
+   * bundle runs (devtools#740, DT-2) — `bundle.ts`'s sdk-redirect module reads
+   * this flag via `isStubBlockingEnabled()` and answers the blocking-UI APIs
+   * in `bridge-stub.ts`'s `STUB_REGISTRY` from fixtures instead of forwarding
+   * them to native. Optional — omitted/false means no flag is injected, which
+   * is byte-for-byte the pre-#740 behavior (the sdk-redirect module treats
+   * absence the same as `false`). Not a secret.
+   */
+  stubBlocking?: boolean;
+  /**
+   * Injects `__AIT_PACE_MS__ = paceMs` before the first test bundle runs
+   * (devtools#767) — `runtime.ts`'s test-execution loop reads this page
+   * global and waits `paceMs` before every test after the first one that
+   * actually runs. Optional — omitted/0 means no flag is injected, which is
+   * byte-for-byte the pre-#767 behavior (the loop treats an absent/non-
+   * positive value as "no pacing"). Not a secret. This is the PAGE-side half
+   * of `--pace`; the RUNNER-side (file-to-file) half is a plain `opts.paceMs`
+   * forwarded to `runTestFilesOverRelay` by the caller (cli.ts) — this
+   * factory only owns the page-global injection.
+   */
+  paceMs?: number;
+  /**
+   * Injects `__AIT_PACE_METHOD_MS__ = paceMethodMs` before the first test
+   * bundle runs (devtools#769) — `bundle.ts`'s sdk-redirect virtual module
+   * reads this page global via `method-pace.ts#getPaceMethodMs()` and paces
+   * every SDK call to a minimum interval BETWEEN calls to the SAME named
+   * function, independent of `--pace`'s test-to-test/file-to-file spacing.
+   * Optional — omitted/0 means no flag is injected, which is byte-for-byte
+   * the pre-#769 behavior (`getPaceMethodMs()` treats an absent/non-positive
+   * value as "no pacing", and `wrapWithMethodPacing` returns the SDK object
+   * untouched in that case). Not a secret.
+   */
+  paceMethodMs?: number;
   /**
    * Overrides the dashboard HTTP server's bind base port (devtools#752).
    * Threaded straight through to `startQrHttpServer`'s `dashboardPort`
@@ -62,12 +124,13 @@ interface RelayConnectionFactoryOptions {
   onQrContent: (textChunks: string[]) => void;
 }
 /**
- * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay
- * connection.
+ * Builds a {@link RelayConnectionFactory} that opens a standalone relay
+ * connection for env 3 (intoss-private scheme, default) or env 2 (AITC Sandbox
+ * PWA launcher deep-link, when `opts.attachLauncher` is set — devtools#774).
  *
  * `open()` performs the full attach lifecycle and BLOCKS while a human scans
- * the rendered QR with their phone — there is no way around the manual scan
- * for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
+ * the rendered QR with their phone — there is no way around the manual scan.
+ * By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
  * runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is
  * a human-paced action with no sound default bound (devtools#735). Passing an
  * explicit `timeoutMs` opts into the old bounded behavior (CI/headless

package/dist/test-runner/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","names":[],"sources":["../../src/test-runner/relay-factory.ts","../../src/test-runner/config.ts"],"mappings":";;;;UAiDiB,6BAAA;ECPD;AAIhB;;;;EDSE,SAAA;ECPA;;;;EDYA,WAAA;ECKmC;;;;;;;;AAcrC;EDTE,SAAA;;EAEA,QAAA;ECSA;;;;;EDHA,IAAA;IAAS,OAAA;IAAiB,QAAA;EAAA;;;;;;;;EAQ1B,aAAA;ECqCc;;;;;;;;;;;;;;;;EDpBd,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;;;;;;;iBAoBA,4BAAA,CACd,IAAA,EAAM,6BAAA,GACL,sBAAA;;;;;;UCjGc,eAAA;EDgGf;;;;EC3FA,OAAA;;;AALF;EASE,SAAA;;;;;EAKA,cAAA;AAAA;;UAIe,mBAAA;EACf,OAAA;EACA,SAAA;EACA,cAAA;AAAA;;;;;AAgBF;;;iBAAgB,qBAAA,CAAsB,UAAA,GAAa,mBAAA,GAAsB,eAAA;;;;;;AAczE;UAAiB,qBAAA;;EAEf,IAAA,EAAM,UAAA,QAAkB,eAAA;EAAxB;EAEA,OAAA;EAFwB;EAIxB,WAAA;AAAA;;UAIe,qBAAA,SAA8B,mBAAA;EAA9B;;;;;;;EAQf,UAAA,EAAY,sBAAA;EAQG;;AAkBjB;;;;;EAlBE,eAAA;AAAA;;;;;;;;;;;;;;;;iBAkBc,uBAAA,CAAwB,UAAA,EAAY,qBAAA,GAAwB,qBAAA"}
+{"version":3,"file":"config.d.ts","names":[],"sources":["../../src/test-runner/relay-factory.ts","../../src/test-runner/config.ts"],"mappings":";;;;UAiDiB,6BAAA;ECrBe;;;;;;AAkBhC;;;EDaE,SAAA;ECZA;;;;;AAkBF;;;;;EDKE,cAAA;ECLuE;;;AAczE;;;;;;;;;EDIE,MAAA;ECEW;AAIb;;;EDDE,WAAA;ECC6C;;;;;;AAkC/C;;;EDzBE,SAAA;ECyBkD;EDvBlD,QAAA;ECuB0E;;;;;EDjB1E,IAAA;IAAS,OAAA;IAAiB,QAAA;EAAA;;;;;;;;;;EAU1B,YAAA;;;;;;;;;;;;EAYA,MAAA;;;;;;;;;;;;EAYA,YAAA;;;;;;;;EAQA,aAAA;;;;;;;;;;;;;;;;;EAiBA,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;;;;;;;;iBAqBA,4BAAA,CACd,IAAA,EAAM,6BAAA,GACL,sBAAA;;;;;;UChKc,eAAA;ED8JD;;;;ECzJd,OAAA;ED0JA;;;ECtJA,SAAA;;;;AATF;EAcE,cAAA;AAAA;;UAIe,mBAAA;EACf,OAAA;EACA,SAAA;EACA,cAAA;AAAA;AAHF;;;;;;;AAAA,iBAmBgB,qBAAA,CAAsB,UAAA,GAAa,mBAAA,GAAsB,eAAA;;AAAzE;;;;;UAciB,qBAAA;EAdwD;EAgBvE,IAAA,EAAM,UAAA,QAAkB,eAAA;EAhB8D;EAkBtF,OAAA;EAJoC;EAMpC,WAAA;AAAA;;UAIe,qBAAA,SAA8B,mBAAA;EARrB;;;;;AAQ1B;;EAQE,UAAA,EAAY,sBAAA;EARoD;;;;;;;EAgBhE,eAAA;AAAA;;;;;;;;;;;;;;;;iBAkBc,uBAAA,CAAwB,UAAA,EAAY,qBAAA,GAAwB,qBAAA"}

package/dist/test-runner/config.js

@@ -1,5 +1,5 @@
 import { RELAY_POOL_NAME, createRelayPool } from "./pool.js";
-import { t as createRelayConnectionFactory } from "../relay-factory-DnuTH4v-.js";
+import { t as createRelayConnectionFactory } from "../relay-factory-C1X3G3WY.js";
 //#region src/test-runner/config.ts
 const DEFAULT_CONFIG = {
 	include: ["**/*.ait.test.ts"],

package/dist/test-runner/method-pace.d.ts

@@ -0,0 +1,82 @@
+//#region src/test-runner/method-pace.d.ts
+/**
+ * Per-method minimum-interval pacing for SDK calls (devtools#769).
+ *
+ * #767's `--pace` inserts delays BETWEEN test files / test-to-test — it has no
+ * effect on a burst of same-method calls WITHIN a single test body (e.g. a
+ * clipboard happy-path loop calling `setClipboardText`/`getClipboardText`
+ * eight times back to back). Real-device observation (sdk-example#293,
+ * 2.x×iOS) showed that burst alone is enough to saturate the native
+ * per-method bridge rate limit (`APP_BRIDGE_THROTTLED`, devtools#767/throttle.ts)
+ * even though `--pace`'s file/test spacing was already in effect — the
+ * limiter reacts to burst cadence within a method name, not just across test
+ * boundaries.
+ *
+ * This module wraps `window.__sdk` (the same bridge object `bundle.ts`'s
+ * `sdkRedirectPlugin` redirects SDK imports to) so that every call to the
+ * SAME named function waits out a minimum gap since that function's PREVIOUS
+ * invocation before the real call proceeds. Preflight (`cell.ts`) proved the
+ * inverse case empirically: a steady 250ms sequential cadence passes cleanly
+ * where an unpaced burst does not — sequential-with-spacing is the fix this
+ * module generalizes to every SDK call, not just the six permission probes.
+ *
+ * Runs entirely on the PAGE side (browser-compatible, no Node APIs) — bundled
+ * into the injected IIFE by `bundle.ts`'s `sdkRedirectPlugin`, the same way
+ * `bridge-stub.ts` and `runtime.ts` are. Imported ONLY from the test-runner
+ * (never from `sdk-example/src` — boilerplate cleanliness, umbrella §1.4).
+ *
+ * SECRET-HANDLING: this module carries no secrets — only method names and
+ * millisecond timestamps/durations.
+ */
+/**
+ * Reads the page-global `__AIT_PACE_METHOD_MS__` gap value (devtools#769),
+ * injected by `relay-factory.ts` the same way `__AIT_PACE_MS__`/`__AIT_CELL__`
+ * are (`cell.ts#injectGlobals`). Absent/non-positive resolves to `0` — the
+ * same "treat absence as zero" contract `runtime.ts`'s `__AIT_PACE_MS__` read
+ * uses.
+ */
+declare function getPaceMethodMs(): number;
+/**
+ * Wraps an SDK-shaped bridge object (`window.__sdk`, or the already
+ * stub-wrapped result of `bridge-stub.ts#wrapSdkWithStub`) so that every
+ * function-valued export is paced to a minimum `gapMs` interval between
+ * calls to the SAME name (devtools#769). Non-function exports (constants,
+ * etc.) and classes (`PermissionError`, etc. — wrapping a class would break
+ * `new`, see `isClass`) pass through completely untouched.
+ *
+ * **Composition with bridge-stub (devtools#740)**: this wrapper is applied to
+ * the RAW `window.__sdk` object, and `wrapSdkWithStub` is applied on TOP of
+ * the paced result (`wrapSdkWithStub(wrapWithMethodPacing(rawSdk, gapMs),
+ * stubEnabled)` — see `bundle.ts`'s sdk-redirect virtual module). This means
+ * pacing sits BEHIND the stub interception: a stubbed name
+ * (`STUB_REGISTRY` — `openPermissionDialog`, `requestPermission`,
+ * `saveBase64Data`, `showFullScreenAd`) resolves instantly from the fixture
+ * with no added delay, because `wrapSdkWithStub`'s Proxy intercepts the
+ * property access before the paced function is ever reached. Only calls that
+ * fall through to the REAL bridge — the ones that actually risk
+ * `APP_BRIDGE_THROTTLED` — pay the pacing cost. Fixed by this ordering, not
+ * incidental: swapping it (pacing outside the stub) would pace fixture
+ * look-ups that can never hit the native rate limiter, for no benefit.
+ *
+ * `gapMs <= 0` (the default, no `--pace-method` / non-2.x cell) returns `sdk`
+ * itself, untouched — the exact object identity is preserved so the
+ * zero-diff-when-off contract holds under strict-equality checks, matching
+ * `wrapSdkWithStub`'s own `enabled === false` fast path.
+ *
+ * **Memoization**: wrapper functions are cached per name in a `Map` local to
+ * this call's `Proxy` (`wrapperCache` below), so repeated property access on
+ * the SAME `sdk` object within a single `wrapWithMethodPacing` call returns
+ * the SAME wrapper reference. This cache does NOT persist across separate
+ * `wrapWithMethodPacing` calls — each call (e.g. the sdk-redirect virtual
+ * module re-evaluated per test file bundle) gets its own fresh `Map` and
+ * therefore its own wrapper function instances, even for the same method
+ * name. That's fine for pacing correctness: the actual timing state lives in
+ * the page-global `getRegistry()` map (keyed by method name, not by wrapper
+ * identity), so cross-bundle pacing still works. But callers should NOT
+ * assume cross-call function identity — only "same wrapper within one call"
+ * is guaranteed.
+ */
+declare function wrapWithMethodPacing(sdk: Record<string, unknown>, gapMs: number): Record<string, unknown>;
+//#endregion
+export { getPaceMethodMs, wrapWithMethodPacing };
+//# sourceMappingURL=method-pace.d.ts.map

package/dist/test-runner/method-pace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-pace.d.ts","names":[],"sources":["../../src/test-runner/method-pace.ts"],"mappings":";;AAmFA;;;;;AA4EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA5EgB,eAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4EA,oBAAA,CACd,GAAA,EAAK,MAAA,mBACL,KAAA,WACC,MAAA"}

package/dist/test-runner/method-pace.js

@@ -0,0 +1,120 @@
+//#region src/test-runner/method-pace.ts
+const REGISTRY_KEY = "__AIT_METHOD_PACE_STATE__";
+/** Reads (or lazily creates) the page-global per-method pacing registry. */
+function getRegistry() {
+	const g = globalThis;
+	let state = g[REGISTRY_KEY];
+	if (!(state instanceof Map)) {
+		state = /* @__PURE__ */ new Map();
+		g[REGISTRY_KEY] = state;
+	}
+	return state;
+}
+/** `setTimeout`-based sleep — no Node APIs, safe on the page side. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* True when `value` is a `class` declaration rather than a plain callable
+* function. The SDK export surface includes at least one class (`PermissionError`,
+* `src/__typecheck.ts`/`bridge-stub.ts` both reference it) — wrapping a class
+* in an async arrow function would silently break `new PermissionError()`
+* (arrow functions are not constructible), so classes must pass through
+* `wrapWithMethodPacing` unwrapped exactly like any other non-callable
+* export. Detected via `Function.prototype.toString` starting with
+* `"class "` — the standard, spec-guaranteed way to distinguish a class from
+* an ordinary function at runtime (no Babel/TS transform in this bundle
+* target — `target: 'es2022'` in `bundle.ts` — down-compiles `class` to a
+* function, so this check remains reliable for esbuild's es2022 output).
+*/
+function isClass(value) {
+	return Function.prototype.toString.call(value).startsWith("class ");
+}
+/**
+* Reads the page-global `__AIT_PACE_METHOD_MS__` gap value (devtools#769),
+* injected by `relay-factory.ts` the same way `__AIT_PACE_MS__`/`__AIT_CELL__`
+* are (`cell.ts#injectGlobals`). Absent/non-positive resolves to `0` — the
+* same "treat absence as zero" contract `runtime.ts`'s `__AIT_PACE_MS__` read
+* uses.
+*/
+function getPaceMethodMs() {
+	const raw = globalThis.__AIT_PACE_METHOD_MS__;
+	return typeof raw === "number" && raw > 0 ? raw : 0;
+}
+/**
+* Wraps a single named SDK function so that calls to it wait out `gapMs`
+* since the function's own previous invocation (tracked in the shared
+* `getRegistry()` map, keyed by `name`) before the real `fn` runs. The
+* result/rejection of `fn` passes through completely unchanged — pacing
+* never alters contract-observed behavior, only its timing.
+*/
+function buildPacedFunction(name, fn, gapMs) {
+	return async (...args) => {
+		const registry = getRegistry();
+		const now = performance.now();
+		const lastInvokeAt = registry.get(name);
+		if (lastInvokeAt !== void 0) {
+			const elapsed = now - lastInvokeAt;
+			if (elapsed < gapMs) await sleep(gapMs - elapsed);
+		}
+		registry.set(name, performance.now());
+		return fn(...args);
+	};
+}
+/**
+* Wraps an SDK-shaped bridge object (`window.__sdk`, or the already
+* stub-wrapped result of `bridge-stub.ts#wrapSdkWithStub`) so that every
+* function-valued export is paced to a minimum `gapMs` interval between
+* calls to the SAME name (devtools#769). Non-function exports (constants,
+* etc.) and classes (`PermissionError`, etc. — wrapping a class would break
+* `new`, see `isClass`) pass through completely untouched.
+*
+* **Composition with bridge-stub (devtools#740)**: this wrapper is applied to
+* the RAW `window.__sdk` object, and `wrapSdkWithStub` is applied on TOP of
+* the paced result (`wrapSdkWithStub(wrapWithMethodPacing(rawSdk, gapMs),
+* stubEnabled)` — see `bundle.ts`'s sdk-redirect virtual module). This means
+* pacing sits BEHIND the stub interception: a stubbed name
+* (`STUB_REGISTRY` — `openPermissionDialog`, `requestPermission`,
+* `saveBase64Data`, `showFullScreenAd`) resolves instantly from the fixture
+* with no added delay, because `wrapSdkWithStub`'s Proxy intercepts the
+* property access before the paced function is ever reached. Only calls that
+* fall through to the REAL bridge — the ones that actually risk
+* `APP_BRIDGE_THROTTLED` — pay the pacing cost. Fixed by this ordering, not
+* incidental: swapping it (pacing outside the stub) would pace fixture
+* look-ups that can never hit the native rate limiter, for no benefit.
+*
+* `gapMs <= 0` (the default, no `--pace-method` / non-2.x cell) returns `sdk`
+* itself, untouched — the exact object identity is preserved so the
+* zero-diff-when-off contract holds under strict-equality checks, matching
+* `wrapSdkWithStub`'s own `enabled === false` fast path.
+*
+* **Memoization**: wrapper functions are cached per name in a `Map` local to
+* this call's `Proxy` (`wrapperCache` below), so repeated property access on
+* the SAME `sdk` object within a single `wrapWithMethodPacing` call returns
+* the SAME wrapper reference. This cache does NOT persist across separate
+* `wrapWithMethodPacing` calls — each call (e.g. the sdk-redirect virtual
+* module re-evaluated per test file bundle) gets its own fresh `Map` and
+* therefore its own wrapper function instances, even for the same method
+* name. That's fine for pacing correctness: the actual timing state lives in
+* the page-global `getRegistry()` map (keyed by method name, not by wrapper
+* identity), so cross-bundle pacing still works. But callers should NOT
+* assume cross-call function identity — only "same wrapper within one call"
+* is guaranteed.
+*/
+function wrapWithMethodPacing(sdk, gapMs) {
+	if (!(gapMs > 0)) return sdk;
+	const wrapperCache = /* @__PURE__ */ new Map();
+	return new Proxy(sdk, { get(target, prop, receiver) {
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof prop !== "string" || typeof value !== "function" || isClass(value)) return value;
+		const cached = wrapperCache.get(prop);
+		if (cached !== void 0) return cached;
+		const wrapped = buildPacedFunction(prop, value, gapMs);
+		wrapperCache.set(prop, wrapped);
+		return wrapped;
+	} });
+}
+//#endregion
+export { getPaceMethodMs, wrapWithMethodPacing };
+
+//# sourceMappingURL=method-pace.js.map

package/dist/test-runner/method-pace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-pace.js","names":[],"sources":["../../src/test-runner/method-pace.ts"],"sourcesContent":["/**\n * Per-method minimum-interval pacing for SDK calls (devtools#769).\n *\n * #767's `--pace` inserts delays BETWEEN test files / test-to-test — it has no\n * effect on a burst of same-method calls WITHIN a single test body (e.g. a\n * clipboard happy-path loop calling `setClipboardText`/`getClipboardText`\n * eight times back to back). Real-device observation (sdk-example#293,\n * 2.x×iOS) showed that burst alone is enough to saturate the native\n * per-method bridge rate limit (`APP_BRIDGE_THROTTLED`, devtools#767/throttle.ts)\n * even though `--pace`'s file/test spacing was already in effect — the\n * limiter reacts to burst cadence within a method name, not just across test\n * boundaries.\n *\n * This module wraps `window.__sdk` (the same bridge object `bundle.ts`'s\n * `sdkRedirectPlugin` redirects SDK imports to) so that every call to the\n * SAME named function waits out a minimum gap since that function's PREVIOUS\n * invocation before the real call proceeds. Preflight (`cell.ts`) proved the\n * inverse case empirically: a steady 250ms sequential cadence passes cleanly\n * where an unpaced burst does not — sequential-with-spacing is the fix this\n * module generalizes to every SDK call, not just the six permission probes.\n *\n * Runs entirely on the PAGE side (browser-compatible, no Node APIs) — bundled\n * into the injected IIFE by `bundle.ts`'s `sdkRedirectPlugin`, the same way\n * `bridge-stub.ts` and `runtime.ts` are. Imported ONLY from the test-runner\n * (never from `sdk-example/src` — boilerplate cleanliness, umbrella §1.4).\n *\n * SECRET-HANDLING: this module carries no secrets — only method names and\n * millisecond timestamps/durations.\n */\n\n/**\n * Page-global registry of per-method last-invocation timestamps\n * (`performance.now()`-relative, monotonic). One registry per page — shared\n * across every wrapped SDK object so repeated `wrapWithMethodPacing` calls\n * (e.g. the sdk-redirect virtual module re-evaluated per test file bundle)\n * still see the true last-invoke time of a given method name, not a fresh\n * per-bundle registry that would silently reset pacing at every file\n * boundary.\n */\ntype MethodPaceState = Map<string, number>;\n\nconst REGISTRY_KEY = '__AIT_METHOD_PACE_STATE__';\n\n/** Reads (or lazily creates) the page-global per-method pacing registry. */\nfunction getRegistry(): MethodPaceState {\n  const g = globalThis as { [REGISTRY_KEY]?: MethodPaceState };\n  let state = g[REGISTRY_KEY];\n  if (!(state instanceof Map)) {\n    state = new Map<string, number>();\n    g[REGISTRY_KEY] = state;\n  }\n  return state;\n}\n\n/** `setTimeout`-based sleep — no Node APIs, safe on the page side. */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * True when `value` is a `class` declaration rather than a plain callable\n * function. The SDK export surface includes at least one class (`PermissionError`,\n * `src/__typecheck.ts`/`bridge-stub.ts` both reference it) — wrapping a class\n * in an async arrow function would silently break `new PermissionError()`\n * (arrow functions are not constructible), so classes must pass through\n * `wrapWithMethodPacing` unwrapped exactly like any other non-callable\n * export. Detected via `Function.prototype.toString` starting with\n * `\"class \"` — the standard, spec-guaranteed way to distinguish a class from\n * an ordinary function at runtime (no Babel/TS transform in this bundle\n * target — `target: 'es2022'` in `bundle.ts` — down-compiles `class` to a\n * function, so this check remains reliable for esbuild's es2022 output).\n */\nfunction isClass(value: (...args: unknown[]) => unknown): boolean {\n  return Function.prototype.toString.call(value).startsWith('class ');\n}\n\n/**\n * Reads the page-global `__AIT_PACE_METHOD_MS__` gap value (devtools#769),\n * injected by `relay-factory.ts` the same way `__AIT_PACE_MS__`/`__AIT_CELL__`\n * are (`cell.ts#injectGlobals`). Absent/non-positive resolves to `0` — the\n * same \"treat absence as zero\" contract `runtime.ts`'s `__AIT_PACE_MS__` read\n * uses.\n */\nexport function getPaceMethodMs(): number {\n  const raw = (globalThis as { __AIT_PACE_METHOD_MS__?: unknown }).__AIT_PACE_METHOD_MS__;\n  return typeof raw === 'number' && raw > 0 ? raw : 0;\n}\n\n/**\n * Wraps a single named SDK function so that calls to it wait out `gapMs`\n * since the function's own previous invocation (tracked in the shared\n * `getRegistry()` map, keyed by `name`) before the real `fn` runs. The\n * result/rejection of `fn` passes through completely unchanged — pacing\n * never alters contract-observed behavior, only its timing.\n */\nfunction buildPacedFunction(\n  name: string,\n  fn: (...args: unknown[]) => unknown,\n  gapMs: number,\n): (...args: unknown[]) => unknown {\n  return async (...args: unknown[]) => {\n    const registry = getRegistry();\n    const now = performance.now();\n    const lastInvokeAt = registry.get(name);\n    if (lastInvokeAt !== undefined) {\n      const elapsed = now - lastInvokeAt;\n      if (elapsed < gapMs) {\n        await sleep(gapMs - elapsed);\n      }\n    }\n    // Record the timestamp AFTER any wait but BEFORE the real call — this is\n    // \"last invoke attempt\", matching the preflight's own \"sequential with\n    // spacing before each call\" model rather than \"last completion\", so two\n    // long-running calls in flight cannot both slip under the gap.\n    registry.set(name, performance.now());\n    return fn(...args);\n  };\n}\n\n/**\n * Wraps an SDK-shaped bridge object (`window.__sdk`, or the already\n * stub-wrapped result of `bridge-stub.ts#wrapSdkWithStub`) so that every\n * function-valued export is paced to a minimum `gapMs` interval between\n * calls to the SAME name (devtools#769). Non-function exports (constants,\n * etc.) and classes (`PermissionError`, etc. — wrapping a class would break\n * `new`, see `isClass`) pass through completely untouched.\n *\n * **Composition with bridge-stub (devtools#740)**: this wrapper is applied to\n * the RAW `window.__sdk` object, and `wrapSdkWithStub` is applied on TOP of\n * the paced result (`wrapSdkWithStub(wrapWithMethodPacing(rawSdk, gapMs),\n * stubEnabled)` — see `bundle.ts`'s sdk-redirect virtual module). This means\n * pacing sits BEHIND the stub interception: a stubbed name\n * (`STUB_REGISTRY` — `openPermissionDialog`, `requestPermission`,\n * `saveBase64Data`, `showFullScreenAd`) resolves instantly from the fixture\n * with no added delay, because `wrapSdkWithStub`'s Proxy intercepts the\n * property access before the paced function is ever reached. Only calls that\n * fall through to the REAL bridge — the ones that actually risk\n * `APP_BRIDGE_THROTTLED` — pay the pacing cost. Fixed by this ordering, not\n * incidental: swapping it (pacing outside the stub) would pace fixture\n * look-ups that can never hit the native rate limiter, for no benefit.\n *\n * `gapMs <= 0` (the default, no `--pace-method` / non-2.x cell) returns `sdk`\n * itself, untouched — the exact object identity is preserved so the\n * zero-diff-when-off contract holds under strict-equality checks, matching\n * `wrapSdkWithStub`'s own `enabled === false` fast path.\n *\n * **Memoization**: wrapper functions are cached per name in a `Map` local to\n * this call's `Proxy` (`wrapperCache` below), so repeated property access on\n * the SAME `sdk` object within a single `wrapWithMethodPacing` call returns\n * the SAME wrapper reference. This cache does NOT persist across separate\n * `wrapWithMethodPacing` calls — each call (e.g. the sdk-redirect virtual\n * module re-evaluated per test file bundle) gets its own fresh `Map` and\n * therefore its own wrapper function instances, even for the same method\n * name. That's fine for pacing correctness: the actual timing state lives in\n * the page-global `getRegistry()` map (keyed by method name, not by wrapper\n * identity), so cross-bundle pacing still works. But callers should NOT\n * assume cross-call function identity — only \"same wrapper within one call\"\n * is guaranteed.\n */\nexport function wrapWithMethodPacing(\n  sdk: Record<string, unknown>,\n  gapMs: number,\n): Record<string, unknown> {\n  if (!(gapMs > 0)) return sdk;\n\n  const wrapperCache = new Map<string, (...args: unknown[]) => unknown>();\n\n  return new Proxy(sdk, {\n    get(target, prop, receiver) {\n      const value = Reflect.get(target, prop, receiver);\n      if (\n        typeof prop !== 'string' ||\n        typeof value !== 'function' ||\n        isClass(value as (...args: unknown[]) => unknown)\n      ) {\n        // Non-function export (constants, symbols) OR a class (e.g.\n        // PermissionError) — pass through unchanged. Wrapping a class would\n        // break `new`, and per-name pacing only makes sense for callable SDK\n        // methods anyway.\n        return value;\n      }\n      const cached = wrapperCache.get(prop);\n      if (cached !== undefined) return cached;\n      const wrapped = buildPacedFunction(prop, value as (...args: unknown[]) => unknown, gapMs);\n      wrapperCache.set(prop, wrapped);\n      return wrapped;\n    },\n  });\n}\n"],"mappings":";AAyCA,MAAM,eAAe;;AAGrB,SAAS,cAA+B;CACtC,MAAM,IAAI;CACV,IAAI,QAAQ,EAAE;AACd,KAAI,EAAE,iBAAiB,MAAM;AAC3B,0BAAQ,IAAI,KAAqB;AACjC,IAAE,gBAAgB;;AAEpB,QAAO;;;AAIT,SAAS,MAAM,IAA2B;AACxC,QAAO,IAAI,SAAS,YAAY,WAAW,SAAS,GAAG,CAAC;;;;;;;;;;;;;;;AAgB1D,SAAS,QAAQ,OAAiD;AAChE,QAAO,SAAS,UAAU,SAAS,KAAK,MAAM,CAAC,WAAW,SAAS;;;;;;;;;AAUrE,SAAgB,kBAA0B;CACxC,MAAM,MAAO,WAAoD;AACjE,QAAO,OAAO,QAAQ,YAAY,MAAM,IAAI,MAAM;;;;;;;;;AAUpD,SAAS,mBACP,MACA,IACA,OACiC;AACjC,QAAO,OAAO,GAAG,SAAoB;EACnC,MAAM,WAAW,aAAa;EAC9B,MAAM,MAAM,YAAY,KAAK;EAC7B,MAAM,eAAe,SAAS,IAAI,KAAK;AACvC,MAAI,iBAAiB,KAAA,GAAW;GAC9B,MAAM,UAAU,MAAM;AACtB,OAAI,UAAU,MACZ,OAAM,MAAM,QAAQ,QAAQ;;AAOhC,WAAS,IAAI,MAAM,YAAY,KAAK,CAAC;AACrC,SAAO,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CtB,SAAgB,qBACd,KACA,OACyB;AACzB,KAAI,EAAE,QAAQ,GAAI,QAAO;CAEzB,MAAM,+BAAe,IAAI,KAA8C;AAEvE,QAAO,IAAI,MAAM,KAAK,EACpB,IAAI,QAAQ,MAAM,UAAU;EAC1B,MAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,SAAS;AACjD,MACE,OAAO,SAAS,YAChB,OAAO,UAAU,cACjB,QAAQ,MAAyC,CAMjD,QAAO;EAET,MAAM,SAAS,aAAa,IAAI,KAAK;AACrC,MAAI,WAAW,KAAA,EAAW,QAAO;EACjC,MAAM,UAAU,mBAAmB,MAAM,OAA0C,MAAM;AACzF,eAAa,IAAI,MAAM,QAAQ;AAC/B,SAAO;IAEV,CAAC"}

package/dist/test-runner/pool.d.ts

@@ -1,2 +1,2 @@
-import { i as createRelayPool, n as RelayConnectionFactory, r as RelayPoolOptions, t as RELAY_POOL_NAME } from "../pool-C6TgrcyW.js";
+import { i as createRelayPool, n as RelayConnectionFactory, r as RelayPoolOptions, t as RELAY_POOL_NAME } from "../pool-CrP5CPvU.js";
 export { RELAY_POOL_NAME, RelayConnectionFactory, RelayPoolOptions, createRelayPool };

package/dist/test-runner/pool.js

@@ -1,4 +1,4 @@
-import { i as runTestFilesOverRelay } from "../relay-worker-UK0nBfDX.js";
+import { i as runTestFilesOverRelay } from "../relay-worker-BUXI0K0b.js";
 import { synthesizeFileTask, toTaskEventPacks, toTaskResultPacks } from "./task-graph.js";
 //#region src/test-runner/pool.ts
 /** The pool name Vitest matches against `getFilePoolName(project)`. */

package/dist/test-runner/relay-factory.d.ts

@@ -11105,8 +11105,36 @@ interface RelayConnectionFactoryOptions {
    * intoss-private:// scheme URL from `ait deploy --scheme-only` (env3). The
    * phone cold-loads the candidate bundle this URL points at. SECRET-HANDLING:
    * never logged.
+   *
+   * Ignored when {@link attachLauncher} is `true` — the env-2 launcher path
+   * builds its attach URL from {@link appUrl} + the relay wss, not a scheme URL.
+   * Pass `''` in that case.
    */
   schemeUrl: string;
+  /**
+   * env-2 (AITC Sandbox PWA) attach mode (devtools#774). When `true`, `open()`
+   * builds the attach URL as a **launcher deep-link**
+   * (`buildLauncherAttachUrl(appUrl, wssUrl, totp)` — the same env-2 path the
+   * MCP daemon takes via `prepareAttach(deps, 'relay-mobile', …)`, issue #378)
+   * instead of an intoss-private scheme deep-link. The relay boot, QR
+   * rendering, dashboard, and attach-wait are byte-for-byte identical to env 3;
+   * only the URL family differs. Omitted/false keeps the env-3 scheme path
+   * unchanged (zero behavior change).
+   */
+  attachLauncher?: boolean;
+  /**
+   * The consumer dev server's HTTP tunnel URL (e.g. an sdk-example
+   * `dev:phone:cdp` `*.trycloudflare.com` URL) that the launcher PWA frames.
+   * REQUIRED when {@link attachLauncher} is `true`; ignored otherwise.
+   *
+   * Threaded to the `relay-mobile` `prepareAttach` branch via the
+   * `AIT_TUNNEL_BASE_URL` env var (the same key the MCP daemon reads), so the
+   * exact same env-2 assembly runs — no divergent code path.
+   *
+   * SECRET-HANDLING: this is a tunnel host at the same sensitivity as the relay
+   * wss — NEVER logged. It rides only inside the QR/dashboard attach capsule.
+   */
+  appUrl?: string;
   /**
    * Project root for the `.ait_relay` secret lookup (read-only). Defaults to
    * `process.cwd()`.
@@ -11133,6 +11161,40 @@ interface RelayConnectionFactoryOptions {
     sdkLine: string;
     platform: string;
   };
+  /**
+   * When `true`, injects `__AIT_STUB_BLOCKING__ = true` before the first test
+   * bundle runs (devtools#740, DT-2) — `bundle.ts`'s sdk-redirect module reads
+   * this flag via `isStubBlockingEnabled()` and answers the blocking-UI APIs
+   * in `bridge-stub.ts`'s `STUB_REGISTRY` from fixtures instead of forwarding
+   * them to native. Optional — omitted/false means no flag is injected, which
+   * is byte-for-byte the pre-#740 behavior (the sdk-redirect module treats
+   * absence the same as `false`). Not a secret.
+   */
+  stubBlocking?: boolean;
+  /**
+   * Injects `__AIT_PACE_MS__ = paceMs` before the first test bundle runs
+   * (devtools#767) — `runtime.ts`'s test-execution loop reads this page
+   * global and waits `paceMs` before every test after the first one that
+   * actually runs. Optional — omitted/0 means no flag is injected, which is
+   * byte-for-byte the pre-#767 behavior (the loop treats an absent/non-
+   * positive value as "no pacing"). Not a secret. This is the PAGE-side half
+   * of `--pace`; the RUNNER-side (file-to-file) half is a plain `opts.paceMs`
+   * forwarded to `runTestFilesOverRelay` by the caller (cli.ts) — this
+   * factory only owns the page-global injection.
+   */
+  paceMs?: number;
+  /**
+   * Injects `__AIT_PACE_METHOD_MS__ = paceMethodMs` before the first test
+   * bundle runs (devtools#769) — `bundle.ts`'s sdk-redirect virtual module
+   * reads this page global via `method-pace.ts#getPaceMethodMs()` and paces
+   * every SDK call to a minimum interval BETWEEN calls to the SAME named
+   * function, independent of `--pace`'s test-to-test/file-to-file spacing.
+   * Optional — omitted/0 means no flag is injected, which is byte-for-byte
+   * the pre-#769 behavior (`getPaceMethodMs()` treats an absent/non-positive
+   * value as "no pacing", and `wrapWithMethodPacing` returns the SDK object
+   * untouched in that case). Not a secret.
+   */
+  paceMethodMs?: number;
   /**
    * Overrides the dashboard HTTP server's bind base port (devtools#752).
    * Threaded straight through to `startQrHttpServer`'s `dashboardPort`
@@ -11160,12 +11222,13 @@ interface RelayConnectionFactoryOptions {
   onQrContent: (textChunks: string[]) => void;
 }
 /**
- * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay
- * connection.
+ * Builds a {@link RelayConnectionFactory} that opens a standalone relay
+ * connection for env 3 (intoss-private scheme, default) or env 2 (AITC Sandbox
+ * PWA launcher deep-link, when `opts.attachLauncher` is set — devtools#774).
  *
  * `open()` performs the full attach lifecycle and BLOCKS while a human scans
- * the rendered QR with their phone — there is no way around the manual scan
- * for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
+ * the rendered QR with their phone — there is no way around the manual scan.
+ * By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
  * runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is
  * a human-paced action with no sound default bound (devtools#735). Passing an
  * explicit `timeoutMs` opts into the old bounded behavior (CI/headless