@ait-co/devtools 0.1.131 → 0.1.133

package/dist/cell-BIdSQb9T.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { t as __exportAll } from "./rolldown-runtime-DGkTqVfb.js";
+import { a as buildIndicatorExpression } from "./attach-orchestrator-CE0S09YU.js";
+//#region src/test-runner/cell.ts
+var cell_exports = /* @__PURE__ */ __exportAll({
+	PERMISSION_PREFLIGHT_TIMEOUT_MS: () => PERMISSION_PREFLIGHT_TIMEOUT_MS,
+	buildPermissionPreflightExpression: () => buildPermissionPreflightExpression,
+	injectDebugIndicator: () => injectDebugIndicator,
+	injectGlobals: () => injectGlobals,
+	runPermissionPreflight: () => runPermissionPreflight
+});
+/**
+* Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).
+*
+* Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the
+* first test bundle is injected. The injected values are session-global — one
+* call covers all files in the run.
+*
+* The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so
+* sdk-example's `aitCapture.ts` picks up the correct test-axis values instead
+* of falling back to `'2.x'`/`'mock'`.
+*
+* devtools does NOT know the shape of `__AIT_CELL__` — it only provides the
+* general injection mechanism. The caller (CLI or MCP auto-attach path) is
+* responsible for constructing the cell object.
+*
+* SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be
+* logged at the caller's discretion. This module does NOT log them itself.
+*
+* Node-only. react-free. CdpConnection only.
+*/
+/**
+* `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed
+* (devtools#739). This is the exact contract sdk-example#265 consumes — do
+* not rename keys without a coordinated sdk-example update.
+*
+* Each SDK function is reached via `window.__sdk` — the SAME page-global
+* bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see
+* `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled
+* `@apps-in-toss/web-framework` imports to this same object at runtime). The
+* test-runner bundle owns no independent SDK import — `window.__sdk` is a
+* page global regardless of whether a bundle has been injected yet, so this
+* preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`
+* mechanism BEFORE the first bundle, rather than being prepended into
+* `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —
+* bundle-prepend was the fallback plan if the SDK were only reachable from
+* inside bundle scope, which reality ruled out.)
+*/
+const PERMISSION_PROBE_MAP = {
+	clipboardRead: "getClipboardText",
+	clipboardWrite: "setClipboardText",
+	album: "fetchAlbumPhotos",
+	camera: "openCamera",
+	contacts: "fetchContacts",
+	location: "getCurrentLocation"
+};
+/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */
+const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
+/**
+* Builds the `Runtime.evaluate` expression for the permission-state preflight
+* (devtools#739). Evaluated ONCE per relay session, before the first test
+* bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).
+*
+* For each entry in {@link PERMISSION_PROBE_MAP}, probes
+* `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never
+* `openPermissionDialog`/`requestPermission`, which open native UI) — and
+* assigns the resolved `'allowed'|'denied'|'notDetermined'` status to
+* `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or
+* rejects resolves to `'unavailable'` — this expression never throws to its
+* caller, and a single slow/broken permission must not fail the others (each
+* probe is awaited independently, not short-circuited).
+*
+* Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch
+* deterministically per permission state instead of blanket outcome-branching.
+*
+* Returns a JSON-serialised string (the same double-serialisation pattern
+* `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP
+* `returnByValue` structural fidelity for a plain object across the Chii
+* relay — the Node side re-parses via `JSON.parse`.
+*
+* Pure function — no I/O, no CDP call. Callers pass the returned string to
+* `Runtime.evaluate`.
+*/
+function buildPermissionPreflightExpression() {
+	return `(async () => {  const probe = async (fnName) => {    try {      const fn = globalThis.__sdk && globalThis.__sdk[fnName];      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';      const status = await fn.getPermission();      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;      return 'unavailable';    } catch (e) {      return 'unavailable';    }  };  const result = {};${Object.entries(PERMISSION_PROBE_MAP).map(([key, fnName]) => `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`).join("\n")}\n  globalThis.__AIT_PERMS__ = result;  return JSON.stringify(result);})()`;
+}
+/**
+* Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`
+* and returns the collected `__AIT_PERMS__` map, or `undefined` when the
+* preflight itself failed or timed out.
+*
+* NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)
+* is caught here, logged as ONE stderr line, and swallowed — the whole test
+* run must proceed even when the preflight cannot complete (e.g. `window.__sdk`
+* not yet installed, or a page navigation mid-attach). Callers that want the
+* result for report provenance (`RelayRunReport.preflight`) get `undefined`
+* in that case, which downstream code treats the same as "not run".
+*
+* SECRET-HANDLING: no relay/wss/secret values are read or logged; only
+* permission-state strings cross this boundary.
+*
+* @param conn      - The live CDP connection (relay-attached page).
+* @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.
+*/
+async function runPermissionPreflight(conn, timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS) {
+	const TIMEOUT_SENTINEL = Symbol("permission-preflight-timeout");
+	const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs));
+	try {
+		const evalPromise = conn.send("Runtime.evaluate", {
+			expression: buildPermissionPreflightExpression(),
+			returnByValue: true,
+			awaitPromise: true
+		});
+		const raceResult = await Promise.race([evalPromise.then((v) => ({
+			tag: "eval",
+			v
+		})), timeoutPromise.then(() => ({ tag: "timeout" }))]);
+		if (raceResult.tag === "timeout") {
+			process.stderr.write(`test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\n`);
+			return;
+		}
+		if (raceResult.v.exceptionDetails) {
+			process.stderr.write("test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\n");
+			return;
+		}
+		const rawValue = raceResult.v.result.value;
+		if (typeof rawValue !== "string") return void 0;
+		const parsed = JSON.parse(rawValue);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		return parsed;
+	} catch (e) {
+		process.stderr.write(`test-runner: permission preflight failed (${e instanceof Error ? e.message : String(e)}) — proceeding with __AIT_PERMS__ unset\n`);
+		return;
+	}
+}
+/**
+* Injects each key of `globals` into `globalThis` in the page via a single
+* `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`
+* inject — the cell is session-global and applies to all subsequent files.
+*
+* Throws if the CDP evaluate returns an exception.
+*
+* @param conn    - The live CDP connection (relay-attached page).
+* @param globals - Plain-JSON-serialisable key→value map to assign onto `globalThis`.
+*/
+async function injectGlobals(conn, globals) {
+	const expr = `(() => { Object.assign(globalThis, ${JSON.stringify(globals)}); return true; })()`;
+	const result = await conn.send("Runtime.evaluate", {
+		expression: expr,
+		returnByValue: true
+	});
+	if (result.exceptionDetails) {
+		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "unknown error";
+		throw new Error(`injectGlobals: Runtime.evaluate threw: ${msg}`);
+	}
+}
+/**
+* Injects (or updates) the "Debugger Connected"/"Debugger Disconnected"
+* on-phone indicator via `Runtime.evaluate` (#730).
+*
+* Uses the same CDP mechanism as {@link injectGlobals} — a single
+* `Runtime.evaluate` round-trip with the expression built by
+* {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at
+* the bottom-left of the page (position:fixed, safe-area-aware): the badge's
+* controller is idempotent, so calling this again (e.g. right before
+* `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in
+* place instead of injecting a duplicate.
+*
+* **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to
+* its caller. Injection failure (e.g. page detached during inject, CSS not
+* supported) is swallowed and logged as `console.debug` — the badge is
+* informational UI and must never block attach success or test execution.
+* This is the same fire-and-forget spirit as the in-page console mount in
+* `src/in-app/attach.ts`.
+*
+* Call this ONLY on the manual debug paths (start_attach MCP, devtools-test
+* CLI). Do NOT call on the `run_tests` auto-attach path — the badge
+* would contaminate screenshots, measure_safe_area probes, and DOM snapshots
+* taken during automated measurement runs.
+*
+* SECRET-HANDLING: the injected expression contains no secrets, relay URLs,
+* wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by
+* {@link buildIndicatorExpression}.
+*
+* @param conn - The live CDP connection (relay-attached page).
+* @param opts - Optional overrides forwarded to {@link buildIndicatorExpression}.
+*/
+async function injectDebugIndicator(conn, opts) {
+	try {
+		await conn.send("Runtime.evaluate", {
+			expression: buildIndicatorExpression(opts),
+			returnByValue: true
+		});
+	} catch (err) {
+		console.debug("[@ait-co/devtools] debug indicator inject skipped:", err);
+	}
+}
+//#endregion
+export { runPermissionPreflight as n, cell_exports as t };
+
+//# sourceMappingURL=cell-BIdSQb9T.js.map

package/dist/cell-BIdSQb9T.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-BIdSQb9T.js","names":[],"sources":["../src/test-runner/cell.ts"],"sourcesContent":["/**\n * Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).\n *\n * Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the\n * first test bundle is injected. The injected values are session-global — one\n * call covers all files in the run.\n *\n * The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so\n * sdk-example's `aitCapture.ts` picks up the correct test-axis values instead\n * of falling back to `'2.x'`/`'mock'`.\n *\n * devtools does NOT know the shape of `__AIT_CELL__` — it only provides the\n * general injection mechanism. The caller (CLI or MCP auto-attach path) is\n * responsible for constructing the cell object.\n *\n * SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be\n * logged at the caller's discretion. This module does NOT log them itself.\n *\n * Node-only. react-free. CdpConnection only.\n */\n\n/**\n * `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed\n * (devtools#739). This is the exact contract sdk-example#265 consumes — do\n * not rename keys without a coordinated sdk-example update.\n *\n * Each SDK function is reached via `window.__sdk` — the SAME page-global\n * bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see\n * `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled\n * `@apps-in-toss/web-framework` imports to this same object at runtime). The\n * test-runner bundle owns no independent SDK import — `window.__sdk` is a\n * page global regardless of whether a bundle has been injected yet, so this\n * preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`\n * mechanism BEFORE the first bundle, rather than being prepended into\n * `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —\n * bundle-prepend was the fallback plan if the SDK were only reachable from\n * inside bundle scope, which reality ruled out.)\n */\nconst PERMISSION_PROBE_MAP: Record<string, string> = {\n  clipboardRead: 'getClipboardText',\n  clipboardWrite: 'setClipboardText',\n  album: 'fetchAlbumPhotos',\n  camera: 'openCamera',\n  contacts: 'fetchContacts',\n  location: 'getCurrentLocation',\n};\n\n/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */\nexport const PERMISSION_PREFLIGHT_TIMEOUT_MS = 10_000;\n\n/**\n * Builds the `Runtime.evaluate` expression for the permission-state preflight\n * (devtools#739). Evaluated ONCE per relay session, before the first test\n * bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).\n *\n * For each entry in {@link PERMISSION_PROBE_MAP}, probes\n * `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never\n * `openPermissionDialog`/`requestPermission`, which open native UI) — and\n * assigns the resolved `'allowed'|'denied'|'notDetermined'` status to\n * `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or\n * rejects resolves to `'unavailable'` — this expression never throws to its\n * caller, and a single slow/broken permission must not fail the others (each\n * probe is awaited independently, not short-circuited).\n *\n * Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch\n * deterministically per permission state instead of blanket outcome-branching.\n *\n * Returns a JSON-serialised string (the same double-serialisation pattern\n * `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP\n * `returnByValue` structural fidelity for a plain object across the Chii\n * relay — the Node side re-parses via `JSON.parse`.\n *\n * Pure function — no I/O, no CDP call. Callers pass the returned string to\n * `Runtime.evaluate`.\n */\nexport function buildPermissionPreflightExpression(): string {\n  const probeEntries = Object.entries(PERMISSION_PROBE_MAP)\n    .map(\n      ([key, fnName]) =>\n        `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`,\n    )\n    .join('\\n');\n\n  return (\n    `(async () => {` +\n    `  const probe = async (fnName) => {` +\n    `    try {` +\n    `      const fn = globalThis.__sdk && globalThis.__sdk[fnName];` +\n    `      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';` +\n    `      const status = await fn.getPermission();` +\n    `      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;` +\n    `      return 'unavailable';` +\n    `    } catch (e) {` +\n    `      return 'unavailable';` +\n    `    }` +\n    `  };` +\n    `  const result = {};` +\n    `${probeEntries}\\n` +\n    `  globalThis.__AIT_PERMS__ = result;` +\n    `  return JSON.stringify(result);` +\n    `})()`\n  );\n}\n\n/**\n * Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`\n * and returns the collected `__AIT_PERMS__` map, or `undefined` when the\n * preflight itself failed or timed out.\n *\n * NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)\n * is caught here, logged as ONE stderr line, and swallowed — the whole test\n * run must proceed even when the preflight cannot complete (e.g. `window.__sdk`\n * not yet installed, or a page navigation mid-attach). Callers that want the\n * result for report provenance (`RelayRunReport.preflight`) get `undefined`\n * in that case, which downstream code treats the same as \"not run\".\n *\n * SECRET-HANDLING: no relay/wss/secret values are read or logged; only\n * permission-state strings cross this boundary.\n *\n * @param conn      - The live CDP connection (relay-attached page).\n * @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.\n */\nexport async function runPermissionPreflight(\n  conn: CdpConnection,\n  timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS,\n): Promise<Record<string, string> | undefined> {\n  const TIMEOUT_SENTINEL = Symbol('permission-preflight-timeout');\n  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) =>\n    setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs),\n  );\n\n  try {\n    const evalPromise = conn.send('Runtime.evaluate', {\n      expression: buildPermissionPreflightExpression(),\n      returnByValue: true,\n      awaitPromise: true,\n    });\n\n    const raceResult = await Promise.race([\n      evalPromise.then((v) => ({ tag: 'eval' as const, v })),\n      timeoutPromise.then(() => ({ tag: 'timeout' as const })),\n    ]);\n\n    if (raceResult.tag === 'timeout') {\n      process.stderr.write(\n        `test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\\n`,\n      );\n      return undefined;\n    }\n\n    if (raceResult.v.exceptionDetails) {\n      process.stderr.write(\n        'test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\\n',\n      );\n      return undefined;\n    }\n\n    const rawValue = raceResult.v.result.value;\n    if (typeof rawValue !== 'string') return undefined;\n    const parsed: unknown = JSON.parse(rawValue);\n    if (typeof parsed !== 'object' || parsed === null) return undefined;\n    return parsed as Record<string, string>;\n  } catch (e) {\n    process.stderr.write(\n      `test-runner: permission preflight failed (${\n        e instanceof Error ? e.message : String(e)\n      }) — proceeding with __AIT_PERMS__ unset\\n`,\n    );\n    return undefined;\n  }\n}\n\nimport { buildIndicatorExpression } from '../mcp/attach-orchestrator.js';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\n\n/**\n * Injects each key of `globals` into `globalThis` in the page via a single\n * `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`\n * inject — the cell is session-global and applies to all subsequent files.\n *\n * Throws if the CDP evaluate returns an exception.\n *\n * @param conn    - The live CDP connection (relay-attached page).\n * @param globals - Plain-JSON-serialisable key→value map to assign onto `globalThis`.\n */\nexport async function injectGlobals(\n  conn: CdpConnection,\n  globals: Record<string, unknown>,\n): Promise<void> {\n  // JSON.stringify is safe here: globals values are plain data (sdkLine/platform\n  // strings or simple objects). If a value is not JSON-serialisable this throws\n  // at call time, which surfaces the error early and clearly.\n  const expr = `(() => { Object.assign(globalThis, ${JSON.stringify(globals)}); return true; })()`;\n  const result = await conn.send('Runtime.evaluate', { expression: expr, returnByValue: true });\n  if (result.exceptionDetails) {\n    const msg =\n      result.exceptionDetails.exception?.description ??\n      result.exceptionDetails.text ??\n      'unknown error';\n    throw new Error(`injectGlobals: Runtime.evaluate threw: ${msg}`);\n  }\n}\n\n/**\n * Injects (or updates) the \"Debugger Connected\"/\"Debugger Disconnected\"\n * on-phone indicator via `Runtime.evaluate` (#730).\n *\n * Uses the same CDP mechanism as {@link injectGlobals} — a single\n * `Runtime.evaluate` round-trip with the expression built by\n * {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at\n * the bottom-left of the page (position:fixed, safe-area-aware): the badge's\n * controller is idempotent, so calling this again (e.g. right before\n * `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in\n * place instead of injecting a duplicate.\n *\n * **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to\n * its caller. Injection failure (e.g. page detached during inject, CSS not\n * supported) is swallowed and logged as `console.debug` — the badge is\n * informational UI and must never block attach success or test execution.\n * This is the same fire-and-forget spirit as the in-page console mount in\n * `src/in-app/attach.ts`.\n *\n * Call this ONLY on the manual debug paths (start_attach MCP, devtools-test\n * CLI). Do NOT call on the `run_tests` auto-attach path — the badge\n * would contaminate screenshots, measure_safe_area probes, and DOM snapshots\n * taken during automated measurement runs.\n *\n * SECRET-HANDLING: the injected expression contains no secrets, relay URLs,\n * wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by\n * {@link buildIndicatorExpression}.\n *\n * @param conn - The live CDP connection (relay-attached page).\n * @param opts - Optional overrides forwarded to {@link buildIndicatorExpression}.\n */\nexport async function injectDebugIndicator(\n  conn: CdpConnection,\n  opts?: { label?: string; disconnectedLabel?: string; state?: 'attached' | 'disconnected' },\n): Promise<void> {\n  try {\n    await conn.send('Runtime.evaluate', {\n      expression: buildIndicatorExpression(opts),\n      returnByValue: true,\n    });\n  } catch (err) {\n    // Badge injection is informational UI — swallow and log; never propagate.\n    console.debug('[@ait-co/devtools] debug indicator inject skipped:', err);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,MAAM,uBAA+C;CACnD,eAAe;CACf,gBAAgB;CAChB,OAAO;CACP,QAAQ;CACR,UAAU;CACV,UAAU;CACX;;AAGD,MAAa,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;AA2B/C,SAAgB,qCAA6C;AAQ3D,QACE,8bARmB,OAAO,QAAQ,qBAAqB,CACtD,KACE,CAAC,KAAK,YACL,cAAc,KAAK,UAAU,IAAI,CAAC,kBAAkB,KAAK,UAAU,OAAO,CAAC,IAC9E,CACA,KAAK,KAAK,CAgBK;;;;;;;;;;;;;;;;;;;;AAyBpB,eAAsB,uBACpB,MACA,YAAY,iCACiC;CAC7C,MAAM,mBAAmB,OAAO,+BAA+B;CAC/D,MAAM,iBAAiB,IAAI,SAAkC,YAC3D,iBAAiB,QAAQ,iBAAiB,EAAE,UAAU,CACvD;AAED,KAAI;EACF,MAAM,cAAc,KAAK,KAAK,oBAAoB;GAChD,YAAY,oCAAoC;GAChD,eAAe;GACf,cAAc;GACf,CAAC;EAEF,MAAM,aAAa,MAAM,QAAQ,KAAK,CACpC,YAAY,MAAM,OAAO;GAAE,KAAK;GAAiB;GAAG,EAAE,EACtD,eAAe,YAAY,EAAE,KAAK,WAAoB,EAAE,CACzD,CAAC;AAEF,MAAI,WAAW,QAAQ,WAAW;AAChC,WAAQ,OAAO,MACb,qDAAqD,UAAU,4CAChE;AACD;;AAGF,MAAI,WAAW,EAAE,kBAAkB;AACjC,WAAQ,OAAO,MACb,kFACD;AACD;;EAGF,MAAM,WAAW,WAAW,EAAE,OAAO;AACrC,MAAI,OAAO,aAAa,SAAU,QAAO,KAAA;EACzC,MAAM,SAAkB,KAAK,MAAM,SAAS;AAC5C,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO,KAAA;AAC1D,SAAO;UACA,GAAG;AACV,UAAQ,OAAO,MACb,6CACE,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAC3C,2CACF;AACD;;;;;;;;;;;;;AAiBJ,eAAsB,cACpB,MACA,SACe;CAIf,MAAM,OAAO,sCAAsC,KAAK,UAAU,QAAQ,CAAC;CAC3E,MAAM,SAAS,MAAM,KAAK,KAAK,oBAAoB;EAAE,YAAY;EAAM,eAAe;EAAM,CAAC;AAC7F,KAAI,OAAO,kBAAkB;EAC3B,MAAM,MACJ,OAAO,iBAAiB,WAAW,eACnC,OAAO,iBAAiB,QACxB;AACF,QAAM,IAAI,MAAM,0CAA0C,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCpE,eAAsB,qBACpB,MACA,MACe;AACf,KAAI;AACF,QAAM,KAAK,KAAK,oBAAoB;GAClC,YAAY,yBAAyB,KAAK;GAC1C,eAAe;GAChB,CAAC;UACK,KAAK;AAEZ,UAAQ,MAAM,sDAAsD,IAAI"}

package/dist/{cell-Cw4fVOl2.js → cell-D1y4shoV.js}

@@ -1,26 +1,6 @@
 import { buildIndicatorExpression } from "./attach-orchestrator-Cjdhir2U.js";
 //#region src/test-runner/cell.ts
 /**
-* Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).
-*
-* Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the
-* first test bundle is injected. The injected values are session-global — one
-* call covers all files in the run.
-*
-* The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so
-* sdk-example's `aitCapture.ts` picks up the correct test-axis values instead
-* of falling back to `'2.x'`/`'mock'`.
-*
-* devtools does NOT know the shape of `__AIT_CELL__` — it only provides the
-* general injection mechanism. The caller (CLI or MCP auto-attach path) is
-* responsible for constructing the cell object.
-*
-* SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be
-* logged at the caller's discretion. This module does NOT log them itself.
-*
-* Node-only. react-free. CdpConnection only.
-*/
-/**
 * Injects each key of `globals` into `globalThis` in the page via a single
 * `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`
 * inject — the cell is session-global and applies to all subsequent files.
@@ -85,4 +65,4 @@ async function injectDebugIndicator(conn, opts) {
 //#endregion
 export { injectDebugIndicator, injectGlobals };
 
-//# sourceMappingURL=cell-Cw4fVOl2.js.map
+//# sourceMappingURL=cell-D1y4shoV.js.map

package/dist/cell-D1y4shoV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-D1y4shoV.js","names":[],"sources":["../src/test-runner/cell.ts"],"sourcesContent":["/**\n * Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).\n *\n * Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the\n * first test bundle is injected. The injected values are session-global — one\n * call covers all files in the run.\n *\n * The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so\n * sdk-example's `aitCapture.ts` picks up the correct test-axis values instead\n * of falling back to `'2.x'`/`'mock'`.\n *\n * devtools does NOT know the shape of `__AIT_CELL__` — it only provides the\n * general injection mechanism. The caller (CLI or MCP auto-attach path) is\n * responsible for constructing the cell object.\n *\n * SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be\n * logged at the caller's discretion. This module does NOT log them itself.\n *\n * Node-only. react-free. CdpConnection only.\n */\n\n/**\n * `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed\n * (devtools#739). This is the exact contract sdk-example#265 consumes — do\n * not rename keys without a coordinated sdk-example update.\n *\n * Each SDK function is reached via `window.__sdk` — the SAME page-global\n * bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see\n * `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled\n * `@apps-in-toss/web-framework` imports to this same object at runtime). The\n * test-runner bundle owns no independent SDK import — `window.__sdk` is a\n * page global regardless of whether a bundle has been injected yet, so this\n * preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`\n * mechanism BEFORE the first bundle, rather than being prepended into\n * `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —\n * bundle-prepend was the fallback plan if the SDK were only reachable from\n * inside bundle scope, which reality ruled out.)\n */\nconst PERMISSION_PROBE_MAP: Record<string, string> = {\n  clipboardRead: 'getClipboardText',\n  clipboardWrite: 'setClipboardText',\n  album: 'fetchAlbumPhotos',\n  camera: 'openCamera',\n  contacts: 'fetchContacts',\n  location: 'getCurrentLocation',\n};\n\n/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */\nexport const PERMISSION_PREFLIGHT_TIMEOUT_MS = 10_000;\n\n/**\n * Builds the `Runtime.evaluate` expression for the permission-state preflight\n * (devtools#739). Evaluated ONCE per relay session, before the first test\n * bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).\n *\n * For each entry in {@link PERMISSION_PROBE_MAP}, probes\n * `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never\n * `openPermissionDialog`/`requestPermission`, which open native UI) — and\n * assigns the resolved `'allowed'|'denied'|'notDetermined'` status to\n * `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or\n * rejects resolves to `'unavailable'` — this expression never throws to its\n * caller, and a single slow/broken permission must not fail the others (each\n * probe is awaited independently, not short-circuited).\n *\n * Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch\n * deterministically per permission state instead of blanket outcome-branching.\n *\n * Returns a JSON-serialised string (the same double-serialisation pattern\n * `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP\n * `returnByValue` structural fidelity for a plain object across the Chii\n * relay — the Node side re-parses via `JSON.parse`.\n *\n * Pure function — no I/O, no CDP call. Callers pass the returned string to\n * `Runtime.evaluate`.\n */\nexport function buildPermissionPreflightExpression(): string {\n  const probeEntries = Object.entries(PERMISSION_PROBE_MAP)\n    .map(\n      ([key, fnName]) =>\n        `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`,\n    )\n    .join('\\n');\n\n  return (\n    `(async () => {` +\n    `  const probe = async (fnName) => {` +\n    `    try {` +\n    `      const fn = globalThis.__sdk && globalThis.__sdk[fnName];` +\n    `      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';` +\n    `      const status = await fn.getPermission();` +\n    `      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;` +\n    `      return 'unavailable';` +\n    `    } catch (e) {` +\n    `      return 'unavailable';` +\n    `    }` +\n    `  };` +\n    `  const result = {};` +\n    `${probeEntries}\\n` +\n    `  globalThis.__AIT_PERMS__ = result;` +\n    `  return JSON.stringify(result);` +\n    `})()`\n  );\n}\n\n/**\n * Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`\n * and returns the collected `__AIT_PERMS__` map, or `undefined` when the\n * preflight itself failed or timed out.\n *\n * NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)\n * is caught here, logged as ONE stderr line, and swallowed — the whole test\n * run must proceed even when the preflight cannot complete (e.g. `window.__sdk`\n * not yet installed, or a page navigation mid-attach). Callers that want the\n * result for report provenance (`RelayRunReport.preflight`) get `undefined`\n * in that case, which downstream code treats the same as \"not run\".\n *\n * SECRET-HANDLING: no relay/wss/secret values are read or logged; only\n * permission-state strings cross this boundary.\n *\n * @param conn      - The live CDP connection (relay-attached page).\n * @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.\n */\nexport async function runPermissionPreflight(\n  conn: CdpConnection,\n  timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS,\n): Promise<Record<string, string> | undefined> {\n  const TIMEOUT_SENTINEL = Symbol('permission-preflight-timeout');\n  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) =>\n    setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs),\n  );\n\n  try {\n    const evalPromise = conn.send('Runtime.evaluate', {\n      expression: buildPermissionPreflightExpression(),\n      returnByValue: true,\n      awaitPromise: true,\n    });\n\n    const raceResult = await Promise.race([\n      evalPromise.then((v) => ({ tag: 'eval' as const, v })),\n      timeoutPromise.then(() => ({ tag: 'timeout' as const })),\n    ]);\n\n    if (raceResult.tag === 'timeout') {\n      process.stderr.write(\n        `test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\\n`,\n      );\n      return undefined;\n    }\n\n    if (raceResult.v.exceptionDetails) {\n      process.stderr.write(\n        'test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\\n',\n      );\n      return undefined;\n    }\n\n    const rawValue = raceResult.v.result.value;\n    if (typeof rawValue !== 'string') return undefined;\n    const parsed: unknown = JSON.parse(rawValue);\n    if (typeof parsed !== 'object' || parsed === null) return undefined;\n    return parsed as Record<string, string>;\n  } catch (e) {\n    process.stderr.write(\n      `test-runner: permission preflight failed (${\n        e instanceof Error ? e.message : String(e)\n      }) — proceeding with __AIT_PERMS__ unset\\n`,\n    );\n    return undefined;\n  }\n}\n\nimport { buildIndicatorExpression } from '../mcp/attach-orchestrator.js';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\n\n/**\n * Injects each key of `globals` into `globalThis` in the page via a single\n * `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`\n * inject — the cell is session-global and applies to all subsequent files.\n *\n * Throws if the CDP evaluate returns an exception.\n *\n * @param conn    - The live CDP connection (relay-attached page).\n * @param globals - Plain-JSON-serialisable key→value map to assign onto `globalThis`.\n */\nexport async function injectGlobals(\n  conn: CdpConnection,\n  globals: Record<string, unknown>,\n): Promise<void> {\n  // JSON.stringify is safe here: globals values are plain data (sdkLine/platform\n  // strings or simple objects). If a value is not JSON-serialisable this throws\n  // at call time, which surfaces the error early and clearly.\n  const expr = `(() => { Object.assign(globalThis, ${JSON.stringify(globals)}); return true; })()`;\n  const result = await conn.send('Runtime.evaluate', { expression: expr, returnByValue: true });\n  if (result.exceptionDetails) {\n    const msg =\n      result.exceptionDetails.exception?.description ??\n      result.exceptionDetails.text ??\n      'unknown error';\n    throw new Error(`injectGlobals: Runtime.evaluate threw: ${msg}`);\n  }\n}\n\n/**\n * Injects (or updates) the \"Debugger Connected\"/\"Debugger Disconnected\"\n * on-phone indicator via `Runtime.evaluate` (#730).\n *\n * Uses the same CDP mechanism as {@link injectGlobals} — a single\n * `Runtime.evaluate` round-trip with the expression built by\n * {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at\n * the bottom-left of the page (position:fixed, safe-area-aware): the badge's\n * controller is idempotent, so calling this again (e.g. right before\n * `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in\n * place instead of injecting a duplicate.\n *\n * **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to\n * its caller. Injection failure (e.g. page detached during inject, CSS not\n * supported) is swallowed and logged as `console.debug` — the badge is\n * informational UI and must never block attach success or test execution.\n * This is the same fire-and-forget spirit as the in-page console mount in\n * `src/in-app/attach.ts`.\n *\n * Call this ONLY on the manual debug paths (start_attach MCP, devtools-test\n * CLI). Do NOT call on the `run_tests` auto-attach path — the badge\n * would contaminate screenshots, measure_safe_area probes, and DOM snapshots\n * taken during automated measurement runs.\n *\n * SECRET-HANDLING: the injected expression contains no secrets, relay URLs,\n * wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by\n * {@link buildIndicatorExpression}.\n *\n * @param conn - The live CDP connection (relay-attached page).\n * @param opts - Optional overrides forwarded to {@link buildIndicatorExpression}.\n */\nexport async function injectDebugIndicator(\n  conn: CdpConnection,\n  opts?: { label?: string; disconnectedLabel?: string; state?: 'attached' | 'disconnected' },\n): Promise<void> {\n  try {\n    await conn.send('Runtime.evaluate', {\n      expression: buildIndicatorExpression(opts),\n      returnByValue: true,\n    });\n  } catch (err) {\n    // Badge injection is informational UI — swallow and log; never propagate.\n    console.debug('[@ait-co/devtools] debug indicator inject skipped:', err);\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAyLA,eAAsB,cACpB,MACA,SACe;CAIf,MAAM,OAAO,sCAAsC,KAAK,UAAU,QAAQ,CAAC;CAC3E,MAAM,SAAS,MAAM,KAAK,KAAK,oBAAoB;EAAE,YAAY;EAAM,eAAe;EAAM,CAAC;AAC7F,KAAI,OAAO,kBAAkB;EAC3B,MAAM,MACJ,OAAO,iBAAiB,WAAW,eACnC,OAAO,iBAAiB,QACxB;AACF,QAAM,IAAI,MAAM,0CAA0C,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCpE,eAAsB,qBACpB,MACA,MACe;AACf,KAAI;AACF,QAAM,KAAK,KAAK,oBAAoB;GAClC,YAAY,yBAAyB,KAAK;GAC1C,eAAe;GAChB,CAAC;UACK,KAAK;AAEZ,UAAQ,MAAM,sDAAsD,IAAI"}

package/dist/cell-DHA578lX.js

@@ -0,0 +1,200 @@
+import { t as __exportAll } from "./rolldown-runtime-DUslC3ob.js";
+import { a as buildIndicatorExpression } from "./attach-orchestrator-CMoDuG2A.js";
+//#region src/test-runner/cell.ts
+var cell_exports = /* @__PURE__ */ __exportAll({
+	PERMISSION_PREFLIGHT_TIMEOUT_MS: () => PERMISSION_PREFLIGHT_TIMEOUT_MS,
+	buildPermissionPreflightExpression: () => buildPermissionPreflightExpression,
+	injectDebugIndicator: () => injectDebugIndicator,
+	injectGlobals: () => injectGlobals,
+	runPermissionPreflight: () => runPermissionPreflight
+});
+/**
+* Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).
+*
+* Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the
+* first test bundle is injected. The injected values are session-global — one
+* call covers all files in the run.
+*
+* The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so
+* sdk-example's `aitCapture.ts` picks up the correct test-axis values instead
+* of falling back to `'2.x'`/`'mock'`.
+*
+* devtools does NOT know the shape of `__AIT_CELL__` — it only provides the
+* general injection mechanism. The caller (CLI or MCP auto-attach path) is
+* responsible for constructing the cell object.
+*
+* SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be
+* logged at the caller's discretion. This module does NOT log them itself.
+*
+* Node-only. react-free. CdpConnection only.
+*/
+/**
+* `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed
+* (devtools#739). This is the exact contract sdk-example#265 consumes — do
+* not rename keys without a coordinated sdk-example update.
+*
+* Each SDK function is reached via `window.__sdk` — the SAME page-global
+* bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see
+* `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled
+* `@apps-in-toss/web-framework` imports to this same object at runtime). The
+* test-runner bundle owns no independent SDK import — `window.__sdk` is a
+* page global regardless of whether a bundle has been injected yet, so this
+* preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`
+* mechanism BEFORE the first bundle, rather than being prepended into
+* `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —
+* bundle-prepend was the fallback plan if the SDK were only reachable from
+* inside bundle scope, which reality ruled out.)
+*/
+const PERMISSION_PROBE_MAP = {
+	clipboardRead: "getClipboardText",
+	clipboardWrite: "setClipboardText",
+	album: "fetchAlbumPhotos",
+	camera: "openCamera",
+	contacts: "fetchContacts",
+	location: "getCurrentLocation"
+};
+/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */
+const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
+/**
+* Builds the `Runtime.evaluate` expression for the permission-state preflight
+* (devtools#739). Evaluated ONCE per relay session, before the first test
+* bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).
+*
+* For each entry in {@link PERMISSION_PROBE_MAP}, probes
+* `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never
+* `openPermissionDialog`/`requestPermission`, which open native UI) — and
+* assigns the resolved `'allowed'|'denied'|'notDetermined'` status to
+* `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or
+* rejects resolves to `'unavailable'` — this expression never throws to its
+* caller, and a single slow/broken permission must not fail the others (each
+* probe is awaited independently, not short-circuited).
+*
+* Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch
+* deterministically per permission state instead of blanket outcome-branching.
+*
+* Returns a JSON-serialised string (the same double-serialisation pattern
+* `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP
+* `returnByValue` structural fidelity for a plain object across the Chii
+* relay — the Node side re-parses via `JSON.parse`.
+*
+* Pure function — no I/O, no CDP call. Callers pass the returned string to
+* `Runtime.evaluate`.
+*/
+function buildPermissionPreflightExpression() {
+	return `(async () => {  const probe = async (fnName) => {    try {      const fn = globalThis.__sdk && globalThis.__sdk[fnName];      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';      const status = await fn.getPermission();      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;      return 'unavailable';    } catch (e) {      return 'unavailable';    }  };  const result = {};${Object.entries(PERMISSION_PROBE_MAP).map(([key, fnName]) => `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`).join("\n")}\n  globalThis.__AIT_PERMS__ = result;  return JSON.stringify(result);})()`;
+}
+/**
+* Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`
+* and returns the collected `__AIT_PERMS__` map, or `undefined` when the
+* preflight itself failed or timed out.
+*
+* NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)
+* is caught here, logged as ONE stderr line, and swallowed — the whole test
+* run must proceed even when the preflight cannot complete (e.g. `window.__sdk`
+* not yet installed, or a page navigation mid-attach). Callers that want the
+* result for report provenance (`RelayRunReport.preflight`) get `undefined`
+* in that case, which downstream code treats the same as "not run".
+*
+* SECRET-HANDLING: no relay/wss/secret values are read or logged; only
+* permission-state strings cross this boundary.
+*
+* @param conn      - The live CDP connection (relay-attached page).
+* @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.
+*/
+async function runPermissionPreflight(conn, timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS) {
+	const TIMEOUT_SENTINEL = Symbol("permission-preflight-timeout");
+	const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs));
+	try {
+		const evalPromise = conn.send("Runtime.evaluate", {
+			expression: buildPermissionPreflightExpression(),
+			returnByValue: true,
+			awaitPromise: true
+		});
+		const raceResult = await Promise.race([evalPromise.then((v) => ({
+			tag: "eval",
+			v
+		})), timeoutPromise.then(() => ({ tag: "timeout" }))]);
+		if (raceResult.tag === "timeout") {
+			process.stderr.write(`test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\n`);
+			return;
+		}
+		if (raceResult.v.exceptionDetails) {
+			process.stderr.write("test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\n");
+			return;
+		}
+		const rawValue = raceResult.v.result.value;
+		if (typeof rawValue !== "string") return void 0;
+		const parsed = JSON.parse(rawValue);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		return parsed;
+	} catch (e) {
+		process.stderr.write(`test-runner: permission preflight failed (${e instanceof Error ? e.message : String(e)}) — proceeding with __AIT_PERMS__ unset\n`);
+		return;
+	}
+}
+/**
+* Injects each key of `globals` into `globalThis` in the page via a single
+* `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`
+* inject — the cell is session-global and applies to all subsequent files.
+*
+* Throws if the CDP evaluate returns an exception.
+*
+* @param conn    - The live CDP connection (relay-attached page).
+* @param globals - Plain-JSON-serialisable key→value map to assign onto `globalThis`.
+*/
+async function injectGlobals(conn, globals) {
+	const expr = `(() => { Object.assign(globalThis, ${JSON.stringify(globals)}); return true; })()`;
+	const result = await conn.send("Runtime.evaluate", {
+		expression: expr,
+		returnByValue: true
+	});
+	if (result.exceptionDetails) {
+		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "unknown error";
+		throw new Error(`injectGlobals: Runtime.evaluate threw: ${msg}`);
+	}
+}
+/**
+* Injects (or updates) the "Debugger Connected"/"Debugger Disconnected"
+* on-phone indicator via `Runtime.evaluate` (#730).
+*
+* Uses the same CDP mechanism as {@link injectGlobals} — a single
+* `Runtime.evaluate` round-trip with the expression built by
+* {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at
+* the bottom-left of the page (position:fixed, safe-area-aware): the badge's
+* controller is idempotent, so calling this again (e.g. right before
+* `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in
+* place instead of injecting a duplicate.
+*
+* **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to
+* its caller. Injection failure (e.g. page detached during inject, CSS not
+* supported) is swallowed and logged as `console.debug` — the badge is
+* informational UI and must never block attach success or test execution.
+* This is the same fire-and-forget spirit as the in-page console mount in
+* `src/in-app/attach.ts`.
+*
+* Call this ONLY on the manual debug paths (start_attach MCP, devtools-test
+* CLI). Do NOT call on the `run_tests` auto-attach path — the badge
+* would contaminate screenshots, measure_safe_area probes, and DOM snapshots
+* taken during automated measurement runs.
+*
+* SECRET-HANDLING: the injected expression contains no secrets, relay URLs,
+* wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by
+* {@link buildIndicatorExpression}.
+*
+* @param conn - The live CDP connection (relay-attached page).
+* @param opts - Optional overrides forwarded to {@link buildIndicatorExpression}.
+*/
+async function injectDebugIndicator(conn, opts) {
+	try {
+		await conn.send("Runtime.evaluate", {
+			expression: buildIndicatorExpression(opts),
+			returnByValue: true
+		});
+	} catch (err) {
+		console.debug("[@ait-co/devtools] debug indicator inject skipped:", err);
+	}
+}
+//#endregion
+export { runPermissionPreflight as n, cell_exports as t };
+
+//# sourceMappingURL=cell-DHA578lX.js.map

package/dist/cell-DHA578lX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-DHA578lX.js","names":[],"sources":["../src/test-runner/cell.ts"],"sourcesContent":["/**\n * Cell injection utility for the `devtools-test` CLI (issue #684 §4.1).\n *\n * Injects arbitrary globals into the page via `Runtime.evaluate` BEFORE the\n * first test bundle is injected. The injected values are session-global — one\n * call covers all files in the run.\n *\n * The primary use-case is injecting `__AIT_CELL__` (sdkLine/platform) so\n * sdk-example's `aitCapture.ts` picks up the correct test-axis values instead\n * of falling back to `'2.x'`/`'mock'`.\n *\n * devtools does NOT know the shape of `__AIT_CELL__` — it only provides the\n * general injection mechanism. The caller (CLI or MCP auto-attach path) is\n * responsible for constructing the cell object.\n *\n * SECRET-HANDLING: cell values (sdkLine/platform) are not secrets and may be\n * logged at the caller's discretion. This module does NOT log them itself.\n *\n * Node-only. react-free. CdpConnection only.\n */\n\n/**\n * `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed\n * (devtools#739). This is the exact contract sdk-example#265 consumes — do\n * not rename keys without a coordinated sdk-example update.\n *\n * Each SDK function is reached via `window.__sdk` — the SAME page-global\n * bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see\n * `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled\n * `@apps-in-toss/web-framework` imports to this same object at runtime). The\n * test-runner bundle owns no independent SDK import — `window.__sdk` is a\n * page global regardless of whether a bundle has been injected yet, so this\n * preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`\n * mechanism BEFORE the first bundle, rather than being prepended into\n * `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —\n * bundle-prepend was the fallback plan if the SDK were only reachable from\n * inside bundle scope, which reality ruled out.)\n */\nconst PERMISSION_PROBE_MAP: Record<string, string> = {\n  clipboardRead: 'getClipboardText',\n  clipboardWrite: 'setClipboardText',\n  album: 'fetchAlbumPhotos',\n  camera: 'openCamera',\n  contacts: 'fetchContacts',\n  location: 'getCurrentLocation',\n};\n\n/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */\nexport const PERMISSION_PREFLIGHT_TIMEOUT_MS = 10_000;\n\n/**\n * Builds the `Runtime.evaluate` expression for the permission-state preflight\n * (devtools#739). Evaluated ONCE per relay session, before the first test\n * bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).\n *\n * For each entry in {@link PERMISSION_PROBE_MAP}, probes\n * `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never\n * `openPermissionDialog`/`requestPermission`, which open native UI) — and\n * assigns the resolved `'allowed'|'denied'|'notDetermined'` status to\n * `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or\n * rejects resolves to `'unavailable'` — this expression never throws to its\n * caller, and a single slow/broken permission must not fail the others (each\n * probe is awaited independently, not short-circuited).\n *\n * Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch\n * deterministically per permission state instead of blanket outcome-branching.\n *\n * Returns a JSON-serialised string (the same double-serialisation pattern\n * `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP\n * `returnByValue` structural fidelity for a plain object across the Chii\n * relay — the Node side re-parses via `JSON.parse`.\n *\n * Pure function — no I/O, no CDP call. Callers pass the returned string to\n * `Runtime.evaluate`.\n */\nexport function buildPermissionPreflightExpression(): string {\n  const probeEntries = Object.entries(PERMISSION_PROBE_MAP)\n    .map(\n      ([key, fnName]) =>\n        `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`,\n    )\n    .join('\\n');\n\n  return (\n    `(async () => {` +\n    `  const probe = async (fnName) => {` +\n    `    try {` +\n    `      const fn = globalThis.__sdk && globalThis.__sdk[fnName];` +\n    `      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';` +\n    `      const status = await fn.getPermission();` +\n    `      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;` +\n    `      return 'unavailable';` +\n    `    } catch (e) {` +\n    `      return 'unavailable';` +\n    `    }` +\n    `  };` +\n    `  const result = {};` +\n    `${probeEntries}\\n` +\n    `  globalThis.__AIT_PERMS__ = result;` +\n    `  return JSON.stringify(result);` +\n    `})()`\n  );\n}\n\n/**\n * Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`\n * and returns the collected `__AIT_PERMS__` map, or `undefined` when the\n * preflight itself failed or timed out.\n *\n * NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)\n * is caught here, logged as ONE stderr line, and swallowed — the whole test\n * run must proceed even when the preflight cannot complete (e.g. `window.__sdk`\n * not yet installed, or a page navigation mid-attach). Callers that want the\n * result for report provenance (`RelayRunReport.preflight`) get `undefined`\n * in that case, which downstream code treats the same as \"not run\".\n *\n * SECRET-HANDLING: no relay/wss/secret values are read or logged; only\n * permission-state strings cross this boundary.\n *\n * @param conn      - The live CDP connection (relay-attached page).\n * @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.\n */\nexport async function runPermissionPreflight(\n  conn: CdpConnection,\n  timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS,\n): Promise<Record<string, string> | undefined> {\n  const TIMEOUT_SENTINEL = Symbol('permission-preflight-timeout');\n  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) =>\n    setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs),\n  );\n\n  try {\n    const evalPromise = conn.send('Runtime.evaluate', {\n      expression: buildPermissionPreflightExpression(),\n      returnByValue: true,\n      awaitPromise: true,\n    });\n\n    const raceResult = await Promise.race([\n      evalPromise.then((v) => ({ tag: 'eval' as const, v })),\n      timeoutPromise.then(() => ({ tag: 'timeout' as const })),\n    ]);\n\n    if (raceResult.tag === 'timeout') {\n      process.stderr.write(\n        `test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\\n`,\n      );\n      return undefined;\n    }\n\n    if (raceResult.v.exceptionDetails) {\n      process.stderr.write(\n        'test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\\n',\n      );\n      return undefined;\n    }\n\n    const rawValue = raceResult.v.result.value;\n    if (typeof rawValue !== 'string') return undefined;\n    const parsed: unknown = JSON.parse(rawValue);\n    if (typeof parsed !== 'object' || parsed === null) return undefined;\n    return parsed as Record<string, string>;\n  } catch (e) {\n    process.stderr.write(\n      `test-runner: permission preflight failed (${\n        e instanceof Error ? e.message : String(e)\n      }) — proceeding with __AIT_PERMS__ unset\\n`,\n    );\n    return undefined;\n  }\n}\n\nimport { buildIndicatorExpression } from '../mcp/attach-orchestrator.js';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\n\n/**\n * Injects each key of `globals` into `globalThis` in the page via a single\n * `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`\n * inject — the cell is session-global and applies to all subsequent files.\n *\n * Throws if the CDP evaluate returns an exception.\n *\n * @param conn    - The live CDP connection (relay-attached page).\n * @param globals - Plain-JSON-serialisable key→value map to assign onto `globalThis`.\n */\nexport async function injectGlobals(\n  conn: CdpConnection,\n  globals: Record<string, unknown>,\n): Promise<void> {\n  // JSON.stringify is safe here: globals values are plain data (sdkLine/platform\n  // strings or simple objects). If a value is not JSON-serialisable this throws\n  // at call time, which surfaces the error early and clearly.\n  const expr = `(() => { Object.assign(globalThis, ${JSON.stringify(globals)}); return true; })()`;\n  const result = await conn.send('Runtime.evaluate', { expression: expr, returnByValue: true });\n  if (result.exceptionDetails) {\n    const msg =\n      result.exceptionDetails.exception?.description ??\n      result.exceptionDetails.text ??\n      'unknown error';\n    throw new Error(`injectGlobals: Runtime.evaluate threw: ${msg}`);\n  }\n}\n\n/**\n * Injects (or updates) the \"Debugger Connected\"/\"Debugger Disconnected\"\n * on-phone indicator via `Runtime.evaluate` (#730).\n *\n * Uses the same CDP mechanism as {@link injectGlobals} — a single\n * `Runtime.evaluate` round-trip with the expression built by\n * {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at\n * the bottom-left of the page (position:fixed, safe-area-aware): the badge's\n * controller is idempotent, so calling this again (e.g. right before\n * `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in\n * place instead of injecting a duplicate.\n *\n * **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to\n * its caller. Injection failure (e.g. page detached during inject, CSS not\n * supported) is swallowed and logged as `console.debug` — the badge is\n * informational UI and must never block attach success or test execution.\n * This is the same fire-and-forget spirit as the in-page console mount in\n * `src/in-app/attach.ts`.\n *\n * Call this ONLY on the manual debug paths (start_attach MCP, devtools-test\n * CLI). Do NOT call on the `run_tests` auto-attach path — the badge\n * would contaminate screenshots, measure_safe_area probes, and DOM snapshots\n * taken during automated measurement runs.\n *\n * SECRET-HANDLING: the injected expression contains no secrets, relay URLs,\n * wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by\n * {@link buildIndicatorExpression}.\n *\n * @param conn - The live CDP connection (relay-attached page).\n * @param opts - Optional overrides forwarded to {@link buildIndicatorExpression}.\n */\nexport async function injectDebugIndicator(\n  conn: CdpConnection,\n  opts?: { label?: string; disconnectedLabel?: string; state?: 'attached' | 'disconnected' },\n): Promise<void> {\n  try {\n    await conn.send('Runtime.evaluate', {\n      expression: buildIndicatorExpression(opts),\n      returnByValue: true,\n    });\n  } catch (err) {\n    // Badge injection is informational UI — swallow and log; never propagate.\n    console.debug('[@ait-co/devtools] debug indicator inject skipped:', err);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,MAAM,uBAA+C;CACnD,eAAe;CACf,gBAAgB;CAChB,OAAO;CACP,QAAQ;CACR,UAAU;CACV,UAAU;CACX;;AAGD,MAAa,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;AA2B/C,SAAgB,qCAA6C;AAQ3D,QACE,8bARmB,OAAO,QAAQ,qBAAqB,CACtD,KACE,CAAC,KAAK,YACL,cAAc,KAAK,UAAU,IAAI,CAAC,kBAAkB,KAAK,UAAU,OAAO,CAAC,IAC9E,CACA,KAAK,KAAK,CAgBK;;;;;;;;;;;;;;;;;;;;AAyBpB,eAAsB,uBACpB,MACA,YAAY,iCACiC;CAC7C,MAAM,mBAAmB,OAAO,+BAA+B;CAC/D,MAAM,iBAAiB,IAAI,SAAkC,YAC3D,iBAAiB,QAAQ,iBAAiB,EAAE,UAAU,CACvD;AAED,KAAI;EACF,MAAM,cAAc,KAAK,KAAK,oBAAoB;GAChD,YAAY,oCAAoC;GAChD,eAAe;GACf,cAAc;GACf,CAAC;EAEF,MAAM,aAAa,MAAM,QAAQ,KAAK,CACpC,YAAY,MAAM,OAAO;GAAE,KAAK;GAAiB;GAAG,EAAE,EACtD,eAAe,YAAY,EAAE,KAAK,WAAoB,EAAE,CACzD,CAAC;AAEF,MAAI,WAAW,QAAQ,WAAW;AAChC,WAAQ,OAAO,MACb,qDAAqD,UAAU,4CAChE;AACD;;AAGF,MAAI,WAAW,EAAE,kBAAkB;AACjC,WAAQ,OAAO,MACb,kFACD;AACD;;EAGF,MAAM,WAAW,WAAW,EAAE,OAAO;AACrC,MAAI,OAAO,aAAa,SAAU,QAAO,KAAA;EACzC,MAAM,SAAkB,KAAK,MAAM,SAAS;AAC5C,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO,KAAA;AAC1D,SAAO;UACA,GAAG;AACV,UAAQ,OAAO,MACb,6CACE,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAC3C,2CACF;AACD;;;;;;;;;;;;;AAiBJ,eAAsB,cACpB,MACA,SACe;CAIf,MAAM,OAAO,sCAAsC,KAAK,UAAU,QAAQ,CAAC;CAC3E,MAAM,SAAS,MAAM,KAAK,KAAK,oBAAoB;EAAE,YAAY;EAAM,eAAe;EAAM,CAAC;AAC7F,KAAI,OAAO,kBAAkB;EAC3B,MAAM,MACJ,OAAO,iBAAiB,WAAW,eACnC,OAAO,iBAAiB,QACxB;AACF,QAAM,IAAI,MAAM,0CAA0C,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCpE,eAAsB,qBACpB,MACA,MACe;AACf,KAAI;AACF,QAAM,KAAK,KAAK,oBAAoB;GAClC,YAAY,yBAAyB,KAAK;GAC1C,eAAe;GAChB,CAAC;UACK,KAAK;AAEZ,UAAQ,MAAM,sDAAsD,IAAI"}

package/dist/{debug-server-qRSRG7YZ.js → debug-server-CS1BS2BX.js}

@@ -1,8 +1,8 @@
 import { n as buildRelayVerifyAuth, r as generateTotp, t as assertRelayAuthConfigured } from "./totp-DfekTBk3.js";
 import "./test-runner/relay-factory.js";
 import { a as startTunnelHealthProbe, i as startQuickTunnel, n as makeTunnelStatus, o as logError, r as printAttachBanner, s as logInfo, t as generateAttachToken } from "./attach-orchestrator-Cjdhir2U.js";
-import "./cell-Cw4fVOl2.js";
-import "./qr-http-server-cKbciY5k.js";
+import "./cell-D1y4shoV.js";
+import "./qr-http-server-DeRrKp_R.js";
 import "./relay-secret-store-BcVrWwTq.js";
 import { createRequire } from "node:module";
 import "@modelcontextprotocol/sdk/server/index.js";
@@ -590,6 +590,24 @@ OPTIONS
   --headless              Disable browser auto-open (text QR only)
   --project-root <dir>    Project root for .ait_relay secret lookup
                           (default: current working directory)
+  --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
+                          a step-by-step Korean prompt naming the file + its
+                          progress (k/n), and the same line is printed to
+                          stdout. Manual files get a 5-minute per-file evaluate
+                          timeout (vs. --timeout for everything else) since a
+                          human is expected to tap through a native sheet
+                          (photo picker, permission dialog, fullscreen ad).
+                          Without this flag (default off), *.manual.ait.test.ts
+                          files are EXCLUDED from the glob expansion entirely —
+                          existing unattended runs are byte-for-byte unaffected.
+                          With --report-dir, a run that included manual files
+                          ALSO writes <sdkLine>.<platform>.manual.json
+                          alongside (never replacing) the standard report, and
+                          each manual file's report entry is stamped
+                          mode: 'manual' — never diff a manual run against an
+                          unattended baseline as if they were equivalent.
   --help, -h              Show this help message
 
 DESCRIPTION
@@ -980,4 +998,4 @@ async function bootRelayFamily(options = {}) {
 //#endregion
 export { bootRelayFamily, buildRelayVerifyAuth };
 
-//# sourceMappingURL=debug-server-qRSRG7YZ.js.map
+//# sourceMappingURL=debug-server-CS1BS2BX.js.map