@ait-co/debug-console 0.1.1

package/dist/index.js

@@ -0,0 +1,1339 @@
+//#region ../internal-protocol/src/debug-host.ts
+/**
+* Host allowlist predicates — the one part of the activation gate that BOTH
+* sides of the device↔host protocol evaluate.
+*
+* The device evaluates them inside the runtime gate (`@ait-co/debug-console`'s
+* `gate.ts`, Layer B1). The daemon evaluates the same predicate when it decides
+* whether a CDP target's URL is allowed to be driven (`@ait-co/debugger`'s
+* `debug-server.ts`). Before the split those two call sites shared one module
+* by reaching from the daemon into the in-app tree — a reverse edge that would
+* have dragged the browser bundle into the daemon's graph once the two surfaces
+* became separate packages. Extracting the 5 predicates here removes the edge
+* without duplicating the rule.
+*
+* This module is intentionally dependency-free (no Node, no DOM — only
+* `String#endsWith` and one regex) so it inlines into both bundles. There is no
+* barrel index in this package: each consumer imports the one subpath it needs,
+* and its bundler inlines the handful of statements at build time. Nothing here
+* survives as a runtime cross-package import.
+*
+* SECRET-HANDLING: a hostname is an input, never an output. These functions
+* return booleans only — no predicate may grow to log or return the hostname,
+* a relay URL, or a tunnel host.
+*/
+/**
+* The host suffix the Toss app uses to serve dogfood / private mini-apps.
+*
+* A dogfood entry maps to a host such as
+* `example.private-apps.tossmini.com`. A production entry is served from
+* `*.apps.tossmini.com` — the `.private-apps.` segment is absent.
+*/
+const PRIVATE_APPS_HOST_SUFFIX = ".private-apps.tossmini.com";
+/**
+* The parent host suffix for the whole mini-app serving family.
+*
+* The 3.0 runtime loader serves mini-app pages from tossmini.com hosts that are
+* NOT `*.private-apps.tossmini.com`, so under 3.0 the hostname no longer
+* distinguishes a dogfood candidate from a production entry. For those hosts
+* the host layer is demoted from a stage discriminator to a "known host family"
+* filter and the effective boundary moves to the opt-in + relay + TOTP layer.
+*/
+const TOSSMINI_HOST_SUFFIX = ".tossmini.com";
+/**
+* The host suffix Cloudflare quick-tunnels serve from — the env 2 (PWA) entry.
+*/
+const TRYCLOUDFLARE_HOST_SUFFIX = ".trycloudflare.com";
+/**
+* Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —
+* the host reserved for dogfood / private mini-app entries.
+*
+* The match is an exact suffix check, not a substring `.includes()`: a
+* substring test would also accept an attacker-controlled host like
+* `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in
+* `.tossmini.com`. Requiring the string to END with the suffix closes that.
+* The leading `.` in the suffix also forces a real subdomain label, so a bare
+* `private-apps.tossmini.com` (no mini-app subdomain) does not match.
+*/
+function isPrivateAppsHost(hostname) {
+	return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);
+}
+/**
+* Returns whether `hostname` is any `*.tossmini.com` subdomain — the host
+* family mini-app pages are served from. Includes the 2.x
+* `*.private-apps.tossmini.com` dogfood hosts and the 3.0 unified serving
+* hosts.
+*
+* Same exact-suffix `endsWith` check as {@link isPrivateAppsHost} — never a
+* substring `.includes()`, which would accept `x.tossmini.com.evil.example`.
+*/
+function isTossminiHost(hostname) {
+	return hostname.endsWith(TOSSMINI_HOST_SUFFIX);
+}
+/**
+* Returns whether `hostname` is a Cloudflare quick-tunnel host — the env 2
+* (PWA) entry.
+*
+* Env 2 serves the local dev server through a `*.trycloudflare.com` quick
+* tunnel. It has no production runtime: the SDK is the devtools mock and the
+* page is the developer's own dev build. The host safety net (which stops a
+* dogfood build that lands on a production host from attaching) has nothing to
+* protect against here — but the remaining gate layers (opt-in, relay URL,
+* TOTP) still apply, so a leaked tunnel URL is still blocked.
+*
+* Same exact-suffix `endsWith` check as {@link isPrivateAppsHost} — never a
+* substring `.includes()`, which would accept
+* `evil.trycloudflare.com.example.com`.
+*/
+function isTrycloudflareHost(hostname) {
+	return hostname.endsWith(TRYCLOUDFLARE_HOST_SUFFIX);
+}
+/**
+* Returns true when the hostname is a localhost/loopback address.
+* Allowed: `localhost`, `127.x.x.x` (full RFC 5735 loopback block), `[::1]`,
+* `0.0.0.0`, `*.localhost`.
+*
+* Security note: `hostname.startsWith('127.')` is intentionally NOT used —
+* that pattern would accept `127.evil.com`, which starts with "127." but is an
+* attacker-controlled hostname, not a loopback address. Instead, the 127/8
+* loopback block is matched with a strict numeric-quad regex so only valid
+* dotted-decimal IPv4 in the 127.x.x.x range pass.
+*/
+function isLocalhostHost(hostname) {
+	if (hostname === "localhost" || hostname === "0.0.0.0") return true;
+	if (hostname === "[::1]") return true;
+	if (/^127\.\d+\.\d+\.\d+$/.test(hostname)) return true;
+	if (hostname.endsWith(".localhost")) return true;
+	return false;
+}
+/**
+* Positive-allowlist kill-switch: returns true when the hostname is a known
+* debug-allowed host. The debug surface is ONLY active on:
+*   - localhost / loopback (env 1 desktop dev)
+*   - `*.trycloudflare.com` (env 2 PWA tunnel)
+*   - `*.tossmini.com` (env 3 dog-food — 2.x private-apps hosts AND the 3.0
+*     unified serving family)
+*
+* Any other host is silently blocked. Unlisted hosts never had a debug surface
+* regardless, but this function makes it explicit and auditable in one place.
+*
+* The 3.0 loader serves dogfood candidates and production entries from the same
+* host family, so the hostname alone can no longer separate them. The "no naked
+* attach on a production-family host" invariant is preserved one layer down: on
+* tossmini hosts that are not `*.private-apps.*` the TOTP code is mandatory,
+* and production entry URLs carry no debug/relay/at params at all.
+*
+* SECRET-HANDLING: the hostname value MUST NOT be logged or included in any
+* error reason string — only benign labels ('host not in allowlist') are safe.
+*/
+function isDebugAllowedHost(hostname) {
+	return isLocalhostHost(hostname) || isTrycloudflareHost(hostname) || isTossminiHost(hostname);
+}
+//#endregion
+//#region src/gate.ts
+/**
+* Runtime activation gate for the in-app debug surface.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+* "3-layer activation gate". This is the pure gate decision; the Chii client,
+* WebSocket transport, MCP server, and CLI that consume it live in src/mcp/.
+*
+* This function evaluates the two RUNTIME layers, B and C. Layer A — the
+* build-time gate — is NOT evaluated here, and deliberately so: it is enforced
+* entirely by the consumer's `if (__DEBUG_BUILD__) { … }` guard around the
+* import site (see sdk-example `src/main.tsx`). `__DEBUG_BUILD__` is a
+* consumer-build-time constant; a release consumer build folds it to `false`
+* and dead-code-eliminates the whole import of `@ait-co/debug-console`, so
+* this code is simply absent from release bundles. A pre-built npm package
+* cannot re-check that flag — it was already baked at devtools' own publish
+* time — so any `isDebugBuild` check inside this function would be permanently
+* `false` and could never pass. Layer A is the consumer guard; B and C are
+* here.
+*
+* Layer B has two parts:
+*   B1 — host allowlist: `hostname` must be a `*.private-apps.tossmini.com`
+*        subdomain (Toss dogfood entry) OR a `*.trycloudflare.com` host (env 2
+*        PWA dev tunnel). The Toss app serves dogfood / private mini-apps from
+*        a separate `private-apps` host; a production (`intoss://`) entry is
+*        served from `*.apps.tossmini.com` WITHOUT the `private-apps` segment.
+*        This is the security gate against a dogfood build that somehow lands
+*        on a production entry — see the comment on {@link isPrivateAppsHost}.
+*        The env 2 tunnel host is allowed because it has no production runtime
+*        (mock SDK, the developer's own dev server) — see {@link
+*        isTrycloudflareHost}.
+*   B2 — entry query: `_deploymentId` must be present and non-empty. Applies to
+*        the Toss path only; the env 2 tunnel has no deployed bundle, so B2 is
+*        skipped for `*.trycloudflare.com` hosts.
+*
+* Layer C — opt-in + relay + optional TOTP auth:
+*   C1 — opt-in:       `debug=1` must be present.
+*   C2 — relay URL:    `relay=<wss-url>` must be a valid `wss:` URL.
+*   C3 — TOTP auth:    When `verifyTotpCode` is provided (consumer injected the
+*                      baked secret at build time via `__DEBUG_TOTP_SECRET__`),
+*                      `at=<code>` is checked. Invalid or absent code → BLOCKED.
+*                      When no verifier is provided (TOTP disabled), `at` is
+*                      ignored (backward compatible).
+*
+* Security note on baked secrets:
+*   The TOTP secret baked in via `__DEBUG_TOTP_SECRET__` is present in the
+*   dogfood bundle and is extractable by a determined reverse engineer.
+*   The practical bar raised is: "URL leak" (Slack paste, QR screenshot) →
+*   blocked; "URL + bundle extraction + live TOTP code" → not blocked.
+*   This is the intended threat model. Do not overpromise on this guarantee.
+*
+* SECRET-HANDLING: `verifyTotpCode` is a black-box predicate. This module
+*   does NOT log the secret, any code value, or pass/fail details beyond the
+*   `'auth'` reason enum.
+*
+* Decision matrix (gate only runs in a debug build — Layer A already passed):
+*
+*   host        | _deploymentId | debug=1 | relay ok | TOTP ok* | result
+*   neither     | (any)         | (any)   | (any)    | (any)    | BLOCKED (host)
+*   private-apps| absent        | (any)   | (any)    | (any)    | BLOCKED (entry)
+*   private-apps| present       | absent  | (any)    | (any)    | BLOCKED (opt-in)
+*   private-apps| present       | present | invalid  | (any)    | BLOCKED (invalid-relay)
+*   private-apps| present       | present | valid    | fail*    | BLOCKED (auth)
+*   private-apps| present       | present | valid    | pass/n/a | ATTACH
+*   trycloudflare| (skipped)    | absent  | (any)    | (any)    | BLOCKED (opt-in)
+*   trycloudflare| (skipped)    | present | invalid  | (any)    | BLOCKED (invalid-relay)
+*   trycloudflare| (skipped)    | present | valid    | fail*    | BLOCKED (auth)
+*   trycloudflare| (skipped)    | present | valid    | pass/n/a | ATTACH
+*   tossmini(3.0)| (reported)   | absent  | (any)    | (any)    | BLOCKED (opt-in)
+*   tossmini(3.0)| (reported)   | present | invalid  | (any)    | BLOCKED (invalid-relay)
+*   tossmini(3.0)| (reported)   | present | valid    | at absent| BLOCKED (auth — TOTP mandatory, #760)
+*   tossmini(3.0)| (reported)   | present | valid    | pass/at present | ATTACH
+*
+*   * "TOTP ok" column only applies when `verifyTotpCode` is provided.
+*     When no verifier is injected, TOTP check is skipped entirely — EXCEPT
+*     on tossmini(3.0) hosts (non-private-apps), where a missing `at=` code
+*     blocks with 'auth' even without a verifier (devtools#760; the relay
+*     side remains the authoritative verifier).
+*
+*   tossmini(3.0) = `*.tossmini.com` hosts that are not
+*   `*.private-apps.tossmini.com` — the 3.0 unified serving family. The 3.0
+*   loader consumes `_deploymentId` natively, so B2 reports it when present
+*   but never requires it there (devtools#760).
+*   For trycloudflare (env 2 tunnel) hosts B1 is bypassed and B2 is skipped;
+*   C1/C2/C3 still apply identically. The ATTACH result carries
+*   `deploymentId: ''` for tunnel hosts.
+*/
+/**
+* Pure function that evaluates the runtime debug activation layers (B and C).
+*
+* Has no side effects. The input is explicit. Returns a discriminated union
+* so callers can pattern-match on `result.attach`.
+*
+* Layer A (build-time) is intentionally not evaluated here — see the file-level
+* comment. By the time this function runs, the consumer's `if (__DEBUG_BUILD__)`
+* guard has already passed; this function only decides B and C.
+*
+* @example
+* ```ts
+* const result = evaluateDebugGate({
+*   hostname: window.location.hostname,
+*   searchParams: new URLSearchParams(window.location.search),
+* });
+* if (result.attach) {
+*   // Proceed to load Chii client
+* }
+* ```
+*/
+function evaluateDebugGate(input) {
+	const isTunnel = isTrycloudflareHost(input.hostname);
+	const isLocal = isLocalhostHost(input.hostname);
+	if (!isDebugAllowedHost(input.hostname)) return {
+		attach: false,
+		reason: "host"
+	};
+	let deploymentId = "";
+	if (isPrivateAppsHost(input.hostname)) {
+		deploymentId = input.searchParams.get("_deploymentId") ?? "";
+		if (deploymentId === "") return {
+			attach: false,
+			reason: "entry"
+		};
+	} else if (!isTunnel && !isLocal) deploymentId = input.searchParams.get("_deploymentId") ?? "";
+	if (input.searchParams.get("debug") !== "1") return {
+		attach: false,
+		reason: "opt-in"
+	};
+	const relayRaw = input.searchParams.get("relay") ?? "";
+	if (relayRaw === "") return {
+		attach: false,
+		reason: "invalid-relay"
+	};
+	let relayUrl;
+	try {
+		relayUrl = new URL(relayRaw);
+	} catch {
+		return {
+			attach: false,
+			reason: "invalid-relay"
+		};
+	}
+	if (relayUrl.protocol !== "wss:") return {
+		attach: false,
+		reason: "invalid-relay"
+	};
+	const atCode = input.searchParams.get("at") ?? "";
+	if (input.verifyTotpCode !== void 0) {
+		if (!input.verifyTotpCode(atCode)) return {
+			attach: false,
+			reason: "auth"
+		};
+	} else if (isTossminiHost(input.hostname) && !isPrivateAppsHost(input.hostname) && atCode === "") return {
+		attach: false,
+		reason: "auth"
+	};
+	return {
+		attach: true,
+		relayUrl: relayUrl.href,
+		deploymentId
+	};
+}
+//#endregion
+//#region ../internal-protocol/src/attach-handshake.ts
+/**
+* Version handshake carried on the attach path.
+*
+* WHY THIS EXISTS — every other clause of the device↔host contract is a
+* value-duplicated string or number with zero compile-time linkage: the
+* `window.__ait_bridge` snapshot and its field names, the `ait:bridge-call` /
+* `ait:relay-ws-state` event names, the `__ait_relay_ws_observed` flag, the
+* `#__ait_debug_indicator` element id, the `/at/<code>/target.js` path
+* convention, `window.__sdk` / `window.__sdkCall`, and close code 4401. When
+* the two sides drift, none of that crashes — it silently misbehaves. The
+* indicator renders empty, a field reads `undefined`, a close frame goes
+* unrecognised. Nothing in the stack says why.
+*
+* Changesets `fixed` keeps `@ait-co/debugger` and `@ait-co/debug-console` on
+* one version number, so "same version" is exactly "mutually tested pair". What
+* `fixed` cannot do is stop a consumer from installing a skewed pair. This
+* handshake turns that skew from a silent misbehaviour into one diagnostic
+* line: the device reports its build-time `__VERSION__` on a fire-and-forget
+* request just before it injects `target.js`, and the daemon compares it with
+* its own.
+*
+* Why a dedicated request rather than a query param on `target.js`: chii's
+* stock `target.js` derives its WebSocket endpoint from its own script `src`
+* via `src.replace('target.js', '')` and then appends `target/<id>`. Any query
+* string on that URL would land in the middle of the derived endpoint and break
+* the dial. The path is therefore separate, and it rides the same
+* `/at/<code>/` prefix so the relay's existing auth gate covers it unchanged.
+*
+* SECRET-HANDLING: the payload is a version string and nothing else. The
+* request carries a TOTP code only in the same path-prefix form the target
+* script already uses; neither side may log the URL, the code, or the relay
+* host. The mismatch diagnostic names two version strings — never a URL.
+*/
+/**
+* Relay HTTP path the device pings once, immediately before injecting
+* `target.js`. Served by the daemon's relay; the response body is empty.
+*/
+const ATTACH_HANDSHAKE_PATH = "/ait-attach";
+//#endregion
+//#region ../internal-protocol/src/bridge-observer-state.ts
+/**
+* CustomEvent fired (no detail) on every bridge-call start/settle so the
+* indicator badge re-renders promptly. SECRET-HANDLING: carries no detail
+* payload at all — the badge reads the enum-only snapshot on receipt.
+*/
+const BRIDGE_CALL_EVENT = "ait:bridge-call";
+/**
+* CustomEvent fired with `{ detail: { state } }` on every relay-WebSocket
+* open/close, so a CDP-injected indicator can follow relay liveness without
+* installing a second Proxy on `window.WebSocket`. `state` is an enum
+* (`'open' | 'closed'`) — never a URL.
+*/
+const RELAY_WS_STATE_EVENT = "ait:relay-ws-state";
+//#endregion
+//#region ../internal-protocol/src/relay-auth-close.ts
+/**
+* Shared constants for the relay's named TOTP-auth rejection.
+*
+* Before the accept-then-close fix the relay rejected an unauthenticated
+* WebSocket upgrade with a raw `HTTP/1.1 401` + `socket.destroy()`. A handshake
+* aborted that way is indistinguishable from a network failure on the browser
+* side — the WebSocket only ever sees close code 1006, so the phone (env-2
+* launcher PWA) could not tell "stale TOTP code" apart from "tunnel down" and
+* stayed silent. The fix is accept-then-close: complete the handshake, then
+* close with an application close code that NAMES the rejection.
+*
+* Three parties share this contract:
+*   - the relay (`@ait-co/debugger`, Node) sends the close frame / HTTP error body;
+*   - the on-device console (`@ait-co/debug-console`, browser) observes
+*     relay-bound WebSockets and surfaces the code to the launcher shell;
+*   - the daemon's own CDP client (`@ait-co/debugger`, Node) recognises the code
+*     as an auth failure on its `/client` dial.
+*
+* This module is intentionally dependency-free (no Node, no DOM) so it is safe
+* to inline into both the browser bundle and the daemon bundle.
+*
+* SECRET-HANDLING: these are fixed enum values. The close reason / error body
+* must never grow to carry a secret, a TOTP code, or a host.
+*/
+/**
+* WebSocket close code sent by the relay when TOTP auth is rejected.
+*
+* 4000–4999 is the application-reserved range (RFC 6455 §7.4.2); 4401 mirrors
+* HTTP 401 so it reads as "unauthorized" at a glance.
+*/
+const RELAY_AUTH_REJECT_CLOSE_CODE = 4401;
+/**
+* Close reason string accompanying {@link RELAY_AUTH_REJECT_CLOSE_CODE}, and
+* the `error` value of the relay's HTTP 401 JSON body. Enum string only —
+* never interpolated with request data.
+*/
+const RELAY_AUTH_REJECT_REASON = "totp-rejected";
+//#endregion
+//#region src/bridge-observer.ts
+/**
+* In-app native-bridge call observer (issue #749).
+*
+* WHY THIS EXISTS — the mock's `observe()` (`src/mock/observe.ts` → `aitState.
+* sdkCallLog`) only wraps the MOCK SDK. In the on-device debug context (env 3,
+* real Toss WebView, run7) the REAL `@apps-in-toss/web-framework` is loaded, so
+* that groundwork sees nothing. The in-app debug surface needs its own
+* observation point at the one place every real async bridge call funnels
+* through, so the on-phone indicator can answer run7's question: is a spinner a
+* pending native call, the app's own UI, or a wedged JS main thread?
+*
+* OBSERVATION POINTS (version-agnostic — both SDK lines route through one of
+* these; picked so a GA flip 2.x↔3.0 does not break the signal):
+*
+*   - 3.0 line — `window.__appsInTossNativeBridge.callAsyncMethod(name, params)`
+*     is the single async dispatcher; it returns the native Promise. Wrapping
+*     it gives the COMPLETE lifecycle (pending on call, settle on resolve/
+*     reject) from ONE hook, with no reliance on how native calls back.
+*   - 2.x line — there is no single dispatcher method (each async bridge is an
+*     independent `createAsyncBridge` closure). The universal START choke point
+*     is `window.ReactNativeWebView.postMessage(json)`; the matching SETTLE
+*     signal is `window.__GRANITE_NATIVE_EMITTER.emit('<method>/resolve|reject/
+*     <eventId>')`. We wrap both.
+*
+* The observer publishes a read-only snapshot on `window.__ait_bridge` (an
+* id→pending map + a last-call record) and fires a payload-less
+* {@link BRIDGE_CALL_EVENT} CustomEvent on every change, so the CDP-injected
+* indicator badge (`buildIndicatorExpression`) can render the pending list +
+* last-call stamp without polling — the same pub/sub decoupling the relay-WS
+* observer uses for `ait:relay-ws-state` (#730).
+*
+* SECRET-HANDLING: this module records API METHOD NAMES + timestamps + a
+* correlation id ONLY. It NEVER reads, stores, or forwards call arguments
+* (`params`/`args`) or results — those may carry tokens, URLs, or user data.
+* The outbound-message parser reads `type`/`name`/`functionName`/`callbackId`/
+* `eventId` and deliberately never touches `params`/`args`.
+*
+* Lives in the in-app graph (reached only via {@link maybeAttach}); a release
+* consumer build DCEs it with the rest of the debug surface (§check:debug-
+* surface-absent). Never throws into the host app — every hook is guarded.
+*/
+/**
+* Pending entries older than this are pruned on the next start — a safety net
+* for the fallback path where a settle signal might be missed, so the pending
+* list can never grow unbounded or show a forever-stuck row. Generous enough
+* that a genuinely slow native call (the exact signal we want to surface) still
+* shows while it is plausibly in flight.
+*/
+const MAX_PENDING_AGE_MS = 12e4;
+/** Guard so the observer wraps the bridge at most once per page lifecycle. */
+let bridgeObserverInstalled = false;
+/** Monotonic id source for the primary (3.0) path, where native gives us none. */
+let callIdCounter = 0;
+/** Undo hooks that {@link uninstallBridgeObserver} runs to restore originals. */
+let restoreHooks = [];
+/** Drops pending entries older than {@link MAX_PENDING_AGE_MS}. */
+function pruneStale(state, now) {
+	for (const id of Object.keys(state.pending)) {
+		const entry = state.pending[id];
+		if (entry !== void 0 && now - entry.startedAt > MAX_PENDING_AGE_MS) delete state.pending[id];
+	}
+}
+/** Fires the payload-less notify event so the badge re-renders. */
+function broadcast() {
+	if (typeof window === "undefined") return;
+	window.dispatchEvent(new CustomEvent(BRIDGE_CALL_EVENT));
+}
+/** Records a call start: add to pending, set last=pending, notify. */
+function startCall(state, id, method, now) {
+	pruneStale(state, now);
+	state.pending[id] = {
+		method,
+		startedAt: now
+	};
+	state.last = {
+		method,
+		at: now,
+		status: "pending"
+	};
+	broadcast();
+}
+/** Records a call settle: remove from pending, stamp last, notify. */
+function settleCall(state, id, status, now) {
+	const entry = state.pending[id];
+	delete state.pending[id];
+	state.last = {
+		method: entry?.method ?? state.last?.method ?? "unknown",
+		at: now,
+		status
+	};
+	broadcast();
+}
+/**
+* Parses an outbound `ReactNativeWebView.postMessage` JSON envelope and records
+* a START for async request/response calls only. Event subscriptions
+* (`addEventListener`/`removeEventListener`/`callEventMethod`), cleanup, and
+* constants are ignored — they are not the "spinner is a pending call" signal.
+*
+* SECRET-HANDLING: reads `type`/`name`/`functionName`/`callbackId`/`eventId`
+* ONLY — never `params`/`args`.
+*/
+function observeOutbound(state, message) {
+	if (typeof message !== "string") return;
+	let parsed;
+	try {
+		parsed = JSON.parse(message);
+	} catch {
+		return;
+	}
+	const now = Date.now();
+	if (parsed.type === "callAsyncMethod" && typeof parsed.name === "string" && typeof parsed.callbackId === "string") {
+		startCall(state, parsed.callbackId, parsed.name, now);
+		return;
+	}
+	if (parsed.type === "method" && typeof parsed.functionName === "string" && typeof parsed.eventId === "string") startCall(state, parsed.eventId, parsed.functionName, now);
+}
+/**
+* Parses a `__GRANITE_NATIVE_EMITTER.emit` event name and records a SETTLE for
+* 2.x async resolves/rejects (`<method>/resolve/<eventId>` |
+* `<method>/reject/<eventId>`). Event-bridge emits (`.../onEvent/...`) are
+* ignored. SECRET-HANDLING: reads the event NAME only — never the emitted args.
+*/
+function observeSettle(state, event) {
+	if (typeof event !== "string") return;
+	const match = /\/(resolve|reject)\/([^/]+)$/.exec(event);
+	if (match === null) return;
+	settleCall(state, match[2], match[1] === "resolve" ? "resolved" : "rejected", Date.now());
+}
+/**
+* Installs the native-bridge call observer (#749). Idempotent per page
+* lifecycle. Called by {@link maybeAttach} after the gate passes (debug builds
+* only). Prefers the 3.0 single-dispatcher wrap; falls back to the universal
+* 2.x postMessage-start + emitter-settle pair. A context with no observable
+* bridge (env 2 mock) leaves `window.__ait_bridge` as an empty snapshot — the
+* badge then shows the heartbeat only, which is correct.
+*
+* Never throws into the host app — a wrapped hook that somehow fails is caught
+* and the original behavior is always preserved.
+*/
+function installBridgeObserver() {
+	if (bridgeObserverInstalled) return;
+	if (typeof window === "undefined") return;
+	bridgeObserverInstalled = true;
+	const state = {
+		pending: Object.create(null),
+		last: null
+	};
+	window.__ait_bridge = state;
+	const nativeBridge = window.__appsInTossNativeBridge;
+	if (nativeBridge !== void 0 && typeof nativeBridge.callAsyncMethod === "function") {
+		const original = nativeBridge.callAsyncMethod;
+		const wrapped = function(name, params) {
+			const id = `c${++callIdCounter}`;
+			startCall(state, id, String(name), Date.now());
+			let result;
+			try {
+				result = original.call(this, name, params);
+			} catch (err) {
+				settleCall(state, id, "rejected", Date.now());
+				throw err;
+			}
+			if (result !== null && typeof result.then === "function") result.then(() => settleCall(state, id, "resolved", Date.now()), () => settleCall(state, id, "rejected", Date.now()));
+			else settleCall(state, id, "resolved", Date.now());
+			return result;
+		};
+		nativeBridge.callAsyncMethod = wrapped;
+		restoreHooks.push(() => {
+			nativeBridge.callAsyncMethod = original;
+		});
+		return;
+	}
+	const webView = window.ReactNativeWebView;
+	if (webView !== void 0 && typeof webView.postMessage === "function") {
+		const originalPost = webView.postMessage;
+		webView.postMessage = function(message) {
+			try {
+				observeOutbound(state, message);
+			} catch {}
+			originalPost.call(this, message);
+		};
+		restoreHooks.push(() => {
+			webView.postMessage = originalPost;
+		});
+	}
+	const emitter = window.__GRANITE_NATIVE_EMITTER;
+	if (emitter !== void 0 && typeof emitter.emit === "function") {
+		const originalEmit = emitter.emit;
+		emitter.emit = function(event, args) {
+			try {
+				observeSettle(state, event);
+			} catch {}
+			originalEmit.call(this, event, args);
+		};
+		restoreHooks.push(() => {
+			emitter.emit = originalEmit;
+		});
+	}
+}
+/**
+* Restores every wrapped bridge hook and removes `window.__ait_bridge` (#749).
+* Idempotent; safe to call when nothing was installed. Wired into
+* {@link detachDebugSurface} (#748) so no bridge wrap survives a run's end.
+*/
+function uninstallBridgeObserver() {
+	if (!bridgeObserverInstalled) return;
+	bridgeObserverInstalled = false;
+	const hooks = restoreHooks;
+	restoreHooks = [];
+	for (const undo of hooks) try {
+		undo();
+	} catch {}
+	if (typeof window !== "undefined") window.__ait_bridge = void 0;
+}
+//#endregion
+//#region src/eruda-overlay.ts
+/**
+* In-app eruda console overlay for the debug attach flow.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+*
+* This module mounts the eruda in-page console (https://github.com/liriliri/eruda)
+* on the phone screen when a debug session attaches. It is the mobile-only
+* counterpart to the Chii `target.js` injection in {@link attach.ts}: Chii is a
+* REMOTE CDP transport (phone → relay → PC DevTools frontend), whereas eruda is
+* a LOCAL in-page view — a floating button + console/network/DOM/storage panels
+* rendered directly on the phone, with no relay or second device. The two are
+* orthogonal and coexist (eruda opens no WebSocket, mounts into its own
+* `#eruda` shadow host — it cannot collide with the relay WS or the Chii DOM).
+*
+* Build-time absence (the security contract): this module lives in the
+* `@ait-co/debug-console` graph. A consumer wraps its
+* `import('@ait-co/debug-console')` call site in `if (__DEBUG_BUILD__) { … }`;
+* a release build folds that constant to `false` and dead-code-eliminates the
+* whole module — so eruda (and its dynamic `import('eruda')` chunk) is simply
+* absent from release bundles, exactly like the Chii target.js injection. The
+* `import('eruda')` here is a dynamic import precisely so the bundler emits it
+* as a separate chunk that the dead branch never pulls in.
+*
+* Runtime gate: `mountEruda()` is called only from `maybeAttach()` AFTER the
+* full Layer B/C gate has passed (`gateResult.attach === true`) — host
+* allowlist, `debug=1`, relay URL, and TOTP. So eruda inherits the same
+* four-layer defence as the Chii injection, byte-for-byte, with no eruda-
+* specific gate of its own.
+*
+* SECRET-HANDLING: this module reads no secret, TOTP code, relay URL, or host
+* value, and logs none. eruda observes only the page it is mounted on.
+*/
+/** Module-level guard against double mount across repeated `maybeAttach` calls. */
+let erudaMounted = false;
+/**
+* The loaded eruda module, captured on a successful {@link mountEruda} so
+* {@link unmountEruda} can call `.destroy()` on the same instance during
+* graceful detach (#748). `null` when eruda was never mounted.
+*/
+let erudaModule = null;
+/**
+* Mounts the eruda in-page console once.
+*
+* Idempotent: repeated calls after a successful mount are no-ops, mirroring the
+* `attached` guard in {@link attach.ts}. Fail-silent: if the dynamic import or
+* `eruda.init()` throws (eruda absent, or a runtime that rejects it), the Chii
+* debug session is unaffected — eruda is an additive convenience, not a
+* dependency of the relay path.
+*
+* `eruda.init()` mounts eruda's own floating entry button on the phone screen;
+* tapping it opens the console. We do not add a separate button.
+*/
+async function mountEruda() {
+	if (erudaMounted || typeof document === "undefined") return;
+	erudaMounted = true;
+	try {
+		const eruda = (await import("eruda")).default;
+		eruda.init();
+		erudaModule = eruda;
+	} catch (err) {
+		erudaMounted = false;
+		console.debug("[@ait-co/debug-console] eruda console mount skipped:", err);
+	}
+}
+/**
+* Unmounts the eruda in-page console (#748 graceful detach).
+*
+* Calls `eruda.destroy()`, which removes eruda's floating entry button, any
+* open panel, and its `#eruda` shadow host — returning the phone screen to a
+* clean, non-debug state when a debug session ends. After a successful unmount
+* the guard is reset so a later {@link mountEruda} (a fresh attach) can
+* re-mount.
+*
+* Idempotent: a call when eruda was never mounted (or already unmounted) is a
+* no-op. Fail-silent: a `destroy()` throw is swallowed — teardown must never
+* throw into the host app.
+*/
+function unmountEruda() {
+	if (!erudaMounted || erudaModule === null) return;
+	try {
+		erudaModule.destroy();
+	} catch (err) {
+		console.debug("[@ait-co/debug-console] eruda console unmount skipped:", err);
+	} finally {
+		erudaMounted = false;
+		erudaModule = null;
+	}
+}
+//#endregion
+//#region src/sdk-probe.ts
+/**
+* Runtime probe for the optional Apps in Toss SDK.
+*
+* WHY A PROBE AND NOT AN IMPORT — this package is the only one in the split
+* that can end up inside a consumer's production bundle, and it ships with
+* `eruda` as its single dependency and no peer dependencies at all. A static
+* `import { setScreenAwakeMode } from '@apps-in-toss/web-framework'` would undo
+* both properties at once: it forces the SDK into the module graph of every
+* consumer that reaches this file, and it pins the package to whichever SDK
+* major exports that symbol. `setScreenAwakeMode` is not part of
+* `@apps-in-toss/web-framework` 2.x's web surface at all — it arrives in the
+* 3.0 line — so a static import does not merely couple us to a version, it
+* breaks 2.x consumers outright.
+*
+* The probe keeps the dependency edge at runtime, where it can be absent
+* without consequence: `import()` inside a `try`, a `typeof === 'function'`
+* check on the export we actually want, and silence when either step fails. The
+* SDK is a devDependency here purely so `tsc` and the unit tests can resolve the
+* specifier; the bundle marks it external so it is never inlined. That makes a
+* 2.x↔3.x GA flip a no-op for this package — the same shape `@ait-co/polyfill`'s
+* `loadTossSdk()` uses.
+*
+* SECRET-HANDLING: nothing here reads or logs a relay URL, a tunnel host, or an
+* auth code. Failures are swallowed; the only thing ever printed is a package-
+* prefixed debug line naming the API that was unavailable.
+*/
+/**
+* Resolved SDK namespace, `null` once a probe has established the SDK is
+* absent, `undefined` while no probe has run yet. Module-scoped, so a
+* `vi.resetModules()` in a test gives a fresh probe.
+*/
+let sdkCache;
+/**
+* Loads the SDK module if the consumer has it installed, else `null`.
+*
+* Never throws and never rejects. The return type is deliberately a bare
+* property bag rather than `typeof import('@apps-in-toss/web-framework')`:
+* callers must feature-sniff the export they need, which is what keeps this
+* file compiling — and behaving — identically against 2.x and 3.x type
+* surfaces.
+*/
+async function loadTossSdk() {
+	if (sdkCache !== void 0) return sdkCache;
+	try {
+		sdkCache = await import("@apps-in-toss/web-framework");
+	} catch {
+		sdkCache = null;
+	}
+	return sdkCache;
+}
+/**
+* The SDK namespace if a previous {@link loadTossSdk} already resolved it, else
+* `null`. Never starts a probe of its own.
+*
+* This exists for the unload path. `pagehide` / `beforeunload` handlers are
+* expected to do their work synchronously — a browser tearing the page down is
+* under no obligation to drain the microtask queue first, so a teardown that
+* begins with `await import(...)` can simply never reach its own body and leave
+* the screen held awake. After a successful attach the cache is warm (the same
+* probe already ran to hold the screen), so the release can be dispatched
+* immediately instead.
+*/
+function getLoadedTossSdk() {
+	return sdkCache ?? null;
+}
+/**
+* Reads a callable export off the SDK namespace, or `null` when it is absent or
+* is not a function. May throw only if the namespace itself is hostile — every
+* caller therefore keeps this inside its own `try`.
+*/
+function pickExport(sdk, name) {
+	const value = sdk[name];
+	return typeof value === "function" ? value : null;
+}
+/**
+* Calls an SDK export by name when it exists, otherwise resolves quietly.
+*
+* @param name - Export to look up on the SDK namespace.
+* @param args - Arguments forwarded verbatim to the export.
+* @returns `true` when the call was dispatched and settled without throwing,
+*   `false` when the SDK or the export was unavailable or the call rejected.
+*/
+async function callTossSdk(name, ...args) {
+	const sdk = await loadTossSdk();
+	if (sdk === null) return false;
+	try {
+		const fn = pickExport(sdk, name);
+		if (fn === null) return false;
+		await fn(...args);
+		return true;
+	} catch (err) {
+		console.debug(`[@ait-co/debug-console] ${name} failed:`, err);
+		return false;
+	}
+}
+/**
+* Dispatches an SDK call in the current tick, using only an already-warm cache.
+*
+* Returns `false` without doing anything when no probe has resolved yet — the
+* caller is expected to fall back to {@link callTossSdk}. Unlike that function,
+* `true` here means only "dispatched": a returned promise is left to settle on
+* its own, because the whole point is not to await inside an unload handler.
+*
+* @param name - Export to look up on the SDK namespace.
+* @param args - Arguments forwarded verbatim to the export.
+*/
+function callTossSdkNow(name, ...args) {
+	const sdk = getLoadedTossSdk();
+	if (sdk === null) return false;
+	try {
+		const fn = pickExport(sdk, name);
+		if (fn === null) return false;
+		const result = fn(...args);
+		if (result instanceof Promise) result.catch((err) => {
+			console.debug(`[@ait-co/debug-console] ${name} failed:`, err);
+		});
+		return true;
+	} catch (err) {
+		console.debug(`[@ait-co/debug-console] ${name} failed:`, err);
+		return false;
+	}
+}
+/**
+* Keeps the phone screen awake for the duration of a debug session (or releases
+* it again). No-op when the SDK is absent or does not expose the API.
+*
+* SECRET-HANDLING: only flips a boolean flag — reads nothing from the relay URL
+* or the auth code.
+*
+* @param enabled - `true` to hold the screen awake, `false` to restore normal
+*   sleep behaviour.
+*/
+async function setScreenAwake(enabled) {
+	return callTossSdk("setScreenAwakeMode", { enabled });
+}
+/**
+* Same as {@link setScreenAwake}, but dispatched in the current tick from an
+* already-warm cache; `false` means nothing was dispatched and the caller
+* should fall back to the async form. Used by the teardown path — see
+* {@link getLoadedTossSdk} for why an unload handler cannot await.
+*
+* @param enabled - `true` to hold the screen awake, `false` to restore normal
+*   sleep behaviour.
+*/
+function setScreenAwakeNow(enabled) {
+	return callTossSdkNow("setScreenAwakeMode", { enabled });
+}
+//#endregion
+//#region src/attach.ts
+/**
+* In-app Chii target injection for the debug attach flow.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+* "MCP attach" topology section — Phase 1 browser-side implementation.
+*
+* This module bridges the 3-layer gate result to a Chii `target.js` script
+* injection. The Chii npm package is the relay SERVER — the in-app side is
+* a plain `<script src="…/target.js">` pointing at the relay host. No chii
+* npm dependency is needed here.
+*/
+/**
+* Converts a validated `wss:` relay URL into the Chii `target.js` script URL.
+*
+* Scheme is mapped `wss:` → `https:`. Host and port are preserved.
+* Pathname is set to `/target.js` (or `/at/<code>/target.js` when a TOTP code
+* is given) regardless of the relay path. Query params and hash from the
+* relay URL are dropped — the target script URL is a static asset path on the
+* same host.
+*
+* TOTP path-prefix transport (issue #466): chii's stock `target.js` derives
+* its WS endpoint from the script `src` (`scriptEl.src.replace('target.js',
+* '')`), so embedding the current TOTP code in the script URL *path* is the
+* only way the phone-side WS upgrade can carry it — both the script fetch and
+* the derived `wss://<host>/at/<code>/target/<id>` dial inherit the prefix,
+* and the relay verifies + strips it before chii parses the URL. The
+* `window.ChiiServerUrl` + query alternative does NOT work: chii appends
+* `target/<id>` to the serverUrl string, which would land after a `?`.
+*
+* SECRET-HANDLING: `atCode` rides only inside the returned URL (the intended
+* transport — same exposure grade as the daemon client's `at=` query). It is
+* never logged here.
+*
+* @example
+* deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
+* // → 'https://abc.trycloudflare.com/target.js'
+*
+* deriveTargetScriptUrl('wss://h.example.com:9100/', '123456')
+* // → 'https://h.example.com:9100/at/123456/target.js'
+*
+* @param relayUrl - Validated `wss:` relay URL from the gate result.
+* @param atCode - Current TOTP code from the page URL's `at` query param, or
+*   `null`/`undefined`/`''` to keep the legacy un-prefixed URL.
+*/
+function deriveTargetScriptUrl(relayUrl, atCode) {
+	const u = new URL(relayUrl);
+	u.protocol = "https:";
+	u.pathname = atCode !== void 0 && atCode !== null && atCode !== "" ? `/at/${encodeURIComponent(atCode)}/target.js` : "/target.js";
+	u.search = "";
+	u.hash = "";
+	return u.toString();
+}
+/**
+* Converts a validated `wss:` relay URL into the version-handshake URL.
+*
+* Same scheme/host/TOTP-prefix derivation as {@link deriveTargetScriptUrl},
+* with this package's build-time `__VERSION__` as the single query value. The
+* handshake gets its own path rather than a query on `target.js` because chii's
+* stock `target.js` derives its WebSocket endpoint from its own script `src`
+* (`src.replace('target.js', '')`) and then appends `target/<id>` — a query
+* string there would land in the middle of the derived endpoint.
+*
+* SECRET-HANDLING: `atCode` rides only inside the returned URL (the same
+* transport the target script already uses) and is never logged.
+*
+* @param relayUrl - Validated `wss:` relay URL from the gate result.
+* @param atCode - Current TOTP code from the page URL's `at` query param, or
+*   `null`/`undefined`/`''` for the un-prefixed form.
+*/
+function deriveHandshakeUrl(relayUrl, atCode) {
+	const u = new URL(relayUrl);
+	u.protocol = "https:";
+	u.pathname = atCode !== void 0 && atCode !== null && atCode !== "" ? `/at/${encodeURIComponent(atCode)}${ATTACH_HANDSHAKE_PATH}` : ATTACH_HANDSHAKE_PATH;
+	u.search = `?v=${encodeURIComponent("0.1.1")}`;
+	u.hash = "";
+	return u.toString();
+}
+/**
+* Reports this package's build-time version to the relay, fire-and-forget.
+*
+* Runs just before `target.js` is injected. Deliberately unawaited and
+* fail-silent: a device↔host version skew is worth a diagnostic on the daemon
+* side, never a reason to hold up or abort an attach. `mode: 'no-cors'` because
+* the relay origin differs from the page origin and we have no use for the
+* response — the daemon is the only party that acts on this.
+*
+* SECRET-HANDLING: the URL (which carries the TOTP code in its path prefix) is
+* never logged, not even on failure.
+*/
+function reportProtocolVersion(relayUrl, atCode) {
+	if (typeof fetch !== "function") return;
+	try {
+		fetch(deriveHandshakeUrl(relayUrl, atCode), {
+			method: "GET",
+			mode: "no-cors",
+			cache: "no-store",
+			keepalive: true
+		}).catch(() => {});
+	} catch {}
+}
+/** Module-level guard against double-injection within a page lifecycle. */
+let attached = false;
+/** One-shot guard for the parent notification (both observer + onerror probe). */
+let authExpiredNotified = false;
+/** Set once a relay-bound socket closed with 4401 — flips dials to fail-fast. */
+let relayAuthExpired = false;
+/** Guard against stacking multiple observer wrappers on window.WebSocket. */
+let wsObserverInstalled = false;
+/**
+* Broadcasts relay-socket lifecycle to any in-page listener (#730) — the
+* on-phone debug indicator subscribes to this instead of wrapping
+* `window.WebSocket` a second time.
+*
+* SECRET-HANDLING: the CustomEvent `detail` carries ONLY the enum
+* `'open' | 'close'` — never a close code, host, relay URL, or TOTP value.
+*/
+function broadcastRelayWsState(state) {
+	if (typeof window === "undefined") return;
+	window.dispatchEvent(new CustomEvent(RELAY_WS_STATE_EVENT, { detail: { state } }));
+}
+/**
+* Posts the `auth-expired` block signal to the parent launcher shell, once.
+*
+* Mirrors the existing `reason: 'auth'` postMessage in {@link maybeAttach}.
+* SECRET-HANDLING: the payload carries ONLY the reason enum — never the code,
+* secret, host, or relay URL.
+*/
+function notifyAuthExpired() {
+	if (authExpiredNotified) return;
+	if (typeof window === "undefined" || window.parent === window) return;
+	authExpiredNotified = true;
+	window.parent.postMessage({
+		type: "ait:debug-attach-blocked",
+		reason: "auth-expired"
+	}, "*");
+}
+/**
+* Normalises a URL into a comparable origin key, mapping the HTTP scheme pair
+* onto the WS pair (`https:`→`wss:`, `http:`→`ws:`) so the `wss:` relay URL
+* from the gate result matches the dials target.js derives from its
+* `https://…/target.js` script src. Returns `null` for unparsable URLs.
+*/
+function wsOriginKey(rawUrl) {
+	let parsed;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		return null;
+	}
+	return `${parsed.protocol === "https:" ? "wss:" : parsed.protocol === "http:" ? "ws:" : parsed.protocol}//${parsed.host}`;
+}
+/**
+* Builds a dummy WebSocket that never connects and closes immediately
+* (asynchronously, with the 4401 code) — returned for relay-bound dials after
+* auth expiry so chii's internal reconnect loop stops producing real network
+* traffic. We cannot stop the loop itself (it lives inside stock target.js);
+* we can only make each iteration free.
+*
+* Both `onclose`-style property handlers and `addEventListener` listeners are
+* fired — stock target.js uses property handlers, but we cannot know every
+* consumer. (A consumer wiring BOTH would see a double callback; acceptable
+* for a retry scheduler and irrelevant for chii.)
+*/
+function createFailFastSocket(url) {
+	const eventTarget = new EventTarget();
+	const sock = {
+		url,
+		readyState: 3,
+		bufferedAmount: 0,
+		extensions: "",
+		protocol: "",
+		binaryType: "blob",
+		onopen: null,
+		onmessage: null,
+		onerror: null,
+		onclose: null,
+		close() {},
+		send() {},
+		addEventListener: eventTarget.addEventListener.bind(eventTarget),
+		removeEventListener: eventTarget.removeEventListener.bind(eventTarget),
+		dispatchEvent: eventTarget.dispatchEvent.bind(eventTarget),
+		CONNECTING: 0,
+		OPEN: 1,
+		CLOSING: 2,
+		CLOSED: 3
+	};
+	setTimeout(() => {
+		const errorEvent = new Event("error");
+		sock.onerror?.(errorEvent);
+		eventTarget.dispatchEvent(errorEvent);
+		let closeEvent;
+		try {
+			closeEvent = new CloseEvent("close", {
+				code: RELAY_AUTH_REJECT_CLOSE_CODE,
+				reason: RELAY_AUTH_REJECT_REASON,
+				wasClean: false
+			});
+		} catch {
+			closeEvent = Object.assign(new Event("close"), {
+				code: RELAY_AUTH_REJECT_CLOSE_CODE,
+				reason: RELAY_AUTH_REJECT_REASON,
+				wasClean: false
+			});
+		}
+		sock.onclose?.(closeEvent);
+		eventTarget.dispatchEvent(closeEvent);
+	}, 0);
+	return sock;
+}
+/** Grace window before a non-terminal relay close tears the surface down. */
+const RECONNECT_GRACE_MS = 5e3;
+/** One-shot guard so the teardown runs at most once per page lifecycle. */
+let debugSurfaceDetached = false;
+/** Pending grace-window timer for a non-terminal close, or `null`. */
+let pendingDetachTimer = null;
+/** Cancels a scheduled teardown — called when a relay socket re-opens. */
+function cancelScheduledDetach() {
+	if (pendingDetachTimer !== null) {
+		clearTimeout(pendingDetachTimer);
+		pendingDetachTimer = null;
+	}
+}
+/**
+* Schedules {@link detachDebugSurface} after {@link RECONNECT_GRACE_MS} unless
+* a reconnect cancels it first. No-op if teardown already ran or is already
+* scheduled. Defensive: if `setTimeout` is somehow unavailable, tears down
+* immediately rather than never.
+*/
+function scheduleDetach() {
+	if (debugSurfaceDetached || pendingDetachTimer !== null) return;
+	if (typeof setTimeout === "undefined") {
+		detachDebugSurface();
+		return;
+	}
+	pendingDetachTimer = setTimeout(() => {
+		pendingDetachTimer = null;
+		detachDebugSurface();
+	}, RECONNECT_GRACE_MS);
+}
+/**
+* Idempotent, non-throwing teardown of the in-app debug surface (issue #748).
+*
+* Removes every debug-surface element WE injected and restores the one side
+* effect WE applied:
+*   1. The CDP-injected `#__ait_debug_indicator` badge (the persistent
+*      "Debugger Disconnected" element). Its live heartbeat/pending-call timer
+*      (#749) is stopped first via the badge controller's `stop()` so no 1 Hz
+*      interval leaks past detach; `buildIndicatorExpression` also
+*      self-dismisses the node — this is the in-app hard guarantee, idempotent,
+*      a no-op if it is already gone.
+*   2. The eruda in-page console (floating button + any open panel).
+*   3. The native-bridge call observer (#749) — its `callAsyncMethod` /
+*      `postMessage` / emitter wraps are restored and `window.__ait_bridge` is
+*      removed, so nothing we wrapped survives the run's end.
+*   4. keepAwake — forced on at attach; restored here so a run that ends
+*      WITHOUT a page unload does not leave the screen pinned awake (the
+*      existing `beforeunload` restore only covers the unload path).
+*
+* Deliberately NOT touched: the `window.WebSocket` observer proxy (kept so the
+* #478 post-4401 fail-fast survives; it is non-blocking and never absorbs
+* input), and any NATIVE overlay (out of our layer — see the block comment
+* above and issue #748 hypothesis (a)).
+*
+* Never throws into the host app — every step is individually guarded.
+* Exported for unit tests and for a consumer that wants to force a clean detach.
+*/
+function detachDebugSurface() {
+	if (debugSurfaceDetached) return;
+	debugSurfaceDetached = true;
+	cancelScheduledDetach();
+	try {
+		if (typeof window !== "undefined") window.__ait_indicator?.stop?.();
+		if (typeof document !== "undefined") document.getElementById("__ait_debug_indicator")?.remove();
+	} catch {}
+	try {
+		unmountEruda();
+	} catch {}
+	try {
+		uninstallBridgeObserver();
+	} catch {}
+	try {
+		if (!setScreenAwakeNow(false)) setScreenAwake(false);
+	} catch {}
+}
+/**
+* Wraps `window.WebSocket` with a relay-origin-scoped observer (issue #478).
+*
+* - Connections whose URL origin does NOT match the relay origin pass through
+*   to the native constructor untouched — app traffic is never observed.
+* - Relay-origin connections get a `close` listener: code 4401 (the relay's
+*   named TOTP rejection) flips the module into the expired state and posts
+*   `reason: 'auth-expired'` to the parent launcher shell (once).
+* - After 4401, further relay-origin dials return a fail-fast dummy socket so
+*   target.js's autonomous reconnect loop stops hitting the network.
+*
+* Installed by {@link maybeAttach} BEFORE target.js is injected so the very
+* first dial is already observed. Idempotent per page lifecycle. Exported for
+* unit tests.
+*/
+function installRelayWsObserver(relayUrl) {
+	if (wsObserverInstalled) return;
+	if (typeof window === "undefined" || typeof window.WebSocket !== "function") return;
+	const relayKey = wsOriginKey(relayUrl);
+	if (relayKey === null) return;
+	wsObserverInstalled = true;
+	window.__ait_relay_ws_observed = true;
+	window.addEventListener("pagehide", () => detachDebugSurface(), { once: true });
+	const NativeWebSocket = window.WebSocket;
+	const observed = new Proxy(NativeWebSocket, { construct(target, args) {
+		const url = String(args[0]);
+		if (wsOriginKey(url) !== relayKey) return Reflect.construct(target, args);
+		if (relayAuthExpired) return createFailFastSocket(url);
+		const ws = Reflect.construct(target, args);
+		ws.addEventListener("open", () => {
+			broadcastRelayWsState("open");
+			cancelScheduledDetach();
+		});
+		ws.addEventListener("close", (event) => {
+			broadcastRelayWsState("close");
+			if (event.code === 4401) {
+				relayAuthExpired = true;
+				notifyAuthExpired();
+				detachDebugSurface();
+			} else scheduleDetach();
+		});
+		ws.addEventListener("error", () => {
+			scheduleDetach();
+		});
+		return ws;
+	} });
+	window.WebSocket = observed;
+}
+/**
+* The webViewType self-report postMessage type (#580).
+*
+* Canonical definition + the receive-side parser live in
+* `src/mock/safe-area-bridge.ts` (`WEB_VIEW_TYPE_MESSAGE_TYPE`,
+* `parseWebViewTypeMessage`). It is re-declared here as a local literal so the
+* in-app entry does NOT import the mock barrel (which would drag mock internals
+* — navigation/state — into the dogfood in-app graph). The two literals are
+* kept in sync by value; if one changes, change both. Same decoupling pattern
+* the launcher fixture uses for its message-type constants.
+*/
+const WEB_VIEW_TYPE_MESSAGE_TYPE = "ait:web-view-type";
+/** Guard so the webViewType self-report is posted at most once per page. */
+let webViewTypeReported = false;
+/**
+* Self-report the mini-app's webViewType to the parent launcher shell, ONCE
+* (#580).
+*
+* The mini-app's type is the build constant `__WEB_VIEW_TYPE__`, injected by
+* the devtools unplugin from `granite.config.ts`'s `webViewProps.type`. The
+* launcher (env-2 PWA) is cross-origin and cannot read it directly, so the
+* framed page posts it to `window.parent`; the launcher switches to game mode
+* automatically (no manual `?navBarType=game` URL edit).
+*
+* Defensive by construction — must NEVER break attach:
+*  - `__WEB_VIEW_TYPE__` is a CONSUMER-build define; it does not exist in
+*    devtools' own build or where the unplugin did not inject it. The `typeof`
+*    guard avoids a ReferenceError; an absent constant is a silent no-op.
+*  - Only posts when inside an iframe (`window.parent !== window`) — a
+*    top-level load has no launcher shell to receive the message.
+*  - The SDK's deprecated `'external'` alias of `partner` (web-framework 2.6.1)
+*    is mapped to `'partner'`; the launcher only emulates `partner` | `game`.
+*  - Wrapped in try/catch so any postMessage/iframe edge case is swallowed.
+*
+* SECRET-HANDLING: the payload carries ONLY the webViewType enum — no host,
+* relay URL, code, or secret.
+*/
+function reportWebViewType() {
+	if (webViewTypeReported) return;
+	try {
+		if (typeof window === "undefined" || window.parent === window) return;
+		const raw = typeof __WEB_VIEW_TYPE__ !== "undefined" ? __WEB_VIEW_TYPE__ : void 0;
+		if (raw === void 0) return;
+		const value = raw === "game" ? "game" : raw === "partner" || raw === "external" ? "partner" : null;
+		if (value === null) return;
+		webViewTypeReported = true;
+		window.parent.postMessage({
+			type: WEB_VIEW_TYPE_MESSAGE_TYPE,
+			value
+		}, "*");
+	} catch {}
+}
+/**
+* Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii
+* `target.js` script into `document.head`.
+*
+* Idempotent — calling more than once is safe. The second call is a no-op if
+* a script with the same `src` is already present in the document, and the
+* module-level `attached` flag prevents redundant DOM queries after the first
+* successful injection.
+*
+* Safe to call even if `document` is somehow unavailable (defensive boundary
+* guard — in practice this always runs in a real WebView).
+*
+* **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({
+* enabled: true })` is called so the phone screen stays awake during the debug
+* session. A `beforeunload` handler restores normal sleep on page unload.
+* Opt out by adding `noKeepAwake=1` to the page URL query string — the check
+* reads `window.location.search` directly, consistent with other guards in
+* this file.
+*
+* @param gateResult - Optional pre-evaluated gate result for testability.
+*   Defaults to `checkDebugGate()` which reads the current page URL. Passing a
+*   custom value avoids the need to manipulate `window.location` in tests.
+*/
+function maybeAttach(gateResult = checkDebugGate()) {
+	reportWebViewType();
+	if (!gateResult.attach) {
+		console.debug(`[@ait-co/debug-console] debug attach skipped — gate blocked (reason: ${gateResult.reason})`);
+		if (gateResult.reason === "auth" && typeof window !== "undefined" && window.parent !== window) window.parent.postMessage({
+			type: "ait:debug-attach-blocked",
+			reason: "auth"
+		}, "*");
+		return;
+	}
+	if (attached) return;
+	if (typeof document === "undefined") return;
+	const atCode = typeof window !== "undefined" ? new URLSearchParams(window.location.search).get("at") : null;
+	const src = deriveTargetScriptUrl(gateResult.relayUrl, atCode);
+	reportProtocolVersion(gateResult.relayUrl, atCode);
+	installRelayWsObserver(gateResult.relayUrl);
+	installBridgeObserver();
+	if (document.querySelector(`script[src="${src}"]`) !== null) {
+		attached = true;
+		return;
+	}
+	const script = document.createElement("script");
+	script.src = src;
+	script.async = true;
+	script.onerror = () => {
+		fetch(src).then((res) => {
+			if (res.status === 401) notifyAuthExpired();
+		}).catch(() => {});
+	};
+	(document.head ?? document.documentElement).appendChild(script);
+	attached = true;
+	mountEruda();
+	if (typeof window !== "undefined" && new URLSearchParams(window.location.search).get("noKeepAwake") === "1") return;
+	setScreenAwake(true).then((held) => {
+		if (!held) return;
+		window.addEventListener("beforeunload", () => {
+			if (!setScreenAwakeNow(false)) setScreenAwake(false);
+		}, { once: true });
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* @ait-co/debug-console entry point.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+*
+* Phase 1 — gate + browser-side Chii target injection.
+* WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that
+* require real-device validation and are not included here.
+*
+* This thin entry reads `window.location` and calls the pure
+* {@link evaluateDebugGate} function. All testable logic lives in `./gate.ts`
+* and `./attach.ts`, not here.
+*
+* Layer A of the activation gate (build-time) is NOT enforced in this module.
+* It is the consumer's responsibility: the consumer wraps its
+* `import('@ait-co/debug-console')` call site in `if (__DEBUG_BUILD__) { … }`
+* (see sdk-example `src/main.tsx`), where `__DEBUG_BUILD__` is a
+* consumer-build-time constant. A release consumer build folds that constant
+* to `false` and dead-code-eliminates this whole module. This package is
+* pre-built and ships with `__DEBUG_BUILD__` already resolved at devtools'
+* publish time, so it could never re-evaluate the consumer's build channel —
+* which is exactly why Layer A lives at the consumer guard, not here.
+*/
+/**
+* Evaluates the runtime debug activation layers (B and C) against the current
+* page URL.
+*
+* Returns the gate result. Callers can check `result.attach` to decide whether
+* to proceed with debug surface attachment.
+*
+* This function reads `window.location` only — both the hostname (Layer B1
+* host allowlist) and the search params (Layers B2 and C). Layer A
+* (build-time) is enforced by the consumer's `if (__DEBUG_BUILD__)` guard
+* around the import site, not here — see the file-level comment. Consumers
+* call this with no arguments, so the Layer B1 host check is picked up with
+* no change at the call site.
+*/
+function checkDebugGate() {
+	return evaluateDebugGate({
+		hostname: window.location.hostname,
+		searchParams: new URLSearchParams(window.location.search)
+	});
+}
+//#endregion
+export { BRIDGE_CALL_EVENT, checkDebugGate, deriveTargetScriptUrl, detachDebugSurface, evaluateDebugGate, installBridgeObserver, isPrivateAppsHost, isTossminiHost, isTrycloudflareHost, maybeAttach, mountEruda, reportWebViewType, uninstallBridgeObserver, unmountEruda };
+
+//# sourceMappingURL=index.js.map