@ait-co/devtools 0.1.144 → 0.2.0

package/dist/in-app/index.d.ts

@@ -1,554 +1,45 @@
-//#region src/in-app/gate.d.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/devtools/in-app`, 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.
- */
-/** Shape returned when the gate allows attachment. */
-interface GateResultAttach {
-  readonly attach: true;
-  /** The validated `wss:` relay URL from the `relay` query param. */
-  readonly relayUrl: string;
-  /** The deployment ID extracted from the `_deploymentId` query param. */
-  readonly deploymentId: string;
-}
-/** Shape returned when the gate blocks attachment, with a reason code. */
-interface GateResultBlocked {
-  readonly attach: false;
-  /**
-   * - `'host'`          Layer B1: `hostname` is not a `*.private-apps.tossmini.com` host.
-   * - `'entry'`         Layer B2: `_deploymentId` param is absent or empty.
-   * - `'opt-in'`        Layer C1: `debug=1` param is absent.
-   * - `'invalid-relay'` Layer C2: `relay` param is absent, empty, or not a `wss:` URL.
-   * - `'auth'`          Layer C3: TOTP `at=` code is absent, invalid, or expired
-   *                     (only when a `verifyTotpCode` predicate is injected).
-   *
-   * There is no `'build'` reason: Layer A is enforced by the consumer's
-   * `if (__DEBUG_BUILD__)` guard, not by this function.
-   *
-   * SECRET-HANDLING: `'auth'` is the only value surfaced for auth failures —
-   * no code value, expected value, or secret fragment is ever exposed.
-   */
-  readonly reason: 'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth';
-}
-type GateResult = GateResultAttach | GateResultBlocked;
-/**
- * Input for {@link evaluateDebugGate}.
- *
- * All fields are explicit so the function is trivially testable without
- * touching `window`.
- */
-interface GateInput {
-  /**
-   * The host the page is served from — `window.location.hostname`.
-   *
-   * This is the Layer B1 security signal. Why hostname and not the entry
-   * scheme: the Toss SDK normalises `intoss-private://` to `intoss://` in
-   * `getSchemeUri()`, and `getOperationalEnvironment()` / `getWebViewType()`
-   * return the same value (`"toss"` / `"partner"`) for both dogfood and
-   * production entries — none of them distinguish a dogfood entry. The host
-   * does: a dogfood / private-apps entry is served from
-   * `*.private-apps.tossmini.com`, a production entry is not. This was
-   * confirmed live over CDP against mini-app 31146 (see spec open question 2).
-   */
-  readonly hostname: string;
-  /**
-   * The URL search params to inspect for gate signals (Layers B2 and C).
-   *
-   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`
-   * without coupling the pure function to `window`.
-   */
-  readonly searchParams: URLSearchParams;
-  /**
-   * Optional TOTP code verifier for Layer C3 auth gate.
-   *
-   * When provided, `evaluateDebugGate` reads the `at` query param and passes
-   * it to this predicate. Return `true` to allow, `false` to block with
-   * `reason: 'auth'`.
-   *
-   * Inject via the consumer's build define, e.g.:
-   * ```ts
-   * // dogfood build entry — consumer's build injects __DEBUG_TOTP_SECRET__
-   * declare const __DEBUG_TOTP_SECRET__: string | undefined;
-   * const verifyTotpCode = typeof __DEBUG_TOTP_SECRET__ !== 'undefined'
-   *   ? (code: string) => verifyTotp(__DEBUG_TOTP_SECRET__, code)
-   *   : undefined;
-   * maybeAttach(evaluateDebugGate({ ...params, verifyTotpCode }));
-   * ```
-   *
-   * Security note: this predicate is a black-box from the gate's perspective.
-   * The gate only surfaces pass/fail and the `'auth'` reason code — no code
-   * value or secret fragment is ever logged or returned.
-   *
-   * When `undefined` (TOTP disabled), `at=` is silently ignored and the gate
-   * proceeds to ATTACH if all other layers pass.
-   */
-  readonly verifyTotpCode?: (code: string) => boolean;
-}
-/**
- * Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —
- * the host the Toss app reserves 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.
- */
-declare function isPrivateAppsHost(hostname: string): boolean;
-/**
- * Returns whether `hostname` is any `*.tossmini.com` subdomain — the host
- * family the Toss app serves mini-app pages from. Includes the 2.x
- * `*.private-apps.tossmini.com` dogfood hosts and the 3.0 unified serving
- * hosts (devtools#760).
- */
-declare function isTossminiHost(hostname: string): boolean;
-/**
- * The host suffix Cloudflare quick-tunnels use — the env 2 (PWA) entry.
- *
- * Env 2 serves the local Vite dev server through a `*.trycloudflare.com` quick
- * tunnel (`src/unplugin/tunnel.ts`). It has no Toss app, no `intoss-private://`
- * scheme, and — critically — no production runtime: the SDK is the devtools
- * mock, and the page is the developer's own dev build. The Layer B1 safety net
- * (which stops a dogfood build that lands on a Toss *production* host from
- * attaching) has nothing to protect against here, because env 2 has no
- * production host. So a trycloudflare host is allowed past B1 — but ONLY past
- * B1: the remaining layers (C1 opt-in, C2 relay, C3 TOTP) still apply, so a
- * leaked tunnel URL is still blocked by TOTP exactly as on the Toss path.
- *
- * The match is the same exact-suffix `endsWith` check as
- * {@link isPrivateAppsHost} — never a substring `.includes()`, which would
- * accept an attacker-controlled `evil.trycloudflare.com.example.com`. The
- * leading `.` forces a real subdomain label, so a bare `trycloudflare.com`
- * (no tunnel subdomain) does not match.
- */
-declare function isTrycloudflareHost(hostname: string): boolean;
-/**
- * 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
- * }
- * ```
- */
-declare function evaluateDebugGate(input: GateInput): GateResult;
-//#endregion
-//#region src/in-app/attach.d.ts
-/**
- * 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.
- */
-declare function deriveTargetScriptUrl(relayUrl: string, atCode?: string | null): string;
-declare global {
-  interface Window {
-    /**
-     * Set once {@link installRelayWsObserver} has wrapped `window.WebSocket`
-     * (#730). The bare CDP-injected indicator (`buildIndicatorExpression`)
-     * checks this flag to decide whether it can piggy-back on the
-     * `ait:relay-ws-state` CustomEvent this module broadcasts, instead of
-     * installing a second competing `Proxy` on `window.WebSocket`.
-     */
-    __ait_relay_ws_observed?: boolean;
-  }
-}
-/**
- * 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.
- */
+//#region src/stubs/in-app.d.ts
+/**
+ * TRANSITION STUB — REMOVE IN 1.0.0.
+ *
+ * `@ait-co/devtools/in-app` moved to `@ait-co/debug-console` (#818).
+ *
+ * **This stub must never throw.** Unlike the `/mcp/*` and `/test-runner`
+ * subpaths, the in-app attach surface is the one piece of the old debug
+ * surface that legitimately ends up inside a shipped mini-app bundle. A
+ * consumer who built and deployed against `@ait-co/devtools@0.1.x` has this
+ * import (or an unplugin-injected equivalent) sitting in production code; if
+ * upgrading the package turned that import into a throw, their app would die
+ * on a real user's phone over a developer-tools concern. So every export here
+ * is an inert no-op that says its piece through `console.error` once and
+ * returns the shape the old API returned.
+ *
+ * The surface below mirrors the pre-split `src/in-app/index.ts` exports so a
+ * stale call site still type-checks and still runs; it simply does nothing.
+ */
+/** Gate decision shape the pre-split module returned. */
+interface GateResult {
+  /** Always `false` here — this stub never attaches anything. */
+  attach: boolean;
+  /** Why the gate did not open. */
+  reason: string;
+}
+/** No-op. The real attach lives in `@ait-co/debug-console`. */
+declare function maybeAttach(): void;
+/** No-op — there is nothing attached to detach. */
 declare function detachDebugSurface(): void;
-/**
- * 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.
- */
+/** No-op — the WebView type self-report moved with the attach surface. */
 declare function reportWebViewType(): void;
-/**
- * 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.
- */
-declare function maybeAttach(gateResult?: GateResult): void;
-//#endregion
-//#region src/in-app/bridge-observer.d.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.
- */
-/** Name of the API being called (never its arguments). */
-interface BridgePendingCall {
-  method: string;
-  /** `Date.now()` epoch ms when the call was dispatched. */
-  startedAt: number;
-}
-/** The most-recent bridge activity — API name + wall-clock + settle status. */
-interface BridgeLastCall {
-  method: string;
-  /** `Date.now()` epoch ms of the start or settle that produced this record. */
-  at: number;
-  status: 'pending' | 'resolved' | 'rejected';
-}
-/**
- * The snapshot exposed on `window.__ait_bridge`. `pending` is keyed by
- * correlation id so a settle is an O(1) delete; the indicator reads
- * `Object.values(pending)` and computes each call's live elapsed itself.
- */
-interface BridgeObserverState {
-  pending: Record<string, BridgePendingCall>;
-  last: BridgeLastCall | null;
-}
-/**
- * CustomEvent fired (no detail) on every start/settle so the indicator badge
- * re-renders promptly. SECRET-HANDLING: carries no detail payload at all — the
- * badge reads the enum-only `window.__ait_bridge` snapshot on receipt.
- */
-declare const BRIDGE_CALL_EVENT = "ait:bridge-call";
-declare global {
-  interface Window {
-    /**
-     * Read-only bridge-call snapshot published by {@link installBridgeObserver}
-     * (#749). The CDP-injected indicator badge reads this to render the pending
-     * native-call list + last-call stamp. Absent when no debug attach ran or in
-     * a context with no observable bridge (env 2 mock). SECRET-HANDLING: holds
-     * API names + timings only — never arguments or results.
-     */
-    __ait_bridge?: BridgeObserverState;
-    /**
-     * 3.0-line native bridge (`@apps-in-toss/webview-bridge`
-     * `injectNativeBridge`). `callAsyncMethod` is the single async dispatcher
-     * the observer wraps.
-     */
-    __appsInTossNativeBridge?: {
-      callAsyncMethod?: (name: string, params?: unknown) => unknown;
-      [key: string]: unknown;
-    };
-    /** 2.x-line native call transport (`ReactNativeWebView.postMessage`). */
-    ReactNativeWebView?: {
-      postMessage?: (message: string) => void;
-      [key: string]: unknown;
-    };
-    /** 2.x-line native→JS settle emitter (`@apps-in-toss/bridge-core`). */
-    __GRANITE_NATIVE_EMITTER?: {
-      emit?: (event: string, args?: unknown) => void;
-      [key: string]: unknown;
-    };
-  }
-}
-/**
- * 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.
- */
-declare function installBridgeObserver(): void;
-/**
- * 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.
- */
-declare function uninstallBridgeObserver(): void;
-//#endregion
-//#region src/in-app/eruda-overlay.d.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/devtools/in-app` graph. A consumer wraps its
- * `import('@ait-co/devtools/in-app')` 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.
- */
-/**
- * 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.
- */
+/** No-op — the eruda overlay moved with the attach surface. */
 declare function mountEruda(): Promise<void>;
-/**
- * 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.
- */
+/** No-op counterpart to {@link mountEruda}. */
 declare function unmountEruda(): void;
-//#endregion
-//#region src/in-app/index.d.ts
-/**
- * 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.
- */
+/** No-op — the bridge observer moved with the attach surface. */
+declare function installBridgeObserver(): void;
+/** No-op counterpart to {@link installBridgeObserver}. */
+declare function uninstallBridgeObserver(): void;
+/** Always reports a closed gate — nothing can attach from this package. */
 declare function checkDebugGate(): GateResult;
 //#endregion
-export { BRIDGE_CALL_EVENT, type BridgeLastCall, type BridgeObserverState, type BridgePendingCall, type GateInput, type GateResult, type GateResultAttach, type GateResultBlocked, checkDebugGate, deriveTargetScriptUrl, detachDebugSurface, evaluateDebugGate, installBridgeObserver, isPrivateAppsHost, isTossminiHost, isTrycloudflareHost, maybeAttach, mountEruda, reportWebViewType, uninstallBridgeObserver, unmountEruda };
+export { GateResult, checkDebugGate, detachDebugSurface, installBridgeObserver, maybeAttach, mountEruda, reportWebViewType, uninstallBridgeObserver, unmountEruda };
 //# sourceMappingURL=index.d.ts.map

package/dist/in-app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/bridge-observer.ts","../../src/in-app/eruda-overlay.ts","../../src/in-app/index.ts"],"mappings":";;AAwFA;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAqCA;;;;;AAuBA;;;;;AA2EA;;;;;;;;;;;;AC3RA;;;;;AAUC;;;;;;;;;;AA+OD;;;;;AAkKA;;;;;AA4CA;;;;UDraiB,gBAAA;EAAA,SACN,MAAA;;WAEA,QAAA;EEhDM;EAAA,SFkDN,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;EEhDoB;;;;;;;;AAY/B;;;;;;EAZ+B,SF+DpB,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;EEpDa;;;;AAAqB;;;;;;;;EAArB,SFiEnB,QAAA;EEtCL;;;;;;EAAA,SF8CK,YAAA,EAAc,eAAA;EExClB;;;;;;;;;AA2HP;;;;;AAoFA;;;;;;;;ACjQA;;EDkDO,SFkEI,cAAA,IAAkB,IAAA;AAAA;;AGpF7B;;;;;;;;ACxBA;;iBJ2IgB,iBAAA,CAAkB,QAAA;;;;;;;iBAqClB,cAAA,CAAe,QAAA;;;;;;;;;;;;;;;;;;;;iBAuBf,mBAAA,CAAoB,QAAA;;;;;;;;;;;;;;;;;;;;;;iBA2EpB,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AA7NrD;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAqCA;;;;;AAuBA;;;;iBChNgB,qBAAA,CAAsB,QAAA,UAAkB,MAAA;AAAA,QAoChD,MAAA;EAAA,UACI,MAAA;IDsP6B;;;;;;;IC9OrC,uBAAA;EAAA;AAAA;AA7CJ;;;;;AAUC;;;;;;;;;;AA+OD;;;;;AAkKA;;;;;AA4CA;;AAvcA,iBAyPgB,kBAAA,CAAA;;;;ACjPhB;;;;;;;;;;;;;;;AAUA;;;;;iBDyYgB,iBAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,WAAA,CAAY,UAAA,GAAY,UAAA;;;;ADraxC;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAqCA;;;;;AAuBA;AAAA,UE3NiB,iBAAA;EACf,MAAA;EF0NkC;EExNlC,SAAA;AAAA;;UAIe,cAAA;EACf,MAAA;EF8RuC;EE5RvC,EAAA;EACA,MAAA;AAAA;;;;;ADAF;UCQiB,mBAAA;EACf,OAAA,EAAS,MAAA,SAAe,iBAAA;EACxB,IAAA,EAAM,cAAA;AAAA;ADAP;;;;;AAAA,cCQY,iBAAA;AAAA,QAWL,MAAA;EAAA,UACI,MAAA;IDee;;AA4M3B;;;;;ICnNI,YAAA,GAAe,mBAAA;IDqXc;;;;AA4CjC;IC3ZI,wBAAA;MACE,eAAA,IAAmB,IAAA,UAAc,MAAA;MAAA,CAChC,GAAA;IAAA;;IAGH,kBAAA;MACE,WAAA,IAAe,OAAA;MAAA,CACd,GAAA;IAAA;IA9D2B;IAiE9B,wBAAA;MACE,IAAA,IAAQ,KAAA,UAAe,IAAA;MAAA,CACtB,GAAA;IAAA;EAAA;AAAA;;;;;;AAhDP;;;;;;iBAsKgB,qBAAA,CAAA;;;;;;iBAoFA,uBAAA,CAAA;;;;AFhOhB;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AA8EA;;;;;AAqCA;;;;;AAuBA;;;iBG/MsB,UAAA,CAAA,GAAc,OAAA;;AH0RpC;;;;;;;;;;;;iBG1PgB,YAAA,CAAA;;;;;AHmHhB;;;;;AAqCA;;;;;AAuBA;;iBIvMgB,cAAA,CAAA,GAAkB,UAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/stubs/in-app.ts"],"mappings":";;AA2CA;;;;;AAQA;;;;;AAKA;;;;;AAKA;;;UAlBiB,UAAA;EAkBgB;EAhB/B,MAAA;EAqB8B;EAnB9B,MAAA;AAAA;;iBAIc,WAAA,CAAA;;iBAKA,kBAAA,CAAA;;iBAKA,iBAAA,CAAA;AAehB;AAAA,iBAVsB,UAAA,CAAA,GAAc,OAAA;;iBAKpB,YAAA,CAAA;;iBAKA,qBAAA,CAAA;;iBAKA,uBAAA,CAAA;;iBAKA,cAAA,CAAA,GAAkB,UAAA"}