@ait-co/devtools 0.1.22 → 0.1.24

package/README.en.md

@@ -13,7 +13,7 @@ Lets you develop and test Apps in Toss mini-apps in a **regular browser** — wi
 - **60+ SDK API mocks** — auth, payments, IAP, location, camera, storage, and more
 - **Device API mode system** — switch between mock / web / prompt modes for device APIs
 - **Device simulation** — iPhone/Galaxy presets + orientation toggle to simulate a mobile viewport in your desktop browser
-- **Floating DevTools Panel** — control SDK state in real time from the browser (10 tabs, mock state preset library included)
+- **Floating DevTools Panel** — control SDK state in real time from the browser (12 tabs, mock state preset library included)
 - **All bundlers supported** — [unplugin](https://github.com/unjs/unplugin)-based Vite, Webpack, Rspack, esbuild, and Rollup integration
 
 Live demo: <https://devtools.aitc.dev/> (the `e2e/fixture/` from this repo deployed to GitHub Pages as a self-contained demo).
@@ -170,12 +170,14 @@ module.exports = {
 | `panel` | `boolean` | `true` | Auto-inject the DevTools Panel |
 | `forceEnable` | `boolean` | `false` | Enable devtools even in production |
 | `mock` | `boolean` | `true` (dev) / `false` (prod+forceEnable) | Enable mock alias |
+| `mcp` | `boolean` | `false` | Add an MCP state endpoint to the Vite dev server (Vite only — see [MCP Server](#mcp-server)) |
 | `tunnel` | `boolean \| { port?: number; qr?: boolean }` | `false` | Expose the Vite dev server via a Cloudflare quick tunnel for real-device preview (see [below](#run-on-a-real-phone)). **Vite dev mode only** |
 
 ```ts
 aitDevtools.vite({ panel: false }); // mock only, no panel
 aitDevtools.vite({ forceEnable: true }); // enable in production (mock OFF by default, panel ON)
 aitDevtools.vite({ forceEnable: true, mock: true }); // enable mock in production too
+aitDevtools.vite({ mcp: true }); // enable MCP endpoint for AI agents
 aitDevtools.vite({ tunnel: true }); // expose dev server at *.trycloudflare.com
 ```
 
@@ -336,7 +338,7 @@ Camera and album APIs return dummy images in mock mode.
 
 When using the plugin, the panel is auto-injected into your entry point file. Click the **'AIT' button** in the bottom-right corner of the screen to toggle it.
 
-### 10 tabs
+### 12 tabs
 
 | Tab | Description |
 |---|---|
@@ -344,9 +346,11 @@ When using the plugin, the panel is auto-injected into your entry point file. Cl
 | **Presets** | Apply/remove common QA scenarios (permission denied, offline, logged out, etc.) with one click. Save and delete user presets |
 | **Viewport** | Simulate a mobile viewport using device presets (iPhone/Galaxy) + orientation toggle |
 | **Permissions** | Control camera, photos, geolocation, clipboard, contacts, and microphone permission states (allowed/denied/notDetermined) |
+| **Notifications** | Choose the next result of the notification-consent flow (new agreement / already agreed / rejected) |
 | **Location** | Set latitude, longitude, and accuracy |
 | **Device** | Switch API modes (mock/web/prompt), manage dummy images (add/remove/reset to defaults) |
 | **IAP** | Choose the next purchase result (success/cancel/error, etc.), TossPay payment result, completed order history (last 5) |
+| **Ads** | Trigger full-screen ad load/show and view the last ad event log |
 | **Events** | Trigger Back/Home navigation events, toggle login state |
 | **Analytics** | Real-time log viewer for recorded analytics events (last 30 entries, with timestamp/type/parameters) |
 | **Storage** | View and clear items stored via the `Storage` API |
@@ -493,7 +497,7 @@ The bottom of the Viewport tab shows the currently applied values in real time:
 ### Known limitations
 
 - **Body becomes the scroll container** — while the viewport is active, scrolling happens on `document.body` rather than `window`. `window.addEventListener('scroll', ...)` or `IntersectionObserver` attached to the root may behave differently from a real device. If your mini-app handles scrolling, verify it against `body` as well.
-- **Estimated presets** — iPhone Air is labeled `(est)` (not yet released) and will be updated when it ships. Galaxy S26 series is based on published spec (phone-simulator.com measurements), but safe area values are temporarily from S25 — pixel-accurate QA should be verified on a real device.
+- **Estimated safe area** — Galaxy S26 series is based on published spec (phone-simulator.com measurements), but safe area values are temporarily from S25 — pixel-accurate QA should be verified on a real device.
 
 ## `window.__ait` console API
 
@@ -780,7 +784,7 @@ Please file an issue: https://github.com/apps-in-toss-community/devtools/issues
 5. Write tests in `src/__tests__/`
 
 ```bash
-pnpm build       # build with tsup
+pnpm build       # build with tsdown
 pnpm typecheck   # verify type compatibility
 pnpm test        # run all tests
 ```
@@ -823,6 +827,109 @@ Since Turbopack doesn't support unplugin, use `resolveAlias` in `next.config.js`
 import '@ait-co/devtools/panel';
 ```
 
+## MCP Server
+
+AI coding agents (Claude Code, Cursor, etc.) can observe a running mini-app directly via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/). A single `devtools-mcp` binary provides two modes.
+
+| Mode | Invocation | Target | Tools |
+|---|---|---|---|
+| **debug** (default) | `devtools-mcp` | Production bundle on a phone or dev browser (CDP/Chii) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| **dev** | `devtools-mcp --mode=dev` | Mock state from a running Vite dev server | `AIT.*` (+ `devtools_get_mock_state` alias) |
+
+Both modes expose the same `AIT.*` tool surface — debug mode backed by the Chii channel, dev mode by the dev server's mock-state HTTP endpoint — so an agent sees the same tools whether attached to a phone (debug) or a dev browser (dev).
+
+### Debug mode (CDP via Chii)
+
+> Read-only tools only. The phone attach roundtrip requires a real-device dog-food step and is deferred to a later phase; the tool layer is CI-verified via mockable injectable CDP connection / AIT source.
+
+Running `devtools-mcp` as a stdio server starts a local Chii relay on `:9100` and opens a cloudflared quick tunnel, printing a public `wss://*.trycloudflare.com` URL, a QR code, and a secret token in the terminal. When the phone enters the dogfood entry point, the in-app attach UI connects to the relay with that URL and token, and the agent reads console/network/page state via `chrome-devtools-mcp`-compatible tools — diagnosing regressions without anyone watching the phone.
+
+```json
+{
+  "mcpServers": {
+    "ait-debug": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp"]
+    }
+  }
+}
+```
+
+| Tool | CDP / AIT backing | Description |
+|---|---|---|
+| `list_console_messages` | `Runtime.consoleAPICalled` | Recent console.log/warn/error messages (level, text, timestamp, args) |
+| `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | Recent XHR/fetch requests (url, method, status, timing) |
+| `list_pages` | Chii relay target list | Attached pages + tunnel status + wss URL |
+| `get_dom_document` | `DOM.getDocument` | DOM tree read (structural/layout regression diagnosis) |
+| `take_snapshot` | `DOMSnapshot.captureSnapshot` | Page snapshot (documents + interned strings, visual regression) |
+| `take_screenshot` | `Page.captureScreenshot` | Page PNG screenshot (returned as an MCP image content block) |
+| `AIT.getSdkCallHistory` | AIT domain | SDK call trace (method, args, result/error, timestamp) |
+| `AIT.getMockState` | AIT domain | Mock state snapshot (`window.__ait`) |
+| `AIT.getOperationalEnvironment` | AIT domain | `getOperationalEnvironment()` + SDK version |
+
+`AIT.*` covers what raw CDP cannot; the same MCP server forwards it alongside CDP. In debug mode the in-app side answers over the Chii channel (phone integration is a later phase).
+
+### Dev mode (mock state)
+
+`devtools-mcp --mode=dev` reads the mock state from a running browser. Phase 3 aligned it on the same `AIT.*` tool surface as debug mode.
+
+#### Architecture
+
+```
+Browser (aitState)
+  └─ POST /api/ait-devtools/state (auto-pushed by the panel on every state change)
+       └─ Vite dev server (unplugin with mcp: true)
+            └─ GET /api/ait-devtools/state
+                 └─ MCP stdio server (dist/mcp/server.js)
+                      └─ AI agent (AIT.getMockState tool)
+```
+
+#### Setup
+
+**1. Add `mcp: true` to the Vite plugin**
+
+```ts
+// vite.config.ts
+import aitDevtools from '@ait-co/devtools/unplugin';
+
+export default {
+  plugins: [aitDevtools.vite({ mcp: true })],
+};
+```
+
+**2. Configure your MCP client (e.g. Claude Code `.claude/settings.json`)**
+
+```json
+{
+  "mcpServers": {
+    "ait-devtools": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp", "--mode=dev"],
+      "env": {
+        "AIT_DEVTOOLS_URL": "http://localhost:5173"
+      }
+    }
+  }
+}
+```
+
+`AIT_DEVTOOLS_URL` defaults to `http://localhost:5173` — you can omit it if you're using the default port.
+
+**3. Open the app in your browser, then call the tool from your AI agent**
+
+```
+> AIT.getMockState
+```
+
+Returns the full current mock state (permissions, location, auth, network, IAP, etc.) as JSON.
+
+| Tool | Description |
+|---|---|
+| `AIT.getMockState` | Returns the current `AitDevtoolsState` snapshot (read-only) |
+| `AIT.getOperationalEnvironment` | Environment + version derived from the mock state's `environment` + `appVersion` |
+| `AIT.getSdkCallHistory` | Empty in dev mode (the HTTP endpoint records no trace) |
+| `devtools_get_mock_state` | Backward-compatible alias of `AIT.getMockState` (prefer `AIT.getMockState` in new configs) |
+
 ## Package export structure
 
 | Import path | Purpose |
@@ -830,6 +937,9 @@ import '@ait-co/devtools/panel';
 | `@ait-co/devtools` or `@ait-co/devtools/mock` | All mock exports (bundler alias target) |
 | `@ait-co/devtools/panel` | Floating DevTools Panel (auto-mounts on import) |
 | `@ait-co/devtools/unplugin` | Bundler plugin (.vite, .webpack, .rspack, .esbuild, .rollup) |
+| `@ait-co/devtools/mcp/server` | Dev-mode MCP stdio server function (Node.js) |
+| `@ait-co/devtools/mcp/cli` | `devtools-mcp` bin entry point (debug / dev mode, Node.js) |
+| `@ait-co/devtools/in-app` | In-app debug attach — 3-layer gate + Chii target.js injection (dogfood builds only; active when `__DEBUG_BUILD__=true`) |
 
 ## Telemetry
 

package/README.md

@@ -13,7 +13,7 @@
 - **60+ SDK API mock** — 인증, 결제, IAP, 위치, 카메라, 스토리지 등
 - **Device API 모드 시스템** — mock / web / prompt 세 가지 모드로 디바이스 API 동작 전환
 - **Device simulation** — iPhone/Galaxy 프리셋 + orientation 토글로 데스크탑 브라우저에서 모바일 뷰포트 시뮬레이션
-- **Floating DevTools Panel** — 브라우저에서 SDK 상태를 실시간으로 제어 (10개 탭, mock state preset library 포함)
+- **Floating DevTools Panel** — 브라우저에서 SDK 상태를 실시간으로 제어 (12개 탭, mock state preset library 포함)
 - **모든 번들러 지원** — [unplugin](https://github.com/unjs/unplugin) 기반 Vite, Webpack, Rspack, esbuild, Rollup 통합
 
 라이브 데모: <https://devtools.aitc.dev/> (이 repo의 `e2e/fixture/`를 GitHub Pages에 그대로 배포한 self-contained 데모).
@@ -170,12 +170,14 @@ module.exports = {
 | `panel` | `boolean` | `true` | DevTools Panel 자동 주입 여부 |
 | `forceEnable` | `boolean` | `false` | production에서도 devtools 활성화 |
 | `mock` | `boolean` | `true` (dev) / `false` (prod+forceEnable) | mock alias 활성화 여부 |
+| `mcp` | `boolean` | `false` | Vite dev server에 MCP state endpoint 추가 (Vite 전용, [MCP 섹션](#mcp-server) 참조) |
 | `tunnel` | `boolean \| { port?: number; qr?: boolean }` | `false` | Vite dev 서버를 Cloudflare quick tunnel로 노출 (실기기 미리보기, [아래](#run-on-a-real-phone-실기기-미리보기) 참고). **Vite dev 모드 전용** |
 
 ```ts
 aitDevtools.vite({ panel: false }); // Panel 없이 mock만 사용
 aitDevtools.vite({ forceEnable: true }); // production에서도 활성화 (mock 기본 OFF, panel ON)
 aitDevtools.vite({ forceEnable: true, mock: true }); // production에서 mock도 활성화
+aitDevtools.vite({ mcp: true }); // AI 에이전트용 MCP endpoint 활성화
 aitDevtools.vite({ tunnel: true }); // dev 서버를 *.trycloudflare.com으로 노출
 ```
 
@@ -336,7 +338,7 @@ mock 모드에서 카메라/앨범 API는 더미 이미지를 반환합니다.
 
 플러그인 사용 시 진입점 파일에 패널이 자동 주입됩니다. 화면 우하단의 **'AIT' 버튼**을 클릭하면 토글됩니다.
 
-### 10개 탭
+### 12개 탭
 
 | 탭 | 설명 |
 |---|---|
@@ -344,9 +346,11 @@ mock 모드에서 카메라/앨범 API는 더미 이미지를 반환합니다.
 | **Presets** | 자주 쓰는 QA 시나리오(권한 거부, offline, 미로그인 등)를 한 클릭으로 적용/해제. 사용자 preset 저장/삭제 가능 |
 | **Viewport** | 디바이스 프리셋(iPhone/Galaxy) + orientation 토글로 모바일 뷰포트 시뮬레이션 |
 | **Permissions** | camera, photos, geolocation, clipboard, contacts, microphone 권한 상태 제어 (allowed/denied/notDetermined) |
+| **Notifications** | 알림 동의 흐름의 다음 결과 선택 (신규 동의 / 이미 동의함 / 거부) |
 | **Location** | 위도, 경도, 정확도 설정 |
 | **Device** | API 모드 전환 (mock/web/prompt), 더미 이미지 관리 (추가/제거/기본값/초기화) |
 | **IAP** | 다음 구매 결과 선택 (success/취소/에러 등), TossPay 결제 결과, 완료된 주문 내역 (최근 5건) |
+| **Ads** | 전면 광고 load/show 트리거 및 마지막 광고 이벤트 로그 |
 | **Events** | Back/Home 네비게이션 이벤트 트리거, 로그인 상태 토글 |
 | **Analytics** | 기록된 분석 이벤트 실시간 로그 뷰어 (최근 30건, 타임스탬프/타입/파라미터) |
 | **Storage** | `Storage` API로 저장된 항목 조회 및 초기화 |
@@ -493,7 +497,7 @@ Viewport 탭 하단에 현재 적용된 값을 실시간으로 보여줍니다:
 ### Known limitations
 
 - **Body가 스크롤 컨테이너가 됩니다** — 뷰포트 활성화 중에는 스크롤이 `window`가 아닌 `document.body`에서 발생합니다. `window.addEventListener('scroll', ...)`나 root에 붙은 `IntersectionObserver`는 실 디바이스와 다른 동작을 보일 수 있습니다. 미니앱 코드에서 스크롤을 다룬다면 `body`도 함께 검증하세요.
-- **추정 프리셋** — iPhone Air는 `(est)` 라벨(미출시)로 표시되며, 실제 출시 후 갱신 예정입니다. Galaxy S26 시리즈는 출시 spec(phone-simulator.com 측정치) 기반이지만 safe area는 S25 값을 잠정 사용 — 픽셀 단위 정확도가 필요한 QA는 실 기기 확인을 권장합니다.
+- **추정 safe area** — Galaxy S26 시리즈는 출시 spec(phone-simulator.com 측정치) 기반이지만 safe area는 S25 값을 잠정 사용합니다 — 픽셀 단위 정확도가 필요한 QA는 실 기기 확인을 권장합니다.
 
 ## `window.__ait` 콘솔 API
 
@@ -780,7 +784,7 @@ Please file an issue: https://github.com/apps-in-toss-community/devtools/issues
 5. `src/__tests/`에 테스트 작성
 
 ```bash
-pnpm build       # tsup으로 빌드
+pnpm build       # tsdown으로 빌드
 pnpm typecheck   # 타입 호환성 검증
 pnpm test        # 전체 테스트 실행
 ```
@@ -823,6 +827,119 @@ Turbopack은 unplugin을 지원하지 않으므로, `next.config.js`에서 `reso
 import '@ait-co/devtools/panel';
 ```
 
+## MCP Server
+
+AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)](https://modelcontextprotocol.io/)를
+통해 실행 중인 미니앱을 직접 관측할 수 있습니다. 단일 `devtools-mcp` bin이 두 모드를 제공합니다.
+
+| 모드 | 호출 | 대상 | tool |
+|---|---|---|---|
+| **debug** (기본값) | `devtools-mcp` | 폰 안 production 번들 또는 dev 브라우저 (CDP/Chii) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| **dev** | `devtools-mcp --mode=dev` | 실행 중인 Vite dev server의 mock state | `AIT.*` (+ `devtools_get_mock_state` alias) |
+
+두 모드는 같은 `AIT.*` tool surface를 노출합니다 — debug 모드는 Chii 채널로, dev 모드는 dev server의
+mock-state HTTP endpoint로 백킹되어, 에이전트가 폰(debug)에 붙든 dev 브라우저(dev)에 붙든 동일한
+tool을 봅니다.
+
+### Debug 모드 (CDP via Chii)
+
+> read-only tool만 노출합니다. 폰 attach 라운드트립은 실기기 dog-food가 필요해 후속 phase로 분리되어
+> 있고, tool 계층은 주입 가능한 CDP 연결 / AIT 소스를 mock해 CI에서 검증됩니다.
+
+`devtools-mcp`를 stdio로 실행하면 로컬 Chii 릴레이(:9100)를 띄우고 cloudflared quick tunnel로
+공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR + secret token을 터미널에 출력합니다.
+폰이 dogfood 진입 시 in-app attach UI가 그 URL + token으로 릴레이에 붙으면, 에이전트가
+`chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을 지켜볼
+필요 없이 회귀를 단독 진단하는 것이 목표입니다.
+
+```json
+{
+  "mcpServers": {
+    "ait-debug": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp"]
+    }
+  }
+}
+```
+
+| Tool | CDP / AIT 백킹 | 설명 |
+|---|---|---|
+| `list_console_messages` | `Runtime.consoleAPICalled` | 최근 console.log/warn/error 메시지 (level, text, timestamp, args) |
+| `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | 최근 XHR/fetch 요청 (url, method, status, timing) |
+| `list_pages` | Chii 릴레이 target 목록 | attach된 페이지 + tunnel 상태 + wss URL |
+| `get_dom_document` | `DOM.getDocument` | DOM 트리 read (구조/레이아웃 회귀 진단) |
+| `take_snapshot` | `DOMSnapshot.captureSnapshot` | 페이지 스냅샷 (documents + interned strings, 시각 회귀 진단) |
+| `take_screenshot` | `Page.captureScreenshot` | 페이지 PNG 스크린샷 (MCP image content block 반환) |
+| `AIT.getSdkCallHistory` | AIT 도메인 | SDK 호출 trace (method, args, result/error, timestamp) |
+| `AIT.getMockState` | AIT 도메인 | mock state 스냅샷 (`window.__ait`) |
+| `AIT.getOperationalEnvironment` | AIT 도메인 | `getOperationalEnvironment()` + SDK 버전 |
+
+`AIT.*`는 raw CDP가 못 잡는 영역으로, 같은 MCP server가 CDP와 함께 forward합니다. debug 모드에서는
+in-app 측이 Chii 채널로 응답합니다(폰 통합은 후속 phase).
+
+### Dev 모드 (mock state)
+
+`devtools-mcp --mode=dev`는 실행 중인 브라우저의 mock state를 읽습니다. Phase 3에서 debug 모드와
+같은 `AIT.*` tool surface로 정렬되었습니다.
+
+#### 구조
+
+```
+브라우저 (aitState)
+  └─ POST /api/ait-devtools/state (panel이 state 변경 시 자동 push)
+       └─ Vite dev server (unplugin mcp: true 로 등록)
+            └─ GET /api/ait-devtools/state
+                 └─ MCP stdio server (dist/mcp/server.js)
+                      └─ AI 에이전트 (AIT.getMockState tool)
+```
+
+#### 설정
+
+**1. Vite 플러그인에 `mcp: true` 추가**
+
+```ts
+// vite.config.ts
+import aitDevtools from '@ait-co/devtools/unplugin';
+
+export default {
+  plugins: [aitDevtools.vite({ mcp: true })],
+};
+```
+
+**2. MCP 클라이언트 설정 (예: Claude Code `.claude/settings.json`)**
+
+```json
+{
+  "mcpServers": {
+    "ait-devtools": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp", "--mode=dev"],
+      "env": {
+        "AIT_DEVTOOLS_URL": "http://localhost:5173"
+      }
+    }
+  }
+}
+```
+
+`AIT_DEVTOOLS_URL`은 기본값이 `http://localhost:5173`이므로 기본 포트를 쓰면 생략 가능합니다.
+
+**3. 앱을 브라우저에서 열고, AI 에이전트에서 tool 호출**
+
+```
+> AIT.getMockState
+```
+
+현재 mock state 전체(권한, 위치, 인증, 네트워크, IAP 등)를 JSON으로 반환합니다.
+
+| Tool | 설명 |
+|---|---|
+| `AIT.getMockState` | 현재 `AitDevtoolsState` 스냅샷 반환 (read-only) |
+| `AIT.getOperationalEnvironment` | mock state의 `environment` + `appVersion` 기반 환경/버전 |
+| `AIT.getSdkCallHistory` | dev 모드에서는 빈 목록 (HTTP endpoint가 trace를 기록하지 않음) |
+| `devtools_get_mock_state` | `AIT.getMockState`의 하위호환 alias (신규 설정은 `AIT.getMockState` 권장) |
+
 ## 패키지 Export 구조
 
 | Import path | 용도 |
@@ -830,6 +947,9 @@ import '@ait-co/devtools/panel';
 | `@ait-co/devtools` 또는 `@ait-co/devtools/mock` | 모든 mock export (번들러 alias 대상) |
 | `@ait-co/devtools/panel` | Floating DevTools Panel (import 시 자동 마운트) |
 | `@ait-co/devtools/unplugin` | 번들러 플러그인 (.vite, .webpack, .rspack, .esbuild, .rollup) |
+| `@ait-co/devtools/mcp/server` | dev-mode MCP stdio server 함수 (Node.js) |
+| `@ait-co/devtools/mcp/cli` | `devtools-mcp` bin 진입점 (debug / dev 모드, Node.js) |
+| `@ait-co/devtools/in-app` | In-app debug attach — 3-layer gate + Chii target.js 주입 (dogfood 빌드 전용, `__DEBUG_BUILD__=true` 시에만 활성) |
 
 ## 텔레메트리
 

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

@@ -0,0 +1,136 @@
+//#region src/in-app/gate.d.ts
+/**
+ * 3-layer 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/.
+ *
+ * Decision matrix:
+ *
+ *   build channel | _deploymentId | debug=1 | result
+ *   release       | (any)         | (any)   | BLOCKED  (Layer A — code absent via DCE)
+ *   dogfood       | absent        | (any)   | BLOCKED  (Layer B — entry gate)
+ *   dogfood       | present       | absent  | BLOCKED  (Layer C — opt-in gate)
+ *   dogfood       | present       | present | ATTACH
+ */
+/** 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;
+  /**
+   * - `'build'`        Layer A: `__DEBUG_BUILD__` is false (release build).
+   * - `'entry'`        Layer B: `_deploymentId` param is absent or empty.
+   * - `'opt-in'`       Layer C: `debug=1` param is absent.
+   * - `'invalid-relay'` Layer C: `relay` param is absent, empty, or not a `wss:` URL.
+   */
+  readonly reason: 'build' | 'entry' | 'opt-in' | 'invalid-relay';
+}
+type GateResult = GateResultAttach | GateResultBlocked;
+/**
+ * Input for {@link evaluateDebugGate}.
+ *
+ * Keeping each field explicit makes the function trivially testable without
+ * needing to manipulate `window.location`.
+ */
+interface GateInput {
+  /**
+   * Whether this is a debug build. Corresponds to the `__DEBUG_BUILD__`
+   * compile-time constant injected by tsdown.
+   *
+   * In source code consumed via `@ait-co/devtools/in-app`, the thin
+   * `src/in-app/index.ts` entry reads `__DEBUG_BUILD__` and passes it here.
+   * Tests supply it directly.
+   */
+  readonly isDebugBuild: boolean;
+  /**
+   * The URL search params to inspect for gate signals.
+   *
+   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`
+   * without coupling the pure function to `window`.
+   *
+   * Layer B open seam (spec open question 2): if the Toss SDK ever exposes
+   * `getEntryScheme()` or a similar API that reliably signals a dogfood entry,
+   * that signal should be checked before `_deploymentId` here. For now only the
+   * `_deploymentId` query param fallback is implemented. Pass a custom
+   * `URLSearchParams` to inject the SDK signal at the call site without
+   * modifying this function.
+   */
+  readonly searchParams: URLSearchParams;
+}
+/**
+ * Pure function that evaluates the 3-layer debug activation gate.
+ *
+ * Has no side effects. All inputs are explicit. Returns a discriminated union
+ * so callers can pattern-match on `result.attach`.
+ *
+ * @example
+ * ```ts
+ * const result = evaluateDebugGate({
+ *   isDebugBuild: __DEBUG_BUILD__,
+ *   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` 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.
+ *
+ * @example
+ * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
+ * // → 'https://abc.trycloudflare.com/target.js'
+ *
+ * deriveTargetScriptUrl('wss://h.example.com:9100/')
+ * // → 'https://h.example.com:9100/target.js'
+ */
+declare function deriveTargetScriptUrl(relayUrl: string): string;
+/**
+ * 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).
+ *
+ * @param gateResult - Optional pre-evaluated gate result for testability.
+ *   Defaults to `checkDebugGate()` which reads the current page URL and the
+ *   `__DEBUG_BUILD__` compile-time constant. Passing a custom value avoids
+ *   the need to manipulate `window.location` in tests.
+ */
+declare function maybeAttach(gateResult?: GateResult): void;
+//#endregion
+//#region src/in-app/index.d.ts
+/**
+ * Evaluates the 3-layer debug activation gate 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` and the `__DEBUG_BUILD__` compile-time
+ * constant. It has no other side effects.
+ */
+declare function checkDebugGate(): GateResult;
+//#endregion
+export { type GateInput, type GateResult, type GateResultAttach, type GateResultBlocked, checkDebugGate, deriveTargetScriptUrl, evaluateDebugGate, maybeAttach };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"mappings":";;AAiBA;;;;;;;;;AASA;;;;;AAWA;AAAA,UApBiB,gBAAA;EAAA,SACN,MAAA;EAmBc;EAAA,SAjBd,QAAA;EAyBM;EAAA,SAvBN,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;EA0Cc;;;AAoBzB;;;EApByB,SAnCd,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;EChBoB;;;;AA6BrC;;;;EA7BqC,SDyB1B,YAAA;;;;AEzBX;;;;;;;;;;WFwCW,YAAA,EAAc,eAAA;AAAA;;;;;;;;;;;;;;;;;;iBAoBT,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AApDrD;;;;;AAQA;;;;;;;iBChBgB,qBAAA,CAAsB,QAAA;;AD4DtC;;;;;;;;;;;;AC5DA;;;;iBA6BgB,WAAA,CAAY,UAAA,GAAY,UAAA;;;;;;ADbxC;;;;;;iBEhBgB,cAAA,CAAA,GAAkB,UAAA"}

package/dist/in-app/index.js

@@ -0,0 +1,163 @@
+//#region src/in-app/gate.ts
+/**
+* Pure function that evaluates the 3-layer debug activation gate.
+*
+* Has no side effects. All inputs are explicit. Returns a discriminated union
+* so callers can pattern-match on `result.attach`.
+*
+* @example
+* ```ts
+* const result = evaluateDebugGate({
+*   isDebugBuild: __DEBUG_BUILD__,
+*   searchParams: new URLSearchParams(window.location.search),
+* });
+* if (result.attach) {
+*   // Proceed to load Chii client
+* }
+* ```
+*/
+function evaluateDebugGate(input) {
+	if (!input.isDebugBuild) return {
+		attach: false,
+		reason: "build"
+	};
+	const deploymentId = input.searchParams.get("_deploymentId") ?? "";
+	if (deploymentId === "") return {
+		attach: false,
+		reason: "entry"
+	};
+	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"
+	};
+	return {
+		attach: true,
+		relayUrl: relayUrl.href,
+		deploymentId
+	};
+}
+//#endregion
+//#region src/in-app/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` 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.
+*
+* @example
+* deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
+* // → 'https://abc.trycloudflare.com/target.js'
+*
+* deriveTargetScriptUrl('wss://h.example.com:9100/')
+* // → 'https://h.example.com:9100/target.js'
+*/
+function deriveTargetScriptUrl(relayUrl) {
+	const u = new URL(relayUrl);
+	u.protocol = "https:";
+	u.pathname = "/target.js";
+	u.search = "";
+	u.hash = "";
+	return u.toString();
+}
+/** Module-level guard against double-injection within a page lifecycle. */
+let attached = false;
+/**
+* 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).
+*
+* @param gateResult - Optional pre-evaluated gate result for testability.
+*   Defaults to `checkDebugGate()` which reads the current page URL and the
+*   `__DEBUG_BUILD__` compile-time constant. Passing a custom value avoids
+*   the need to manipulate `window.location` in tests.
+*/
+function maybeAttach(gateResult = checkDebugGate()) {
+	if (!gateResult.attach) {
+		console.debug(`[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`);
+		return;
+	}
+	if (attached) return;
+	if (typeof document === "undefined") return;
+	const src = deriveTargetScriptUrl(gateResult.relayUrl);
+	if (document.querySelector(`script[src="${src}"]`) !== null) {
+		attached = true;
+		return;
+	}
+	const script = document.createElement("script");
+	script.src = src;
+	script.async = true;
+	(document.head ?? document.documentElement).appendChild(script);
+	attached = true;
+}
+//#endregion
+//#region src/in-app/index.ts
+/**
+* @ait-co/devtools/in-app 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 `__DEBUG_BUILD__` and `window.location`, then calls
+* the pure {@link evaluateDebugGate} function. All testable logic lives in
+* `./gate.ts` and `./attach.ts`, not here.
+*/
+/**
+* Evaluates the 3-layer debug activation gate 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` and the `__DEBUG_BUILD__` compile-time
+* constant. It has no other side effects.
+*/
+function checkDebugGate() {
+	return evaluateDebugGate({
+		isDebugBuild: false,
+		searchParams: new URLSearchParams(window.location.search)
+	});
+}
+//#endregion
+export { checkDebugGate, deriveTargetScriptUrl, evaluateDebugGate, maybeAttach };
+
+//# sourceMappingURL=index.js.map