@ait-co/devtools 0.1.18 → 0.1.20

package/README.md

@@ -1,5 +1,9 @@
 # @ait-co/devtools
 
+**한국어** · [English](./README.en.md)
+
+[![npm](https://img.shields.io/npm/v/@ait-co/devtools)](https://www.npmjs.com/package/@ait-co/devtools) [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
+
 ![@ait-co/devtools — SDK mock + DevTools panel for Apps In Toss mini-apps](./assets/og/image.png)
 
 `@apps-in-toss/web-framework` SDK의 mock 라이브러리입니다. `@apps-in-toss/web-bridge`, `@apps-in-toss/web-analytics` import도 함께 mock됩니다.
@@ -14,10 +18,6 @@
 
 라이브 데모: <https://devtools.aitc.dev/> (이 repo의 `e2e/fixture/`를 GitHub Pages에 그대로 배포한 self-contained 데모).
 
-## Reference consumer
-
-[`sdk-example`](https://github.com/apps-in-toss-community/sdk-example)이 devtools의 reference consumer다. 모든 SDK API를 인터랙티브하게 실행해볼 수 있는 카탈로그 앱으로, 웹 데모는 <https://sdk-example.aitc.dev/>에서 바로 확인할 수 있다. 새 mock을 추가하면 sdk-example의 카드에서 그대로 동작하는 게 1차 sanity check. 단, 이 repo의 E2E suite는 sdk-example을 clone하지 않고 **내부 자기완결 fixture(`e2e/fixture/`)** 로 운영한다 — sdk-example이 깨져도 devtools CI는 영향받지 않는다.
-
 ## 설치
 
 ```bash
@@ -34,6 +34,10 @@ pnpm add -D @ait-co/devtools
 > 안 되는" 상황을 방지하기 위한 의도적 동작입니다. 누락된 API는
 > [이슈](https://github.com/apps-in-toss-community/devtools/issues)로 알려주세요.
 
+## Reference consumer
+
+[`sdk-example`](https://github.com/apps-in-toss-community/sdk-example)이 devtools의 reference consumer다. 모든 SDK API를 인터랙티브하게 실행해볼 수 있는 카탈로그 앱으로, 웹 데모는 <https://sdk-example.aitc.dev/>에서 바로 확인할 수 있다. 새 mock을 추가하면 sdk-example의 카드에서 그대로 동작하는 게 1차 sanity check. 단, 이 repo의 E2E suite는 sdk-example을 clone하지 않고 **내부 자기완결 fixture(`e2e/fixture/`)** 로 운영한다 — sdk-example이 깨져도 devtools CI는 영향받지 않는다.
+
 ## 번들러 설정
 
 ### Vite
@@ -166,11 +170,13 @@ module.exports = {
 | `panel` | `boolean` | `true` | DevTools Panel 자동 주입 여부 |
 | `forceEnable` | `boolean` | `false` | production에서도 devtools 활성화 |
 | `mock` | `boolean` | `true` (dev) / `false` (prod+forceEnable) | mock alias 활성화 여부 |
+| `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({ tunnel: true }); // dev 서버를 *.trycloudflare.com으로 노출
 ```
 
 ## Production 빌드
@@ -209,6 +215,81 @@ if (process.env.NODE_ENV !== 'production') {
 
 > Next.js 설정은 위의 [Next.js (Webpack)](#nextjs-webpack) 및 [Next.js (Turbopack)](#nextjs-turbopack) 섹션을 참고하세요.
 
+## Run on a real phone (실기기 미리보기)
+
+데스크톱 크롬에서 잘 돌던 미니앱을 **실제 폰**에서 보고 싶을 때. Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, **계정 불필요**)로 노출하고, 폰에는 고정 URL의 launcher PWA를 한 번만 추가해 그 안에서 매번의 tunnel URL을 띄웁니다.
+
+셋업은 세 갈래입니다:
+
+- **프로젝트당 1회** — `vite.config`에 옵션 + `package.json`에 pnpm 설정 + (선택) `dev:phone` 스크립트
+- **폰당 1회** — launcher PWA를 홈 화면에 추가
+- **매 세션** — `pnpm dev:phone` (또는 `AIT_TUNNEL=1 pnpm dev`) 한 줄
+
+### 1. 프로젝트당 1회 셋업
+
+(a) **`vite.config.ts`에 `tunnel` 옵션 추가** — 항상 켜져 있어 매번 cloudflared가 떠도 괜찮으면 `tunnel: true`, 평소엔 끄고 명시할 때만 켜고 싶으면 env-gate 권장:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import aitDevtools from '@ait-co/devtools/unplugin';
+
+export default defineConfig({
+  plugins: [
+    aitDevtools.vite({
+      tunnel: !!process.env.AIT_TUNNEL, // 평소 OFF, AIT_TUNNEL=1 일 때만 ON
+    }),
+  ],
+});
+```
+
+> `process.env.AIT_TUNNEL`은 `vite.config.ts`를 로드하는 시점(= vite 프로세스 기동 시)에 평가됩니다. 따라서 env 변수는 **vite를 띄우기 전에** 설정되어 있어야 합니다 (아래 (c)의 `dev:phone` 스크립트가 이를 자동으로 해결합니다).
+
+(b) **`package.json`에 pnpm 10+ 빌드 스크립트 허용** — pnpm은 보안상 dependency의 postinstall을 기본 차단합니다. `cloudflared`는 postinstall에서 바이너리(~38 MB)를 받으므로 명시 허용 필요:
+
+```json
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["cloudflared"]
+  }
+}
+```
+
+> 명시하지 않아도 동작은 됩니다 — `tunnel.ts`가 첫 기동 시 `cloudflared.install()`을 lazy로 호출. 다만 `pnpm install`마다 "Ignored build scripts" 경고가 남고, 바이너리 다운로드가 첫 `pnpm dev` 시점으로 미뤄집니다. 참고: [`sdk-example#60`](https://github.com/apps-in-toss-community/sdk-example/pull/60).
+
+(c) **(선택) `dev:phone` 스크립트** — env 변수 매번 타기 귀찮으면:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:phone": "AIT_TUNNEL=1 vite"
+  }
+}
+```
+
+### 2. 폰당 1회 셋업
+
+폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가**합니다 (iOS Safari "공유 → 홈 화면에 추가", Android Chrome "앱 설치"). launcher 자체는 URL이 바뀌지 않으니 한 번만 하면 됩니다.
+
+### 3. 매 세션
+
+1. 데스크톱에서 `pnpm dev:phone`을 실행합니다 (1-(c) 스크립트를 추가하지 않았다면 `AIT_TUNNEL=1 pnpm dev`). 터미널에 `https://*.trycloudflare.com` URL + ASCII QR이 출력됩니다.
+2. 폰의 launcher 아이콘 실행 → 카메라로 QR 스캔(또는 URL 붙여넣기) → 주소창 없는 풀스크린으로 dev 앱이 뜹니다.
+3. 다음 세션엔 새 URL을 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
+
+### 배경
+
+> **왜 launcher를 거치나요?** quick tunnel URL은 매 실행마다 바뀌므로 그 URL 자체를 PWA로 설치하면 다음 세션엔 죽은 링크가 됩니다. cross-origin으로 페이지를 전환하면 iOS/Android 모두 standalone(크롬리스)이 깨집니다. → 고정 URL의 launcher를 한 번 설치하고, 그 안의 `<iframe>`으로 그날의 dev 앱을 full-bleed로 보여주는 구조입니다.
+>
+> quick tunnel은 **인증이 없고**, **URL이 매 실행마다 바뀌며**, **프로덕션용이 아닙니다**. (계정·도메인이 있다면 named tunnel로 고정 hostname을 받는 방식은 추후 `tunnel: { hostname }` 옵션으로 확장 여지를 남겨뒀습니다.)
+>
+> `tunnel` 옵션은 Vite dev 모드에서만 동작합니다 — production 빌드는 `forceEnable`이어도 터널을 띄우지 않습니다. 다른 번들러(Webpack/Rspack 등)에서는 무시됩니다. 이 옵션을 켜면 `cloudflared` / `qrcode-terminal`가 동적 import로만 로드되므로, 끄면 번들 그래프에 들어오지 않습니다.
+
+### 한 줄 셋업 (예정)
+
+위 "프로젝트당 1회" 단계(vite.config 패치 + `onlyBuiltDependencies` + `dev:phone` 스크립트)는 향후 [`agent-plugin`](https://github.com/apps-in-toss-community/agent-plugin)이 `/ait setup phone` 같은 단일 명령으로 흡수할 예정입니다 (명령 이름은 잠정). 이 README가 그 자동화의 명세서 역할을 하므로, 수동 셋업 단계가 줄어들어도 동작 모델 자체는 동일합니다.
+
 ## Device API 모드 시스템
 
 디바이스 관련 API(카메라, 위치, 클립보드 등)는 세 가지 모드로 동작합니다:
@@ -362,7 +443,7 @@ Landscape로 전환하면:
 **Show Apps in Toss nav bar** 토글(기본 on)을 켜면:
 - 토스 호스트의 상단 nav bar(뒤로가기 / 앱 아이콘·이름 / ⋯ / ×)를 48px 높이로 오버레이
 - status bar 바로 아래, safe area top 이후에 배치
-- **중요**: 이 48px는 `env(safe-area-inset-top)` 및 `SafeAreaInsets.get().top`에 **포함되지 않습니다** (공식 SDK 동작). 토스 공식 예제들도 `insets.top + 48` 패턴으로 보정합니다.
+- **중요**: 이 48px는 `env(safe-area-inset-top)` 및 `SafeAreaInsets.get().top`에 **포함되지 않습니다** (SDK 동작). 토스 측 예제들도 `insets.top + 48` 패턴으로 보정합니다.
 
 ### 콘솔에서 직접 조작
 
@@ -746,6 +827,37 @@ import '@ait-co/devtools/panel';
 | `@ait-co/devtools/panel` | Floating DevTools Panel (import 시 자동 마운트) |
 | `@ait-co/devtools/unplugin` | 번들러 플러그인 (.vite, .webpack, .rspack, .esbuild, .rollup) |
 
+## 텔레메트리
+
+devtools는 두 단계의 텔레메트리를 사용합니다.
+
+### Tier 0 — 익명 사용 신호 (기본 ON, opt-out)
+
+패널이 열릴 때 하루 1회 익명 ping을 전송합니다.
+
+수집 항목: `source`, `version`, `ts` — PII 없음, `anon_id` 없음. 서버가 IP+UA 기반 daily hash를 생성하지만 저장하지 않습니다.
+
+끄는 방법:
+- 패널 Environment 탭 → "익명 사용 신호 (Tier 0)" 토글 OFF
+- `localStorage.setItem('__ait_telemetry:t0_off', '1')` (콘솔에서 직접)
+- 환경 변수: `AITC_TELEMETRY=off`
+
+### Tier 1 — 확장 텔레메트리 (기본 OFF, opt-in)
+
+패널 최초 실행 시 동의 토스트로 묻습니다. 동의한 경우에만 수집됩니다.
+
+수집 항목: `panel_open`, `tab_view`, `session_duration` 이벤트 + 익명 UUID(`anon_id`).
+
+끄는 방법:
+- 패널 Environment 탭 → "확장 텔레메트리 (Tier 1)" 토글 OFF
+- 수집된 데이터 삭제: 패널 Environment 탭 → "내 데이터 삭제"
+
+개인정보 처리방침: <https://docs.aitc.dev/privacy>
+
 ## 라이센스
 
 BSD 3-Clause
+
+---
+
+커뮤니티 오픈소스 프로젝트입니다.

package/dist/panel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/panel/index.ts"],"mappings":";;;;;;;iBAqNS,KAAA,CAAA;;;;;;;;;iBA0JA,YAAA,CAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/panel/index.ts"],"mappings":";;;;;;;iBAuNS,KAAA,CAAA;;;;;;;;;iBAyLA,YAAA,CAAA"}