@ait-co/devtools 0.1.106 → 0.1.108

package/dist/bundle-BJm5jk56.d.ts

@@ -0,0 +1,49 @@
+//#region src/test-runner/bundle.d.ts
+/**
+ * esbuild-based bundler for user test files.
+ *
+ * Bundles a single test file into a self-contained IIFE string that can be
+ * injected into a WebView via `Runtime.evaluate`. The user's SDK imports
+ * (`@apps-in-toss/web-framework` and sub-paths) are intercepted via an
+ * esbuild plugin that redirects them to `window.__sdk`, which the in-app
+ * debug gate (`src/in-app/auto.ts`) installs as a namespace mirror of the
+ * SDK exports (works for both 2.x and 3.x SDK).
+ *
+ * SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
+ */
+/** Options accepted by `bundleTestFile`. */
+interface BundleOptions {
+  /**
+   * Additional esbuild `external` patterns. The SDK package
+   * (`@apps-in-toss/web-framework` and `@apps-in-toss/web-framework/*`) is
+   * always handled by the SDK redirect plugin — callers may add more patterns
+   * to be left as globals.
+   */
+  extraExternals?: string[];
+  /**
+   * Global name for the IIFE output object. Defaults to `__testBundle`.
+   * The runtime entry uses this to call `__testBundle.runTestModule()`.
+   */
+  globalName?: string;
+}
+/**
+ * The result of bundling a test file.
+ * `code` is a self-contained IIFE string ready for `Runtime.evaluate`.
+ */
+interface BundleResult {
+  code: string;
+  warnings: string[];
+}
+/**
+ * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
+ *
+ * The IIFE installs `window.__testBundle` (or the custom `globalName`) with
+ * `runTestModule` as the callable entry point.
+ *
+ * @param absPath - Absolute path to the user test file.
+ * @param opts    - Optional bundling overrides.
+ */
+declare function bundleTestFile(absPath: string, opts?: BundleOptions): Promise<BundleResult>;
+//#endregion
+export { BundleResult as n, bundleTestFile as r, BundleOptions as t };
+//# sourceMappingURL=bundle-BJm5jk56.d.ts.map

package/dist/bundle-BJm5jk56.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-BJm5jk56.d.ts","names":[],"sources":["../src/test-runner/bundle.ts"],"mappings":";;AAwBA;;;;;AAmBA;;;;;AAqEA;;UAxFiB,aAAA;EAwF4C;;;;;;EAjF3D,cAAA;EAiFoD;;;;EA5EpD,UAAA;AAAA;;;;;UAOe,YAAA;EACf,IAAA;EACA,QAAA;AAAA;;;;;;;;;;iBAmEoB,cAAA,CAAe,OAAA,UAAiB,IAAA,GAAO,aAAA,GAAgB,OAAA,CAAQ,YAAA"}

package/dist/cdp-connection-C0AP0tH2.d.ts

@@ -0,0 +1,277 @@
+//#region src/mcp/cdp-connection.d.ts
+/**
+ * Injectable CDP connection abstraction for the debug-mode MCP server.
+ *
+ * The Phase 1 tool layer (`list_console_messages`, `list_network_requests`,
+ * `list_pages`) reads from CDP events captured off a Chii relay connection.
+ * To keep that tool layer CI-verifiable without a phone roundtrip, the actual
+ * relay websocket sits behind this interface. Production wires
+ * `ChiiCdpConnection` (see `chii-connection.ts`); tests inject a fake that
+ * emits canned `Runtime.consoleAPICalled` / `Network.*` events.
+ *
+ * Phase 2 adds CDP *commands* (request→response): `DOM.getDocument`,
+ * `DOMSnapshot.captureSnapshot`, `Page.captureScreenshot`. Unlike Phase 1's
+ * event streams these need a `send(method, params)` round-trip, so the
+ * connection grows a typed `send`. The fake returns canned command results.
+ *
+ * Phase 2 extension: `Runtime.evaluate` (read-only probe) added for the
+ * `measure_safe_area` tool — executes a JS snippet on the attached page and
+ * returns the result as a `RemoteObject`. The fake returns canned results for
+ * unit tests without a phone roundtrip.
+ *
+ * Only the slice of the Chrome DevTools Protocol the tools need is typed here.
+ */
+/** A target (page) the Chii relay currently sees attached. */
+interface CdpTarget {
+  /** Chii's internal target id (session UUID). */
+  id: string;
+  /** Page title reported by the in-app target. */
+  title: string;
+  /** Page URL reported by the in-app target. */
+  url: string;
+}
+/** `Runtime.RemoteObject` subset we surface for console args. */
+interface CdpRemoteObject {
+  type: string;
+  subtype?: string;
+  value?: unknown;
+  description?: string;
+  className?: string;
+}
+/** Payload of a `Runtime.consoleAPICalled` event. */
+interface ConsoleApiCalledEvent {
+  /** log | warning | error | info | debug | … */
+  type: string;
+  args: CdpRemoteObject[];
+  /** Milliseconds since epoch (CDP `Runtime.Timestamp`). */
+  timestamp: number;
+  executionContextId?: number;
+  stackTrace?: {
+    callFrames: Array<{
+      functionName: string;
+      url: string;
+      lineNumber: number;
+      columnNumber: number;
+    }>;
+  };
+}
+/** Payload of a `Network.requestWillBeSent` event (subset). */
+interface NetworkRequestWillBeSentEvent {
+  requestId: string;
+  request: {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+  };
+  /** CDP `Network.MonotonicTime` (seconds). */
+  timestamp: number;
+  /** Wall-clock seconds since epoch, when available. */
+  wallTime?: number;
+  type?: string;
+}
+/** Payload of a `Network.responseReceived` event (subset). */
+interface NetworkResponseReceivedEvent {
+  requestId: string;
+  response: {
+    url: string;
+    status: number;
+    statusText: string;
+    mimeType?: string;
+  };
+  timestamp: number;
+  type?: string;
+}
+/**
+ * A single call frame in a `Runtime.exceptionThrown` stack trace.
+ * Subset of the CDP `Runtime.CallFrame` shape.
+ */
+interface CdpCallFrame {
+  functionName: string;
+  scriptId?: string;
+  url: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+/** Payload of a `Runtime.exceptionThrown` event. */
+interface RuntimeExceptionThrownEvent {
+  /** Milliseconds since epoch (CDP `Runtime.Timestamp`). */
+  timestamp: number;
+  exceptionDetails: {
+    exceptionId: number;
+    text: string;
+    lineNumber: number;
+    columnNumber: number;
+    scriptId?: string;
+    url?: string;
+    stackTrace?: {
+      callFrames: CdpCallFrame[];
+    }; /** The thrown value as a CDP `RemoteObject`. */
+    exception?: CdpRemoteObject;
+  };
+}
+/** Map of the CDP event names Phase 1 consumes to their payload shapes. */
+interface CdpEventMap {
+  'Runtime.consoleAPICalled': ConsoleApiCalledEvent;
+  'Network.requestWillBeSent': NetworkRequestWillBeSentEvent;
+  'Network.responseReceived': NetworkResponseReceivedEvent;
+  'Runtime.exceptionThrown': RuntimeExceptionThrownEvent;
+}
+type CdpEventName = keyof CdpEventMap;
+/** A `DOM.Node` subset (recursive) returned by `DOM.getDocument`. */
+interface CdpDomNode {
+  nodeId: number;
+  /** CDP node type (1 = element, 3 = text, 9 = document, …). */
+  nodeType: number;
+  nodeName: string;
+  /** Tag/local name for elements. */
+  localName?: string;
+  nodeValue?: string;
+  /** Flattened attribute list: `[name, value, name, value, …]`. */
+  attributes?: string[];
+  childNodeCount?: number;
+  children?: CdpDomNode[];
+  documentURL?: string;
+  baseURL?: string;
+}
+/** Result of `DOM.getDocument`. */
+interface DomGetDocumentResult {
+  root: CdpDomNode;
+}
+/** Result of `DOMSnapshot.captureSnapshot` (subset we surface). */
+interface DomSnapshotResult {
+  documents: unknown[];
+  strings: string[];
+}
+/** Result of `Page.captureScreenshot`. */
+interface PageCaptureScreenshotResult {
+  /** Base64-encoded image bytes (PNG by default). */
+  data: string;
+}
+/**
+ * Params for `Runtime.evaluate`.
+ * Covers the subset used by the `measure_safe_area` read-only probe.
+ */
+interface RuntimeEvaluateParams {
+  /** JavaScript expression to evaluate in the page context. */
+  expression: string;
+  /** Return the result as a plain JSON value (vs. a handle). Default false. */
+  returnByValue?: boolean;
+  /** Await a returned Promise before resolving. Default false. */
+  awaitPromise?: boolean;
+}
+/** Result of `Runtime.evaluate`. */
+interface RuntimeEvaluateResult {
+  /** The evaluation result. */
+  result: CdpRemoteObject;
+  /** Present when evaluation threw an uncaught exception. */
+  exceptionDetails?: {
+    text: string;
+    exception?: CdpRemoteObject;
+  };
+}
+/**
+ * Map of CDP command method → params/result shape. Keeps `send` typed so a
+ * `DOM.getDocument` call resolves to a `DomGetDocumentResult`, etc.
+ */
+interface CdpCommandMap {
+  'DOM.getDocument': {
+    params: {
+      depth?: number;
+      pierce?: boolean;
+    };
+    result: DomGetDocumentResult;
+  };
+  'DOMSnapshot.captureSnapshot': {
+    params: {
+      computedStyles?: string[];
+    };
+    result: DomSnapshotResult;
+  };
+  'Page.captureScreenshot': {
+    params: {
+      format?: 'png' | 'jpeg' | 'webp';
+      quality?: number;
+    };
+    result: PageCaptureScreenshotResult;
+  };
+  'Runtime.evaluate': {
+    params: RuntimeEvaluateParams;
+    result: RuntimeEvaluateResult;
+  };
+}
+type CdpCommandName = keyof CdpCommandMap;
+/**
+ * The connection the tool layer reads from. The production implementation
+ * wraps the Chii relay's CDP websocket; tests inject a fake.
+ *
+ * Implementations are expected to maintain an internal ring buffer of recent
+ * events (so a tool call returns recent history rather than only live events).
+ */
+interface CdpConnection {
+  /**
+   * Authoritative kind of this connection's transport (issue #348).
+   *
+   * - `'relay'` — backed by the Chii relay + cloudflared tunnel (a real-device
+   *   WebView, env 3/4). `ChiiCdpConnection`.
+   * - `'local'` — backed by a direct CDP websocket to a local Chromium (env 1).
+   *   `LocalCdpConnection`.
+   *
+   * This replaces the old `getEnvironment()` URL-pattern sniffing: the
+   * `mock` vs `relay` split is now a free, authoritative property of the
+   * connection itself, known before any target attaches. The `relay-dev` vs
+   * `relay-live` distinction is orthogonal (operator-supplied `liveIntent`,
+   * see `environment.ts`) because dog-food and production relays are
+   * byte-identical on the wire.
+   */
+  readonly kind: 'relay' | 'local';
+  /**
+   * Enable the CDP domains Phase 1 needs (`Runtime.enable`, `Network.enable`).
+   * Idempotent. Resolves once the relay has acknowledged (or immediately for a
+   * fake connection).
+   */
+  enableDomains(): Promise<void>;
+  /** Targets (pages) the relay currently sees attached. */
+  listTargets(): CdpTarget[];
+  /** Recent buffered events for a domain, oldest-first. */
+  getBufferedEvents<E extends CdpEventName>(event: E): ReadonlyArray<CdpEventMap[E]>;
+  /** Subscribe to live events. Returns an unsubscribe function. */
+  on<E extends CdpEventName>(event: E, listener: (payload: CdpEventMap[E]) => void): () => void;
+  /**
+   * Issue a CDP command (request → response). Phase 2's DOM/snapshot/screenshot
+   * tools use this; resolves with the typed result or rejects on a CDP error.
+   * Implementations must have called {@link enableDomains} first.
+   */
+  send<M extends CdpCommandName>(method: M, params?: CdpCommandMap[M]['params']): Promise<CdpCommandMap[M]['result']>;
+  /**
+   * Close the underlying transport and reject any in-flight commands.
+   * Optional so that minimal test fakes that don't need teardown remain
+   * compatible without change. Both `ChiiCdpConnection` and
+   * `LocalCdpConnection` already implement this.
+   */
+  close?(): void;
+  /**
+   * Refresh the attached-target list from the relay and return the result.
+   * Emits an internal `'target:attached'` event when a new target appears so
+   * that {@link waitForFirstTarget} can race against the polling round.
+   *
+   * Optional — only `ChiiCdpConnection` (relay mode) supports this; local
+   * connections and test fakes may omit it. Callers should guard with
+   * `connection.refreshTargets?.()`.
+   */
+  refreshTargets?(): Promise<CdpTarget[]>;
+  /**
+   * Waits until at least one target satisfying `filterFn` is attached, then
+   * resolves with the full target list at that moment.
+   *
+   * Optional — only `ChiiCdpConnection` provides the event-driven
+   * implementation. When absent, callers fall back to a generic polling loop.
+   *
+   * @param filterFn      - Predicate the resolved targets must satisfy.
+   * @param timeoutMs     - Reject after this many ms (default 90 000).
+   * @param pollIntervalMs - Fallback poll interval (default 500 ms).
+   */
+  waitForFirstTarget?(filterFn: (targets: CdpTarget[]) => boolean, timeoutMs?: number, pollIntervalMs?: number): Promise<CdpTarget[]>;
+}
+//#endregion
+export { CdpConnection as t };
+//# sourceMappingURL=cdp-connection-C0AP0tH2.d.ts.map

package/dist/cdp-connection-C0AP0tH2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-connection-C0AP0tH2.d.ts","names":[],"sources":["../src/mcp/cdp-connection.ts"],"mappings":"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"}

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

@@ -11,6 +11,23 @@
  * imported chunk stays dormant and `window.__sdk` / `window.__sdkCall` are
  * never installed on a normal production load.
  *
+ * DEPRECATED for builds that require debug code to be PHYSICALLY ABSENT from
+ * the release bundle. This entry is a RUNTIME self-gate, not a build-time one:
+ * the imported chunk (Chii target.js injection, the SDK bridge, and the eruda
+ * console it pulls in via `maybeAttach()`) stays in the production bundle as a
+ * dormant chunk and is only kept asleep at runtime. If your threat model needs
+ * "zero bytes of debug surface in release" (no dormant chunk to extract or
+ * re-enable), do NOT use this entry. Instead guard the call site yourself:
+ *
+ *   if (__DEBUG_BUILD__) {
+ *     import('@ait-co/devtools/in-app').then((m) => m.maybeAttach());
+ *   }
+ *
+ * with `define: { __DEBUG_BUILD__: 'false' }` in your release build — the
+ * bundler then dead-code-eliminates the whole `@ait-co/devtools/in-app` graph
+ * (verified on Vite 8/rolldown). This entry stays for the convenience case
+ * where a dormant chunk gated at runtime is acceptable.
+ *
  * When the gate passes it:
  *  1. Calls `maybeAttach()` — runs the full Layer B/C gate (host allowlist,
  *     opt-in params, relay URL, TOTP) and injects the Chii `target.js` script.

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

@@ -1 +1 @@
-{"version":3,"file":"auto.d.ts","names":[],"sources":["../../src/in-app/auto.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AA4HA;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAhGQ,MAAA;EAAA,UACI,MAAA;;;;;;;;;;IAUR,KAAA,GAAQ,MAAA;;;;;;;;;IAUR,SAAA,IACE,IAAA,aACG,IAAA,gBACA,OAAA;MAAU,EAAA;MAAa,KAAA;MAAiB,KAAA;IAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAsCjC,eAAA,CAAA;;;;;;;;;;;;;;iBAkCA,cAAA,CACd,KAAA,YACA,SAAA"}
+{"version":3,"file":"auto.d.ts","names":[],"sources":["../../src/in-app/auto.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AA6IA;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAhGQ,MAAA;EAAA,UACI,MAAA;;;;;;;;;;IAUR,KAAA,GAAQ,MAAA;;;;;;;;;IAUR,SAAA,IACE,IAAA,aACG,IAAA,gBACA,OAAA;MAAU,EAAA;MAAa,KAAA;MAAiB,KAAA;IAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAsCjC,eAAA,CAAA;;;;;;;;;;;;;;iBAkCA,cAAA,CACd,KAAA,YACA,SAAA"}

package/dist/in-app/auto.js

@@ -40,6 +40,64 @@ const RELAY_AUTH_REJECT_CLOSE_CODE = 4401;
 */
 const RELAY_AUTH_REJECT_REASON = "totp-rejected";
 //#endregion
+//#region src/in-app/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/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.
+*/
+/** Module-level guard against double mount across repeated `maybeAttach` calls. */
+let erudaMounted = false;
+/**
+* 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 {
+		(await import("eruda")).default.init();
+	} catch (err) {
+		erudaMounted = false;
+		console.debug("[@ait-co/devtools] eruda console mount skipped:", err);
+	}
+}
+//#endregion
 //#region src/in-app/gate.ts
 /**
 * The host suffix the Toss app uses to serve dogfood / private mini-apps.
@@ -499,6 +557,7 @@ function maybeAttach(gateResult = checkDebugGate()) {
 	};
 	(document.head ?? document.documentElement).appendChild(script);
 	attached = true;
+	mountEruda();
 	if (typeof window !== "undefined" && new URLSearchParams(window.location.search).get("noKeepAwake") === "1") return;
 	setScreenAwakeMode({ enabled: true }).then(() => {
 		window.addEventListener("beforeunload", () => {
@@ -522,6 +581,23 @@ function maybeAttach(gateResult = checkDebugGate()) {
 * imported chunk stays dormant and `window.__sdk` / `window.__sdkCall` are
 * never installed on a normal production load.
 *
+* DEPRECATED for builds that require debug code to be PHYSICALLY ABSENT from
+* the release bundle. This entry is a RUNTIME self-gate, not a build-time one:
+* the imported chunk (Chii target.js injection, the SDK bridge, and the eruda
+* console it pulls in via `maybeAttach()`) stays in the production bundle as a
+* dormant chunk and is only kept asleep at runtime. If your threat model needs
+* "zero bytes of debug surface in release" (no dormant chunk to extract or
+* re-enable), do NOT use this entry. Instead guard the call site yourself:
+*
+*   if (__DEBUG_BUILD__) {
+*     import('@ait-co/devtools/in-app').then((m) => m.maybeAttach());
+*   }
+*
+* with `define: { __DEBUG_BUILD__: 'false' }` in your release build — the
+* bundler then dead-code-eliminates the whole `@ait-co/devtools/in-app` graph
+* (verified on Vite 8/rolldown). This entry stays for the convenience case
+* where a dormant chunk gated at runtime is acceptable.
+*
 * When the gate passes it:
 *  1. Calls `maybeAttach()` — runs the full Layer B/C gate (host allowlist,
 *     opt-in params, relay URL, TOTP) and injects the Chii `target.js` script.