@ait-co/devtools 0.1.17 → 0.1.19

package/README.md

@@ -166,11 +166,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 +211,26 @@ 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. unplugin에 `tunnel: true` 추가:
+   ```ts
+   // vite.config.ts
+   plugins: [aitDevtools.vite({ tunnel: true })]
+   ```
+2. `pnpm dev` (= `vite`) 실행. dev 서버가 listen하면 터미널에 공개 URL + ASCII QR이 출력됩니다. (첫 실행 시 `cloudflared` 바이너리를 자동 다운로드합니다.)
+3. 폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가** (iOS Safari "공유 → 홈 화면에 추가", Android Chrome "앱 설치"). 이걸 한 번만 하면 됩니다 — launcher 자체는 URL이 바뀌지 않습니다.
+4. launcher 아이콘으로 실행 → 카메라로 2번의 QR을 스캔(또는 URL을 붙여넣기) → dev 앱이 주소창 없는 풀스크린으로 뜹니다.
+5. 다음 세션엔 `pnpm dev` → 새 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로만 로드되므로, 끄면 번들 그래프에 들어오지 않습니다.
+
 ## Device API 모드 시스템
 
 디바이스 관련 API(카메라, 위치, 클립보드 등)는 세 가지 모드로 동작합니다:
@@ -327,10 +349,10 @@ mount();          // 깨끗한 상태로 다시 마운트. 중복 <style>·liste
 | 카테고리 | 기기 |
 |---|---|
 | Apple | iPhone SE (3rd gen), iPhone 16e, iPhone 17, iPhone Air, iPhone 17 Pro, iPhone 17 Pro Max |
-| Samsung | Galaxy S26 *(S25 fallback)*, S26+ *(S25 fallback)*, S26 Ultra *(S25 fallback)*, Z Flip7, Z Fold7 (folded / unfolded) |
+| Samsung | Galaxy S26, S26+, S26 Ultra, Z Flip7, Z Fold7 (folded / unfolded) |
 | 기타 | Custom (width/height 직접 입력), None (기본) |
 
-> **Galaxy S26 시리즈는 2026-05 기준 미출시.** 드롭다운에 보이는 `Galaxy S26 / S26+ / S26 Ultra` 항목은 현재 S25 / S25+ / S25 Ultra의 viewport spec(`width × height`, DPR, safe area)을 그대로 fallback으로 쓰고 있습니다. 라벨에 `(S25 fallback)`이 붙어 있어 UI에서 즉시 구분 가능하며, S26 시리즈 출시 후 확정 spec으로 갱신될 예정입니다. QA에서 픽셀 단위 정확도가 필요한 경우 이 값을 절대값으로 신뢰하지 마세요.
+> **Galaxy S26 시리즈** (2026-03-11 출시)의 CSS viewport 값은 [phone-simulator.com](https://www.phone-simulator.com/)의 측정치를 사용합니다. safe area insets는 토스 호스트 환경 실측 전까지 S25 값을 잠정 사용 — 픽셀 단위 정확도가 필요한 QA는 실 기기에서 한 번 더 확인하세요.
 >
 > iPhone 17 시리즈는 2025-09에 출시되어 실제 spec 기반입니다.
 
@@ -408,7 +430,7 @@ Viewport 탭 하단에 현재 적용된 값을 실시간으로 보여줍니다:
 ### Known limitations
 
 - **Body가 스크롤 컨테이너가 됩니다** — 뷰포트 활성화 중에는 스크롤이 `window`가 아닌 `document.body`에서 발생합니다. `window.addEventListener('scroll', ...)`나 root에 붙은 `IntersectionObserver`는 실 디바이스와 다른 동작을 보일 수 있습니다. 미니앱 코드에서 스크롤을 다룬다면 `body`도 함께 검증하세요.
-- **추정/fallback 프리셋** — iPhone Air는 `(est)` 라벨(미출시), Galaxy S26 / S26+ / S26 Ultra는 `(S25 fallback)` 라벨(미출시, S25 spec을 그대로 사용). 모두 실제 출시 후 갱신 예정이며, QA 시 절대값으로 신뢰하지 마세요.
+- **추정 프리셋** — iPhone Air는 `(est)` 라벨(미출시)로 표시되며, 실제 출시 후 갱신 예정입니다. Galaxy S26 시리즈는 출시 spec(phone-simulator.com 측정치) 기반이지만 safe area는 S25 값을 잠정 사용 — 픽셀 단위 정확도가 필요한 QA는 실 기기 확인을 권장합니다.
 
 ## `window.__ait` 콘솔 API
 

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"}