@ait-co/devtools 0.1.136 → 0.1.138

package/dist/test-runner/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { m as logInfo } from "../attach-orchestrator-CE0S09YU.js";
+import { m as logInfo } from "../attach-orchestrator-BEiz3wAx.js";
 import { r as generateTotp } from "../totp-CZLLKfOC.js";
-import { n as runPermissionPreflight } from "../cell-BIdSQb9T.js";
+import { r as runPermissionPreflight, t as PERMISSION_PREFLIGHT_TIMEOUT_MS } from "../cell-KsRXFdDs.js";
 import * as path$1 from "node:path";
 import path, { basename, isAbsolute, resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -93,12 +93,13 @@ function partitionManualTests(files) {
 //#endregion
 //#region src/test-runner/relay-factory.ts
 /**
-* 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
@@ -115,14 +116,17 @@ function createRelayConnectionFactory(opts) {
 	const headless = opts.headless === true;
 	let family;
 	let qrServer;
+	let attachWatcher;
 	let phase = "active";
 	let manualPrompt = null;
 	return {
 		async open() {
-			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-CE0S09YU.js").then((n) => n.i);
-			const { injectDebugIndicator, injectGlobals } = await import("../cell-BIdSQb9T.js").then((n) => n.t);
-			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-CLEGyHou.js");
-			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-D2wpPK3_.js");
+			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-BEiz3wAx.js").then((n) => n.i);
+			const { injectDebugIndicator, injectGlobals } = await import("../cell-KsRXFdDs.js").then((n) => n.n);
+			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-Bmyleu0A.js");
+			const { bootRelayFamily, buildRelayVerifyAuth, startAttachWatcher } = await import("../debug-server-DWat7d-9.js");
+			const { buildChiiInspectorUrl } = await import("../devtools-opener-CJpEsXXQ.js");
+			const { generateTotp } = await import("../totp-CZLLKfOC.js").then((n) => n.i);
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -152,29 +156,73 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-C7q8Gn04.js");
+				const { startQrHttpServer } = await import("../qr-http-server-DIjCV7h_.js");
 				const getDashboardState = () => ({
 					tunnel: attachDeps.getTunnelStatus(),
-					pages: null,
+					pages: booted.connection.listTargets().map((t) => ({
+						id: t.id,
+						url: t.url
+					})),
 					attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,
-					mode: "relay-dev",
+					mode: opts.attachLauncher === true ? "relay-mobile" : "relay-dev",
 					phase,
 					manualPrompt
 				});
-				qrServer = await startQrHttpServer(getDashboardState, { dashboardPort: opts.dashboardPort });
+				const getDirectInspectorUrl = () => {
+					if (!booted.relayHttpUrl) return {
+						ok: false,
+						reason: "relayDown"
+					};
+					const targets = booted.connection.listTargets();
+					if (targets.length === 0) return {
+						ok: false,
+						reason: "noTarget"
+					};
+					const totpSecret = process.env.AIT_DEBUG_TOTP_SECRET;
+					if (!totpSecret) return {
+						ok: false,
+						reason: "totpUnavailable"
+					};
+					const url = buildChiiInspectorUrl(booted.relayHttpUrl, targets[0].id, () => generateTotp(totpSecret, Date.now()));
+					if (url === null) return {
+						ok: false,
+						reason: "totpUnavailable"
+					};
+					return {
+						ok: true,
+						url
+					};
+				};
+				qrServer = await startQrHttpServer(getDashboardState, {
+					dashboardPort: opts.dashboardPort,
+					getDirectInspectorUrl
+				});
 				attachDeps.qrHttpServer = qrServer;
 				attachDeps.onAttachUrlBuilt = (parts) => {
 					lastAttachParts = parts;
 					qrServer?.notifyStateChange();
 				};
+				attachWatcher = startAttachWatcher(booted.connection, void 0, 1e3, () => qrServer?.notifyStateChange(), () => qrServer?.notifyStateChange());
 				process.stderr.write(`devtools-test: QR dashboard: http://127.0.0.1:${qrServer.port}/\n`);
 			} catch {}
 			const TUNNEL_BOOT_TIMEOUT_MS = 15e3;
 			await Promise.race([tunnelReady, new Promise((resolve) => setTimeout(resolve, TUNNEL_BOOT_TIMEOUT_MS))]);
-			const prep = await prepareAttach(attachDeps, "relay-dev", { scheme_url: opts.schemeUrl }, booted.connection);
+			let prep;
+			if (opts.attachLauncher === true) {
+				const priorTunnelBaseUrl = process.env.AIT_TUNNEL_BASE_URL;
+				process.env.AIT_TUNNEL_BASE_URL = opts.appUrl ?? "";
+				try {
+					prep = await prepareAttach(attachDeps, "relay-mobile", {}, booted.connection);
+				} finally {
+					if (priorTunnelBaseUrl === void 0) delete process.env.AIT_TUNNEL_BASE_URL;
+					else process.env.AIT_TUNNEL_BASE_URL = priorTunnelBaseUrl;
+				}
+			} else prep = await prepareAttach(attachDeps, "relay-dev", { scheme_url: opts.schemeUrl }, booted.connection);
 			if (!prep.ok) {
 				booted.stop();
 				family = void 0;
+				attachWatcher?.stop();
+				attachWatcher = void 0;
 				await qrServer?.close();
 				qrServer = void 0;
 				throw new Error("createRelayConnectionFactory: attach preparation failed — check the scheme_url and that the relay tunnel is up");
@@ -183,6 +231,8 @@ function createRelayConnectionFactory(opts) {
 			if (waitResult.isError) {
 				booted.stop();
 				family = void 0;
+				attachWatcher?.stop();
+				attachWatcher = void 0;
 				await qrServer?.close();
 				qrServer = void 0;
 				const timeoutSec = Math.round(timeoutMs / 1e3);
@@ -204,12 +254,17 @@ function createRelayConnectionFactory(opts) {
 			if (lastEnableError !== void 0) {
 				booted.stop();
 				family = void 0;
+				attachWatcher?.stop();
+				attachWatcher = void 0;
 				await qrServer?.close();
 				qrServer = void 0;
 				throw new Error(`createRelayConnectionFactory: page did not become ready after ${PAGE_READY_RETRIES} attempts (${Math.round(PAGE_READY_RETRIES * PAGE_READY_RETRY_DELAY_MS / 1e3)}s) — the mini-app page may have disconnected before enableDomains() could open the CDP websocket`);
 			}
 			await injectDebugIndicator(booted.connection);
 			if (opts.cell !== void 0) await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });
+			if (opts.stubBlocking === true) await injectGlobals(booted.connection, { __AIT_STUB_BLOCKING__: true });
+			if (opts.paceMs !== void 0 && opts.paceMs > 0) await injectGlobals(booted.connection, { __AIT_PACE_MS__: opts.paceMs });
+			if (opts.paceMethodMs !== void 0 && opts.paceMethodMs > 0) await injectGlobals(booted.connection, { __AIT_PACE_METHOD_MS__: opts.paceMethodMs });
 			return booted.connection;
 		},
 		onSessionPhase(next) {
@@ -226,11 +281,13 @@ function createRelayConnectionFactory(opts) {
 				qrServer?.notifyStateChange();
 			}
 			try {
-				const { injectDebugIndicator } = await import("../cell-BIdSQb9T.js").then((n) => n.t);
+				const { injectDebugIndicator } = await import("../cell-KsRXFdDs.js").then((n) => n.n);
 				await injectDebugIndicator(connection, { state: "disconnected" });
 			} catch {}
 			family?.stop();
 			family = void 0;
+			attachWatcher?.stop();
+			attachWatcher = void 0;
 			await qrServer?.close();
 			qrServer = void 0;
 		}
@@ -906,7 +963,73 @@ const SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\]\\]
 *
 * If `window.__sdk` is absent (non-dog-food build), every access throws a
 * descriptive error rather than returning `undefined` silently.
+*
+* Bridge-stub interception (devtools#740, DT-2): the virtual module runs the
+* resolved `window.__sdk` object through `wrapSdkWithStub` before exporting
+* it. `wrapSdkWithStub` is a pass-through (returns the same object,
+* unwrapped) unless `isStubBlockingEnabled()` reads `true` off
+* `globalThis.__AIT_STUB_BLOCKING__` — an opt-in flag injected the same way
+* `__AIT_CELL__` is (`cell.ts#injectGlobals`, wired from the CLI's
+* `--stub-blocking` flag). Default off => zero behavior change: every existing
+* (non-stub) test run resolves the exact same `window.__sdk` reference it did
+* before this plugin learned about stubbing.
+*
+* Per-method pacing (devtools#769): BEFORE the stub wrap, `window.__sdk` is
+* run through `wrapWithMethodPacing`, which enforces a minimum interval
+* between calls to the SAME named SDK function (`getPaceMethodMs()` reads the
+* `__AIT_PACE_METHOD_MS__` page global — see `method-pace.ts`). Composition
+* order is pacing INSIDE the stub (`wrapSdkWithStub(wrapWithMethodPacing(sdk,
+* gap), enabled)`): a stubbed name resolves instantly from
+* `bridge-stub.ts`'s fixtures without ever reaching the paced wrapper, and
+* only calls that fall through to the real bridge — the ones that can
+* actually trigger `APP_BRIDGE_THROTTLED` — pay the pacing cost. `gapMs <= 0`
+* (default, no `--pace-method` / non-2.x cell) is a no-op fast path — see
+* `method-pace.ts#wrapWithMethodPacing`'s doc for the full contract.
 */
+/**
+* Builds the virtual CommonJS-style module contents the `sdk-redirect`
+* esbuild plugin loads for every `@apps-in-toss/web-framework` import.
+*
+* Pulled out to a pure, exported function (rather than inlined at the
+* `build.onLoad` call site) so unit tests can assert the exact composition
+* order (pacing wraps the raw SDK; the stub wraps the paced result) as a
+* string-level contract, independent of esbuild — esbuild cannot run inside
+* this repo's jsdom vitest environment (see `bundleTestFile`'s module doc's
+* lazy-import note), so a real bundling round-trip is out of unit-test reach
+* here; `wrapSdkWithStub`/`wrapWithMethodPacing`'s own composed-call behavior
+* is covered directly (see `bundle.test.ts`).
+*
+* Generates a virtual CommonJS-style module so that esbuild does NOT perform
+* strict named-export matching. When `format:'iife'` bundles a CJS module, it
+* wraps it with its own `__toCommonJS` helper and satisfies named imports via
+* property access on the `module.exports` object — which is our Proxy. This
+* means `import { getPlatformOS } from '...'` becomes
+* `__proxy.getPlatformOS` at runtime, which correctly reads from
+* `window.__sdk`.
+*
+* The bridge-stub and method-pace imports are STATIC imports of the real
+* `bridge-stub.ts`/`method-pace.ts` modules (not inlined JS) so esbuild
+* bundles each once and the fixture registry / pacing registry have a single
+* source of truth shared with their own unit tests.
+*
+* Exported for unit testing.
+*/
+function buildSdkRedirectModuleContents() {
+	return `
+import { wrapSdkWithStub, isStubBlockingEnabled } from ${JSON.stringify(getBridgeStubPath())};
+import { wrapWithMethodPacing, getPaceMethodMs } from ${JSON.stringify(getMethodPacePath())};
+var __rawSdk = (typeof window !== 'undefined' && window.__sdk)
+  ? window.__sdk
+  : new Proxy({}, {
+      get: function(_t, p) {
+        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
+      }
+    });
+var __pacedSdk = wrapWithMethodPacing(__rawSdk, getPaceMethodMs());
+var __proxy = wrapSdkWithStub(__pacedSdk, isStubBlockingEnabled());
+module.exports = __proxy;
+`;
+}
 function sdkRedirectPlugin() {
 	return {
 		name: "sdk-redirect",
@@ -919,17 +1042,9 @@ function sdkRedirectPlugin() {
 				filter: /.*/,
 				namespace: "sdk-redirect"
 			}, () => ({
-				contents: `
-var __proxy = (typeof window !== 'undefined' && window.__sdk)
-  ? window.__sdk
-  : new Proxy({}, {
-      get: function(_t, p) {
-        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
-      }
-    });
-module.exports = __proxy;
-`,
-				loader: "js"
+				contents: buildSdkRedirectModuleContents(),
+				loader: "js",
+				resolveDir: process.cwd()
 			}));
 		}
 	};
@@ -1063,8 +1178,9 @@ function userFactoryPlugin(absPath) {
 	};
 }
 /**
-* Returns the absolute filesystem path to the test-runner runtime module
-* (dist/test-runner/runtime.js — a fully self-contained page-side bundle).
+* Returns the absolute filesystem path to a page-side leaf module shipped
+* alongside `bundle.ts` in dist (e.g. `runtime.js`, `bridge-stub.js`) — a
+* fully self-contained module with no further page-side deps of its own.
 *
 * Rolldown code-splitting duplicates this bundling logic into shared chunks
 * emitted at ARBITRARY dist depths: the `devtools-test` CLI pulls it from
@@ -1074,26 +1190,30 @@ function userFactoryPlugin(absPath) {
 * is therefore wrong from at least one chunk — the live #697 regression.
 *
 * This resolves WITHOUT assuming chunk depth: from `import.meta.url`'s dir it
-* probes the co-located `runtime.js` and the nested `test-runner/runtime.js`,
+* probes the co-located `<name>.js` and the nested `test-runner/<name>.js`,
 * then ascends one directory at a time (bounded) repeating both probes. The
-* nested probe catches dist/test-runner/runtime.js from the dist/ root level no
+* nested probe catches dist/test-runner/<name>.js from the dist/ root level no
 * matter which depth the chunk was hoisted to (root, dist/mcp/, or a future
-* relocation). The build always emits dist/test-runner/runtime.js (tsdown entry
-* `'test-runner/runtime'`; guarded by scripts/check-test-runner-dist.sh).
+* relocation). The build always emits dist/test-runner/<name>.js (tsdown entry
+* `'test-runner/<name>'`; guarded by scripts/check-test-runner-dist.sh for
+* `runtime`).
 *
 * An ABSOLUTE path is returned deliberately: esbuild loads it as a literal file
 * read, bypassing Node module resolution entirely, so this works identically in
 * the npx-daemon context (its own dist tree) and the consumer-CLI context
 * (the mini-app's installed @ait-co/devtools dist) — neither needs the package
 * to be node-resolvable from the caller.
+*
+* @param moduleName - The leaf module's basename without extension, e.g.
+*   `'runtime'` or `'bridge-stub'`.
 */
-function getRuntimePath() {
+function getPageSideModulePath(moduleName) {
 	const startDir = path$1.dirname(fileURLToPath(import.meta.url));
 	const RELATIVE_PROBES = [
-		["runtime.js"],
-		["test-runner", "runtime.js"],
-		["runtime.ts"],
-		["test-runner", "runtime.ts"]
+		[`${moduleName}.js`],
+		["test-runner", `${moduleName}.js`],
+		[`${moduleName}.ts`],
+		["test-runner", `${moduleName}.ts`]
 	];
 	let dir = startDir;
 	for (let i = 0; i < 12; i++) {
@@ -1108,7 +1228,27 @@ function getRuntimePath() {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return path$1.join(startDir, "runtime.js");
+	return path$1.join(startDir, `${moduleName}.js`);
+}
+/** Absolute path to the test-runner page-side runtime (describe/it/test/expect). */
+function getRuntimePath() {
+	return getPageSideModulePath("runtime");
+}
+/**
+* Absolute path to the bridge-stub interceptor (devtools#740, DT-2) —
+* `wrapSdkWithStub`/`isStubBlockingEnabled`, statically imported by the
+* `sdk-redirect` virtual module.
+*/
+function getBridgeStubPath() {
+	return getPageSideModulePath("bridge-stub");
+}
+/**
+* Absolute path to the per-method pacing wrapper (devtools#769) —
+* `wrapWithMethodPacing`/`getPaceMethodMs`, statically imported by the
+* `sdk-redirect` virtual module.
+*/
+function getMethodPacePath() {
+	return getPageSideModulePath("method-pace");
 }
 /**
 * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
@@ -1382,15 +1522,21 @@ async function runTestFilesOverRelay(connection, files, opts) {
 	const manualFiles = opts?.manualFiles;
 	const manualTotal = manualFiles?.size ?? 0;
 	let manualIndex = 0;
+	const stubBlockingFiles = opts?.stubBlockingFiles;
 	let preflightPermissions;
-	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection);
+	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection, PERMISSION_PREFLIGHT_TIMEOUT_MS, opts?.preflightSdkLine !== "3.x");
+	const paceMs = opts?.paceMs;
+	let ranFirstFile = false;
 	try {
 		for (const file of files) {
 			if (pendingReconnectCheck) {
 				await attemptReconnect("next-file");
 				pendingReconnectCheck = false;
 			}
-			const isManual = manualFiles?.has(file) === true;
+			if (paceMs !== void 0 && paceMs > 0 && ranFirstFile) await new Promise((resolve) => setTimeout(resolve, paceMs));
+			ranFirstFile = true;
+			const isStubbed = stubBlockingFiles?.has(file) === true;
+			const isManual = !isStubbed && manualFiles?.has(file) === true;
 			if (isManual) {
 				manualIndex += 1;
 				opts?.onManualFile?.(file, manualIndex, manualTotal);
@@ -1457,7 +1603,8 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				};
 			}
 			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
-			if (isManual) fileEntry.mode = "manual";
+			if (isStubbed) fileEntry.mode = "stubbed";
+			else if (isManual) fileEntry.mode = "manual";
 			fileResults.push(fileEntry);
 		}
 	} finally {
@@ -1573,7 +1720,7 @@ function serializeRelayReport(report, meta) {
 		...report.preflight ? { preflight: report.preflight } : {},
 		files: report.files.map((f) => {
 			const file = relativise(meta.projectRoot, f.file);
-			const modeField = f.mode === "manual" ? { mode: "manual" } : {};
+			const modeField = f.mode === "manual" || f.mode === "stubbed" ? { mode: f.mode } : {};
 			if ("error" in f.result) return {
 				file,
 				error: f.result.error,
@@ -1605,11 +1752,21 @@ function serializeRelayReport(report, meta) {
 * `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard
 * one — the standard `<sdkLine>.<platform>.json` filename is reserved for the
 * regular (unattended) files only, so a manual run's presence never mutates
-* what the unattended-baseline filename means. If ALL files in the run are
-* regular, only the standard artifact is written (today's behavior,
-* unchanged). If a run mixes both (regular files + `--manual-blocking`
-* scheduled last), BOTH artifacts are written — the manual one ALONGSIDE, not
-* replacing, the standard one.
+* what the unattended-baseline filename means.
+*
+* Stub-blocking provenance (devtools#740, DT-2): `mode: 'stubbed'` files are
+* written to a THIRD, separate `<dir>/<sdkLine>.<platform>.stubbed.json`
+* artifact — never merged into the standard file (it is unattended, like the
+* standard file, so a naive filename split could conflate the two) and never
+* merged into `.manual.json` (it did NOT have a human present). Its body is
+* ALSO stamped `cell.bridgeStub: true` — the mandatory HYBRID-cell provenance
+* from the issue: a stubbed result must never be silently mixed into the
+* real-device baseline report.
+*
+* If ALL files in the run are regular, only the standard artifact is written
+* (today's behavior, unchanged). Any combination of the three modes present
+* in a single run writes ONLY the corresponding artifacts — each is additive,
+* never replacing another.
 *
 * SECRET-HANDLING: the written body contains no relay/secret fields (the schema
 * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
@@ -1618,14 +1775,16 @@ function serializeRelayReport(report, meta) {
 * @param dir    - Output directory (created recursively if missing).
 * @param meta   - Cell axes + projectRoot.
 * @returns The absolute path(s) written, in order: standard first (if any
-*   regular files ran), then manual (if any manual files ran). At least one
-*   path is always returned when `report.files` is non-empty.
+*   regular files ran), then manual (if any manual files ran), then stubbed
+*   (if any stubbed files ran). At least one path is always returned when
+*   `report.files` is non-empty.
 */
 async function writeReportArtifact(report, dir, meta) {
 	const serialised = serializeRelayReport(report, meta);
 	await mkdir(dir, { recursive: true });
-	const regularFiles = serialised.files.filter((f) => f.mode !== "manual");
+	const regularFiles = serialised.files.filter((f) => f.mode === void 0);
 	const manualFiles = serialised.files.filter((f) => f.mode === "manual");
+	const stubbedFiles = serialised.files.filter((f) => f.mode === "stubbed");
 	const written = [];
 	if (regularFiles.length > 0 || serialised.files.length === 0) {
 		const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
@@ -1643,6 +1802,18 @@ async function writeReportArtifact(report, dir, meta) {
 		}, null, 2)}\n`, "utf8");
 		written.push(manualOutFile);
 	}
+	if (stubbedFiles.length > 0) {
+		const stubbedOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.stubbed.json`);
+		await writeFile(stubbedOutFile, `${JSON.stringify({
+			...serialised,
+			cell: {
+				...serialised.cell,
+				bridgeStub: true
+			},
+			files: stubbedFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(stubbedOutFile);
+	}
 	return written;
 }
 /**
@@ -1777,7 +1948,21 @@ USAGE
 
 OPTIONS
   --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
-                          (required for standalone relay attach / env3)
+                          (required for standalone relay attach / env3). Unused
+                          and ignored when --attach-launcher is set.
+  --attach-launcher       Attach over the env-2 AITC Sandbox PWA launcher
+                          (real-device WebKit) instead of the env-3 intoss
+                          scheme deep-link. The relay/QR/dashboard/attach-wait
+                          are identical; only the QR is a launcher deep-link.
+                          Requires --app-url. The SDK still hits the mock in
+                          env 2, so this measures the mock + standard Web API
+                          layer's engine-attributable behavior (env1↔env2
+                          equivalence), NOT native-bridge fidelity (that is env3).
+  --app-url <url>         The consumer dev server's HTTP tunnel URL (e.g. the
+                          *.trycloudflare.com URL from \`pnpm dev:phone:cdp\`)
+                          that the launcher PWA frames. REQUIRED with
+                          --attach-launcher; ignored otherwise. SECRET: a tunnel
+                          host — never printed; it rides only inside the QR.
   --timeout <ms>          Per-file evaluate timeout in ms (default: 60000).
                           Controls how long a single test file is allowed to run
                           before it is considered hung. Does NOT affect how long
@@ -1789,7 +1974,10 @@ OPTIONS
                           Pass a value to bound the wait for CI/headless runs.
   --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
   --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
-                          (mock|ios|android, default: AIT_CELL_PLATFORM env)
+                          (mock|ios|android|ios-pwa, default: AIT_CELL_PLATFORM
+                          env). Use ios-pwa for env-2 (--attach-launcher) runs
+                          so env1(mock@desktop) and env2(mock@WebKit) captures
+                          stay distinguishable. An unknown value is rejected.
   --report-dir <dir>      Persist a runner-agnostic report + captures to <dir>
                           (report: <sdkLine>.<platform>.json; captures:
                           <dir>/.ait-capture/<category>.<sdkLine>.<platform>.json).
@@ -1804,6 +1992,28 @@ OPTIONS
   --headless              Disable browser auto-open (text QR only)
   --project-root <dir>    Project root for .ait_relay secret lookup
                           (default: current working directory)
+  --pace <ms>             Minimum delay in ms between test-to-test AND
+                          file-to-file bridge calls (default: 0, i.e. no
+                          added delay — today's behavior byte-for-byte).
+                          Falls back to the AIT_PACE env var when omitted
+                          (--pace takes precedence over the env var when both
+                          are given). Use on a 2.x cell scan when the native
+                          per-method bridge rate limit (APP_BRIDGE_THROTTLED,
+                          devtools#767) is rejecting rapid same-method calls —
+                          3.x cells are unaffected by that limiter and do not
+                          need this flag.
+  --pace-method <ms>      Minimum delay in ms BETWEEN calls to the SAME named
+                          SDK function — paces a same-method burst WITHIN a
+                          single test body (e.g. a clipboard happy-path loop
+                          calling setClipboardText/getClipboardText 8 times
+                          back to back), which --pace's test/file spacing
+                          cannot reach (devtools#769). Falls back to the
+                          AIT_PACE_METHOD env var when omitted (--pace-method
+                          takes precedence over the env var when both are
+                          given). Default: 250ms when --cell-sdk-line is 2.x
+                          (unset --cell-sdk-line also defaults to 2.x — see
+                          --cell-sdk-line), 0 (no added delay) otherwise. Pass
+                          --pace-method 0 to opt out even on a 2.x cell.
   --manual-blocking       Run manual-tagged test files (*.manual.ait.test.ts)
                           LAST, after all regular files, with a human present.
                           Before each manual file, the QR dashboard is pushed
@@ -1822,6 +2032,24 @@ OPTIONS
                           each manual file's report entry is stamped
                           mode: 'manual' — never diff a manual run against an
                           unattended baseline as if they were equivalent.
+  --stub-blocking         Run manual-tagged test files (*.manual.ait.test.ts)
+                          UNATTENDED (devtools#740, DT-2) by intercepting a
+                          fixed allowlist of blocking-UI SDK calls (ads
+                          show*, openPermissionDialog/requestPermission,
+                          saveBase64Data) in the page and answering them from
+                          fixtures captured by a real --manual-blocking run,
+                          instead of forwarding them to native UI. Implies
+                          --manual-blocking (manual files are included in the
+                          run); no human presence or QR-dashboard prompt is
+                          needed for them. HYBRID cell, not pure env3 — every
+                          other SDK call in the same run still hits the real
+                          native bridge. With --report-dir, files that ran
+                          under the stub are written to a SEPARATE
+                          <sdkLine>.<platform>.stubbed.json artifact (never
+                          merged into the standard or .manual.json report) and
+                          the report body is stamped cell.bridgeStub: true —
+                          never diff a stubbed run against a real device
+                          baseline (manual or unattended) as if equivalent.
   --help, -h              Show this help message
 
 DESCRIPTION
@@ -1838,7 +2066,7 @@ DESCRIPTION
   The test files run against the live relay connection started by this process;
   no separate MCP daemon is required.
 
-EXAMPLE
+EXAMPLE (env 3 — intoss-private scheme)
   devtools-test 'src/**/*.ait.test.ts' \\
     --scheme-url "intoss-private://..." \\
     --cell-sdk-line 3.x \\
@@ -1846,6 +2074,14 @@ EXAMPLE
     --report-dir .ait-report \\
     --timeout 60000
 
+EXAMPLE (env 2 — AITC Sandbox PWA launcher)
+  devtools-test 'src/**/*.ait.test.ts' \\
+    --attach-launcher \\
+    --app-url "https://<subdomain>.trycloudflare.com" \\
+    --cell-sdk-line 3.x \\
+    --cell-platform ios-pwa \\
+    --report-dir .ait-report
+
 `.trimStart();
 /**
 * Grace period (ms) for the exit backstop armed around Step 6 teardown
@@ -1894,6 +2130,144 @@ function resolveDashboardPort(raw) {
 	return port;
 }
 /**
+* Rewrites a lone `--pace <value>` or `--pace-method <value>` pair from space
+* syntax to `=` syntax (`--pace=<value>` / `--pace-method=<value>`) when
+* `<value>` starts with `-` (devtools#768 review; extended to `--pace-method`
+* in devtools#769).
+*
+* Node's `util.parseArgs` treats a `type: 'string'` option's value as
+* "ambiguous" and throws its OWN parser error whenever that value starts with
+* a dash and was passed via the space form (`--pace -1`) — it never reaches
+* this module's `resolvePace`/`resolvePaceMethod`, so the friendly
+* `'--pace must be a non-negative integer'` message (and its unit-tested path)
+* was unreachable from the real CLI entry point for the single most natural
+* way a user would try a negative value, even though every other flag in
+* {@link USAGE} is documented in space syntax.
+*
+* Scoped narrowly to `--pace`/`--pace=...` and `--pace-method`/
+* `--pace-method=...` tokens only — every other flag is untouched, and
+* positionals/other options keep flowing through `parseArgs` unchanged. Only
+* rewrites the space form; `--pace=-1`/`--pace-method=-1` already parse fine
+* and are passed through untouched.
+*
+* Exported for unit testing.
+*/
+function normalizePaceArgv(argv) {
+	const out = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if ((arg === "--pace" || arg === "--pace-method") && next !== void 0 && next.startsWith("-") && next !== "--") {
+			out.push(`${arg}=${next}`);
+			i++;
+			continue;
+		}
+		out.push(arg);
+	}
+	return out;
+}
+/**
+* Parses `--pace` (falling back to the `AIT_PACE` env var when the flag is
+* omitted) into a validated millisecond delay (devtools#767).
+*
+* Opt-in, zero-diff-when-absent: BOTH omitted resolves to `0` — no pacing —
+* which is byte-for-byte today's behavior (`runtime.ts` treats `0`/absent
+* `__AIT_PACE_MS__` identically, and `relay-worker.ts`'s file-to-file gap is
+* skipped entirely when the resolved value is 0). `--pace` takes precedence
+* over `AIT_PACE` when both are present, mirroring `--cell-platform` /
+* `AIT_CELL_PLATFORM`'s existing flag-over-env precedent.
+*
+* Returns an error string on invalid input (non-integer or negative), or the
+* resolved delay (`>= 0`) on success. Exported for unit testing.
+*/
+function resolvePace(rawFlag, rawEnv) {
+	const raw = rawFlag ?? rawEnv;
+	if (raw === void 0) return 0;
+	const ms = parseInt(raw, 10);
+	if (Number.isNaN(ms) || ms < 0) return "--pace must be a non-negative integer";
+	return ms;
+}
+/**
+* Parses `--pace-method` (falling back to the `AIT_PACE_METHOD` env var when
+* the flag is omitted) into a validated millisecond per-method minimum
+* interval (devtools#769).
+*
+* Precedence, highest first: `--pace-method` flag > `AIT_PACE_METHOD` env >
+* sdkLine-aware default (`{@link DEFAULT_PACE_METHOD_MS_2X}` for a 2.x cell,
+* `0` otherwise) — an EXPLICIT flag or env value always wins, including
+* `--pace-method 0` to opt out on a 2.x cell. Mirrors `resolvePace`'s
+* flag-over-env precedent, with the sdkLine default spliced in only when
+* BOTH are absent.
+*
+* Returns an error string on invalid input (non-integer or negative), or the
+* resolved delay (`>= 0`) on success. Exported for unit testing.
+*
+* @param rawFlag        - The raw `--pace-method` string value, if passed.
+* @param rawEnv         - The raw `AIT_PACE_METHOD` env value, if set.
+* @param resolvedCellSdkLine - The effective `cell.sdkLine` value (already
+*   defaulted to '2.x' by the caller when `--cell-sdk-line` was omitted — see
+*   `main()`'s `cell` construction) — used ONLY to pick the sdkLine-aware
+*   default when both `rawFlag` and `rawEnv` are absent.
+*/
+function resolvePaceMethod(rawFlag, rawEnv, resolvedCellSdkLine) {
+	const raw = rawFlag ?? rawEnv;
+	if (raw === void 0) return resolvedCellSdkLine === "2.x" ? 250 : 0;
+	const ms = parseInt(raw, 10);
+	if (Number.isNaN(ms) || ms < 0) return "--pace-method must be a non-negative integer";
+	return ms;
+}
+/**
+* The set of `__AIT_CELL__.platform` values the runner accepts (devtools#774).
+*
+* `mock`/`ios`/`android` mirror sdk-example `aitCapture`'s existing `Platform`
+* union; `ios-pwa` is the new env-2 axis value (issue #774) — env 1 is
+* mock@desktop-Chromium and env 2 is mock@real-device-WebKit, so the two share
+* `sdkLine`/`ios` but must be DISTINGUISHABLE in the capture cell to diff
+* engine-attributable differences. `ios-pwa` names "mock SDK, real-device iOS
+* WebKit via the launcher PWA" — it is NOT `ios` (which is env 3's native
+* bridge). The consuming `aitCapture` type extension is a separate sdk-example
+* PR (out of scope here); the runner only needs to inject + validate the label.
+*
+* Kept as a validated allowlist (rather than a free string) purely as a
+* typo guard: `platform` flows into report/capture FILENAMES
+* (`<sdkLine>.<platform>.json`), so a silent typo would fork the artifact set
+* and break offline diffing. This is the first validation on `--cell-platform`
+* — before #774 it was an unvalidated free string defaulting to `mock`.
+*/
+const ALLOWED_CELL_PLATFORMS = [
+	"mock",
+	"ios",
+	"android",
+	"ios-pwa"
+];
+/**
+* Validates a resolved `--cell-platform` value against {@link ALLOWED_CELL_PLATFORMS}.
+*
+* `undefined` (flag + `AIT_CELL_PLATFORM` env both absent) passes through as
+* `{ ok: true, value: undefined }` — the caller applies its own `'mock'`
+* default, so an omitted platform is never an error. A present-but-unknown
+* value returns `{ ok: false, error }` naming the allowed set.
+*
+* Uses a tagged result (not the `string`-is-error convention of
+* `resolveDashboardPort`/`resolvePace`) because BOTH the success value and the
+* error message are strings here — a bare `string` return would be ambiguous.
+* Exported for unit testing.
+*/
+function resolveCellPlatform(raw) {
+	if (raw === void 0) return {
+		ok: true,
+		value: void 0
+	};
+	if (ALLOWED_CELL_PLATFORMS.includes(raw)) return {
+		ok: true,
+		value: raw
+	};
+	return {
+		ok: false,
+		error: `--cell-platform must be one of ${ALLOWED_CELL_PLATFORMS.join("|")} (got "${raw}")`
+	};
+}
+/**
 * Renders per-file result lines and the aggregate totals line to a string.
 *
 * Each file gets one line:
@@ -1962,8 +2336,8 @@ function shouldSuppressQr(noQrFlag) {
 *
 * 1. Parse args: globs, --timeout (per-file evaluate), --attach-timeout (QR
 *    scan wait), --cell-sdk-line, --cell-platform, --scheme-url (required for
-*    env3), --report-dir, --dashboard-port, --no-qr-stdout, --headless,
-*    --project-root.
+*    env3) OR --attach-launcher + --app-url (env2, devtools#774), --report-dir,
+*    --dashboard-port, --no-qr-stdout, --headless, --project-root.
 * 2. Discover test files; exit 1 if none.
 * 3. factory.open() — boot relay → render QR (suppressed on non-interactive
 *    stdout) → wait for phone (up to attachTimeoutMs) → inject cell →
@@ -1984,7 +2358,7 @@ async function main(argv = process.argv.slice(2)) {
 	let parsed;
 	try {
 		parsed = parseArgs({
-			args: argv,
+			args: normalizePaceArgv(argv),
 			options: {
 				help: {
 					type: "boolean",
@@ -1993,6 +2367,8 @@ async function main(argv = process.argv.slice(2)) {
 				timeout: { type: "string" },
 				"attach-timeout": { type: "string" },
 				"scheme-url": { type: "string" },
+				"attach-launcher": { type: "boolean" },
+				"app-url": { type: "string" },
 				"cell-sdk-line": { type: "string" },
 				"cell-platform": { type: "string" },
 				"report-dir": { type: "string" },
@@ -2000,7 +2376,10 @@ async function main(argv = process.argv.slice(2)) {
 				"no-qr-stdout": { type: "boolean" },
 				headless: { type: "boolean" },
 				"project-root": { type: "string" },
-				"manual-blocking": { type: "boolean" }
+				pace: { type: "string" },
+				"pace-method": { type: "string" },
+				"manual-blocking": { type: "boolean" },
+				"stub-blocking": { type: "boolean" }
 			},
 			allowPositionals: true
 		});
@@ -2021,9 +2400,17 @@ async function main(argv = process.argv.slice(2)) {
 		return;
 	}
 	const { evaluateTimeoutMs, attachTimeoutMs } = timeouts;
+	const attachLauncher = vals["attach-launcher"] === true;
 	const schemeUrl = typeof vals["scheme-url"] === "string" ? vals["scheme-url"] : "";
-	if (schemeUrl === "") {
-		process.stderr.write("devtools-test: --scheme-url is required for standalone relay attach.\n  Pass the intoss-private:// URL from `ait deploy --scheme-only`.\n");
+	const appUrl = typeof vals["app-url"] === "string" ? vals["app-url"] : "";
+	if (attachLauncher) {
+		if (appUrl === "") {
+			process.stderr.write("devtools-test: --app-url is required with --attach-launcher (env 2).\n  Pass the consumer dev server's tunnel URL (e.g. the HTTP *.trycloudflare.com\n  URL printed by `pnpm dev:phone:cdp`). --scheme-url is not used in this mode.\n");
+			process.exitCode = 1;
+			return;
+		}
+	} else if (schemeUrl === "") {
+		process.stderr.write("devtools-test: --scheme-url is required for standalone relay attach.\n  Pass the intoss-private:// URL from `ait deploy --scheme-only`.\n  (For env 2 / AITC Sandbox PWA, use --attach-launcher --app-url <tunnel-url> instead.)\n");
 		process.exitCode = 1;
 		return;
 	}
@@ -2036,15 +2423,34 @@ async function main(argv = process.argv.slice(2)) {
 		process.exitCode = 1;
 		return;
 	}
+	const paceMs = resolvePace(typeof vals.pace === "string" ? vals.pace : void 0, process.env.AIT_PACE);
+	if (typeof paceMs === "string") {
+		process.stderr.write(`devtools-test: ${paceMs}\n`);
+		process.exitCode = 1;
+		return;
+	}
 	const suppressQr = shouldSuppressQr(vals["no-qr-stdout"] === true);
-	const manualBlocking = vals["manual-blocking"] === true;
+	const stubBlocking = vals["stub-blocking"] === true;
+	const manualBlocking = vals["manual-blocking"] === true || stubBlocking;
 	const cellSdkLine = typeof vals["cell-sdk-line"] === "string" ? vals["cell-sdk-line"] : void 0;
-	const cellPlatform = typeof vals["cell-platform"] === "string" ? vals["cell-platform"] : process.env.AIT_CELL_PLATFORM;
+	const cellPlatformResult = resolveCellPlatform(typeof vals["cell-platform"] === "string" ? vals["cell-platform"] : process.env.AIT_CELL_PLATFORM);
+	if (!cellPlatformResult.ok) {
+		process.stderr.write(`devtools-test: ${cellPlatformResult.error}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	const cellPlatform = cellPlatformResult.value;
 	const hasCell = cellSdkLine !== void 0 || cellPlatform !== void 0;
 	const cell = {
 		sdkLine: cellSdkLine ?? "2.x",
 		platform: cellPlatform ?? "mock"
 	};
+	const paceMethodMs = resolvePaceMethod(typeof vals["pace-method"] === "string" ? vals["pace-method"] : void 0, process.env.AIT_PACE_METHOD, cell.sdkLine);
+	if (typeof paceMethodMs === "string") {
+		process.stderr.write(`devtools-test: ${paceMethodMs}\n`);
+		process.exitCode = 1;
+		return;
+	}
 	const globs = parsed.positionals;
 	if (globs.length === 0) {
 		process.stderr.write(`devtools-test: at least one glob pattern is required\n`);
@@ -2063,13 +2469,23 @@ async function main(argv = process.argv.slice(2)) {
 	const manualFileSet = new Set(manual);
 	process.stderr.write(manualBlocking && manual.length > 0 ? `devtools-test: found ${regular.length} regular + ${manual.length} manual (${MANUAL_TEST_SUFFIX}) test file(s)\n` : `devtools-test: found ${files.length} test file(s)\n`);
 	if (hasCell) process.stderr.write(`devtools-test: injecting __AIT_CELL__ = ${JSON.stringify(cell)}\n`);
+	if (stubBlocking) process.stderr.write("devtools-test: --stub-blocking enabled — blocking-UI calls in manual-tagged files will be answered from fixtures (devtools#740), not forwarded to native UI\n");
+	if (paceMs > 0) process.stderr.write(`devtools-test: --pace ${paceMs}ms enabled (devtools#767)\n`);
+	if (paceMethodMs > 0) process.stderr.write(`devtools-test: --pace-method ${paceMethodMs}ms enabled (devtools#769)\n`);
 	const factory = createRelayConnectionFactory({
 		schemeUrl,
+		...attachLauncher ? {
+			attachLauncher: true,
+			appUrl
+		} : {},
 		projectRoot,
 		...attachTimeoutMs !== void 0 ? { timeoutMs: attachTimeoutMs } : {},
 		...dashboardPort !== void 0 ? { dashboardPort } : {},
 		headless,
 		cell: hasCell ? cell : void 0,
+		stubBlocking,
+		paceMs,
+		paceMethodMs,
 		onQrContent: (chunks) => {
 			if (suppressQr) {
 				process.stdout.write("QR suppressed (non-interactive)\n");
@@ -2093,7 +2509,10 @@ async function main(argv = process.argv.slice(2)) {
 			timeoutMs: evaluateTimeoutMs,
 			printSummary: true,
 			collectCaptures: reportDir !== void 0,
+			paceMs,
+			preflightSdkLine: cell.sdkLine,
 			manualFiles: manualBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
+			stubBlockingFiles: stubBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
 			onManualFile: (file, index, total) => {
 				const name = basename(file);
 				process.stdout.write(`수동 단계: ${name} — 폰에서 네이티브 시트가 뜨면 안내에 따라 조작하세요 (${index}/${total})\n`);