@apps-in-toss/devtools 3.1.0-beta.1 → 3.1.1

package/dist/unplugin/index.d.cts

@@ -1,28 +1,352 @@
-//#region src/unplugin/index.d.ts
+//#region src/mock/deep-merge.d.ts
 /**
- * @apps-in-toss/devtools unplugin
- *
- * 모든 주요 번들러를 지원하는 단일 플러그인.
- * @apps-in-toss/web-framework → @apps-in-toss/devtools/mock 으로 alias 설정.
- *
- * Usage:
- *   import aitDevtools from '@apps-in-toss/devtools/unplugin';
+ * unplugin `initialState` 옵션이 `DEFAULT_STATE`에 병합될 때 쓰는 순수
+ * 유틸리티. 카탈로그 선언 의미론에 맞춰 **객체는 재귀 병합, 배열은 부분
+ * 병합 없이 통째로 교체**한다 — 예를 들어 `iap.products`에 override 배열을
+ * 주면 기존 원소와 합쳐지는 게 아니라 그 배열로 완전히 대체된다(신규 SKU
+ * 하나를 추가하려 해도 기본 카탈로그 원소를 함께 적어야 한다는 뜻).
  *
- *   // Vite
- *   export default { plugins: [aitDevtools.vite()] };
- *
- *   // Webpack / Next.js
- *   config.plugins.push(aitDevtools.webpack());
- *
- *   // Rspack
- *   config.plugins.push(aitDevtools.rspack());
+ * `base`에 없는 키(오탈자·구버전 필드 등)는 조용히 무시한다 — 타입 체크가
+ * 없는 소비자(순수 JS `vite.config.js`)가 잘못된 키를 넣어도 알 수 없는
+ * 필드가 state에 새로 생겨 patch/panel 코드가 예상 못한 shape을 보는 사고를
+ * 막기 위한 방어적 기본값이다.
+ */
+/**
+ * `T`를 재귀적으로 부분 타입화한다. 배열 필드는 원소 단위로 partial하지
+ * 않고 전체 배열 타입을 그대로 유지한다 — merge 시 배열은 통째로 교체되기
+ * 때문에, override 쪽 배열도 완전한 원소 shape을 요구하는 게 맞다.
+ */
+type DeepPartial<T> = T extends (infer _U)[] ? T : T extends readonly (infer _U)[] ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]>; } : T;
+//#endregion
+//#region src/mock/native-error.d.ts
+/**
+ * sdk-example#284 매트릭스에 등재된 2.x 네이티브 실패 코드 인벤토리.
+ * 새 코드가 매트릭스에 추가되면 여기에도 추가한다.
+ */
+type NativeErrorCode = "APP_LOGIN" | "PLACEMENT_ID_FETCH_FAILED" | "EXECUTION_ERROR" | "NO_PERMISSION" | "INVALID_REQUEST" | "INVALID_DATA" | "FAILED_TO_GET_LOADED_AD" | "APP_BRIDGE_THROTTLED" | "1006" | "4000";
+//#endregion
+//#region src/mock/sdk-call.d.ts
+/**
+ * SDK-call trace shape produced by the mock's `observe()` wrapper.
  *
- *   // esbuild
- *   { plugins: [aitDevtools.esbuild()] }
+ * These declarations used to live in `src/mcp/ait-source.ts` (that module is now
+ * `@ait-co/debugger`'s `packages/debugger/src/mcp/ait-source.ts`) because the MCP
+ * `AIT.getSdkCallHistory` tool was their only *consumer*. After the debug
+ * surface moved to `@ait-co/debugger` (#818) the producer — `observe()`
+ * writing into `aitState.sdkCallLog` — is the only side left in this package,
+ * so the types live next to it.
  *
- *   // Rollup
- *   { plugins: [aitDevtools.rollup()] }
+ * They stay part of the public `@apps-in-toss/devtools/mock` surface (re-exported by
+ * `state.ts`): a consumer reading `window.__ait.sdkCallLog` needs the shape,
+ * and any out-of-process reader (the MCP daemon among them) types against the
+ * same declarations.
+ */
+/**
+ * Mock fidelity grade of the SDK call.
+ * - `faithful` — mock faithfully reproduces the real SDK contract (🟢).
+ * - `partial`  — mock partially matches; edge cases may differ from real (🟡).
+ * - `inert`    — mock accepts the call but produces no observable effect (🔴).
+ */
+type AitSdkCallFidelity = "faithful" | "partial" | "inert";
+/** One entry of the SDK-call trace. */
+interface AitSdkCall {
+  /** SDK method name, e.g. `getOperationalEnvironment`, `saveBase64Data`. */
+  method: string;
+  /** Arguments passed to the call, serialized for transport. */
+  args: unknown[];
+  /** Milliseconds since epoch when the call was made. */
+  timestamp: number;
+  /** Outcome — resolved value, rejection error message, or still pending. */
+  status: "resolved" | "rejected" | "pending";
+  /** Serialized resolved value when `status === 'resolved'`. */
+  result?: unknown;
+  /** Error message when `status === 'rejected'`. */
+  error?: string;
+  /** Mock fidelity grade — how closely this mock reproduces the real SDK behaviour. */
+  fidelity: AitSdkCallFidelity;
+}
+//#endregion
+//#region src/mock/types.d.ts
+type PlatformOS = "ios" | "android";
+type OperationalEnvironment = "toss" | "sandbox";
+type NetworkStatus = "OFFLINE" | "WIFI" | "2G" | "3G" | "4G" | "5G" | "WWAN" | "UNKNOWN";
+type PermissionStatus = "notDetermined" | "denied" | "allowed";
+type PermissionName = "clipboard" | "contacts" | "photos" | "geolocation" | "camera" | "microphone";
+type DeviceApiMode = "mock" | "web" | "prompt";
+interface DeviceModes {
+  camera: DeviceApiMode;
+  photos: DeviceApiMode;
+  location: DeviceApiMode;
+  network: "mock" | "web";
+  clipboard: "mock" | "web";
+}
+interface MockData {
+  images: string[];
+  clipboardText: string;
+}
+interface LocationCoords {
+  latitude: number;
+  longitude: number;
+  altitude: number;
+  accuracy: number;
+  altitudeAccuracy: number;
+  heading: number;
+}
+interface MockLocation {
+  coords: LocationCoords;
+  timestamp: number;
+  accessLocation?: "FINE" | "COARSE";
+}
+interface MockContact {
+  name: string;
+  phoneNumber: string;
+}
+interface MockIapProduct {
+  sku: string;
+  type: "CONSUMABLE" | "NON_CONSUMABLE" | "SUBSCRIPTION";
+  displayName: string;
+  displayAmount: string;
+  iconUrl: string;
+  description: string;
+  renewalCycle?: "WEEKLY" | "MONTHLY" | "YEARLY";
+}
+type IapNextResult = "success" | "USER_CANCELED" | "INVALID_PRODUCT_ID" | "PAYMENT_PENDING" | "NETWORK_ERROR" | "ITEM_ALREADY_OWNED" | "INTERNAL_ERROR";
+type NotificationAgreementResult = "newAgreement" | "alreadyAgreed" | "agreementRejected";
+/**
+ * `getConsentedUserData`가 반환할 수 있는 동의 데이터 키. SDK 선언(`@apps-in-toss/web-bridge`
+ * 경유, web-framework 2.x 라인)의 `ConsentedUserDataKey`와 이름·값 동일(devtools#798).
+ */
+type ConsentedUserDataKey = "USER_NAME" | "USER_GENDER" | "USER_NATIONALITY" | "USER_BIRTHDAY" | "USER_PHONE" | "USER_ADDRESS" | "USER_EMAIL" | "USER_CONSUMPTION_HISTORY";
+/** `getConsentedUserData`의 반환 shape. SDK 선언과 동일한 `Partial<Record<..., string>>`. */
+type ConsentedUserData = Partial<Record<ConsentedUserDataKey, string>>;
+interface DeclaredAgeRange {
+  status: "SHARING" | "DECLINED_SHARING" | "UNSUPPORTED_OS" | "NOT_AVAILABLE" | "INVALID_REQUEST" | "FAILED";
+  lowerBound?: number;
+  upperBound?: number;
+  ageRangeDeclaration?: string;
+  activeParentalControls: string[];
+  isEligibleForAgeFeatures?: boolean;
+  errorCode?: string;
+}
+interface AnalyticsLogEntry {
+  timestamp: number;
+  type: string;
+  params: Record<string, unknown>;
+}
+interface SafeAreaInsets {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+type ViewportPresetId = "none" | "iphone-se-3" | "iphone-15-pro" | "iphone-16e" | "iphone-17" | "iphone-air" | "iphone-17-pro" | "iphone-17-pro-max" | "galaxy-s26" | "galaxy-s26-plus" | "galaxy-s26-ultra" | "galaxy-z-flip7" | "galaxy-z-fold7-folded" | "galaxy-z-fold7-unfolded" | "custom";
+/**
+ * Panel의 orientation 선택.
+ * - `auto` — Panel이 강제하지 않음. 앱의 SDK `setDeviceOrientation` 호출을 그대로 따름.
+ *   호출 값은 별도로 `viewport.appOrientation`에 기록되며, `viewport.orientation`은
+ *   계속 `auto`로 유지된다 — 같은 앱이 여러 번 호출해도 매번 정상 반영됨.
+ * - `portrait` / `landscape` — Panel이 강제. SDK 호출은 무시됨 (로그만 남김).
  */
+type ViewportOrientation = "auto" | "portrait" | "landscape";
+/**
+ * `setDeviceOrientation`이 한 번도 호출되지 않은 초기 상태는 `null`.
+ * SDK가 받을 수 있는 값과 일치하므로 portrait/landscape만 허용.
+ */
+type AppOrientation = "portrait" | "landscape" | null;
+/**
+ * Apps in Toss host nav bar 변형. SDK `webViewProps.type`과 의미 일치.
+ * - `partner` (기본): 흰 배경, 뒤로가기 + 앱 아이콘/이름 + ⋯ + ×.
+ * - `game`: 투명 배경, 게임 캔버스를 가리지 않도록 ⋯ + ×만 표시.
+ */
+type AitNavBarType = "partner" | "game";
+interface ViewportState {
+  preset: ViewportPresetId;
+  /** User-controlled orientation. `auto`이면 `appOrientation`을 따른다. */
+  orientation: ViewportOrientation;
+  /**
+   * SDK가 마지막으로 요청한 orientation. `setDeviceOrientation` 호출 시 갱신.
+   * `orientation === 'auto'`일 때 실제 화면 방향 결정에 쓰인다. 초기값 `null`.
+   */
+  appOrientation: AppOrientation;
+  customWidth: number;
+  customHeight: number;
+  frame: boolean;
+  /** Render the Apps in Toss host nav bar (back / app name / ··· / close) inside the frame. */
+  aitNavBar: boolean;
+  /** Nav bar 변형. `partner` = 기본(흰 배경 + 아이콘/이름), `game` = 투명 배경 + ⋯/× 만. */
+  aitNavBarType: AitNavBarType;
+}
+//#endregion
+//#region src/mock/state.d.ts
+interface AitDevtoolsState {
+  platform: PlatformOS;
+  environment: OperationalEnvironment;
+  appVersion: string;
+  locale: string;
+  schemeUri: string;
+  groupId: string;
+  deploymentId: string;
+  deviceId: string;
+  brand: {
+    displayName: string;
+    icon: string;
+    primaryColor: string;
+  };
+  networkStatus: NetworkStatus;
+  navigation: {
+    iosSwipeGestureEnabled: boolean | null;
+  };
+  permissions: Record<PermissionName, PermissionStatus>;
+  location: MockLocation;
+  safeAreaInsets: SafeAreaInsets;
+  contacts: MockContact[];
+  iap: {
+    products: MockIapProduct[];
+    nextResult: IapNextResult;
+    pendingOrders: Array<{
+      orderId: string;
+      sku: string;
+      paymentCompletedDate: string;
+    }>;
+    completedOrders: Array<{
+      orderId: string;
+      sku: string;
+      status: "COMPLETED" | "REFUNDED";
+      date: string;
+    }>;
+  };
+  payment: {
+    nextResult: "success" | "fail";
+    failReason: string;
+  };
+  auth: {
+    isLoggedIn: boolean;
+    isTossLoginIntegrated: boolean;
+    userKeyHash: string;
+    anonymousKeyHash: string;
+    /**
+     * `getConsentedUserData`가 resolve할 최소 plausible 객체(devtools#798). 실제로는
+     * 콘솔에 등록된 동의문/데이터 묶음(`consentedUserDataKey`)에 따라 채워지는 키가
+     * 달라지지만 그 매핑은 서버 쪽 설정이라 mock이 알 수 없다 — 호출 파라미터와
+     * 무관하게 이 상태값을 그대로 반환한다.
+     */
+    consentedUserData: ConsentedUserData;
+    /** `getDeclaredAgeRange`/`User.getDeclaredAgeRange`가 반환할 테스트 값. */
+    declaredAgeRange: DeclaredAgeRange;
+  };
+  notification: {
+    nextResult: NotificationAgreementResult;
+  };
+  ads: {
+    isLoaded: boolean;
+    nextEvent: "loaded" | "clicked" | "dismissed" | "failedToShow" | "impression" | "userEarnedReward";
+    forceNoFill: boolean;
+    lastEvent: {
+      type: string;
+      timestamp: number;
+    } | null;
+    /** AdMob reward 단위 타입 (기본: 'coins') */
+    rewardUnitType: string;
+    /** AdMob reward 단위 수량 (기본: 10) */
+    rewardAmount: number;
+  };
+  game: {
+    profile: {
+      nickname: string;
+      profileImageUri: string;
+    } | null;
+    leaderboardScores: Array<{
+      score: string;
+      timestamp: number;
+    }>;
+  };
+  analyticsLog: AnalyticsLogEntry[];
+  sdkCallLog: AitSdkCall[];
+  deviceModes: DeviceModes;
+  mockData: MockData;
+  panelEditable: boolean;
+  viewport: ViewportState;
+  failureModes: FailureModes;
+}
+/**
+ * per-API 실패 코드 다이얼. 값이 설정된 API만 mock이 reject하고, 나머지는
+ * 기존 낙관적 resolve를 유지한다. `sdkLine`은 envelope shape 분기 축 —
+ * `'2.x'`(기본)는 native envelope(`{name,code,userInfo,moduleName,__isError}`),
+ * `'3.x'`는 맨 Error로 평탄화(sdk-example#284 매트릭스 "패턴 ① envelope 평탄화").
+ */
+interface FailureModes {
+  /** 네이티브 실패 envelope의 라인 축. 기본 '2.x'. */
+  sdkLine: "2.x" | "3.x";
+  /** appLogin 실패 코드 (예: 'APP_LOGIN'). 미설정 시 기존처럼 항상 resolve. */
+  appLogin?: NativeErrorCode;
+  /** GoogleAdMob.loadAppsInTossAdMob 실패 코드 (예: 'PLACEMENT_ID_FETCH_FAILED'). */
+  loadAdMob?: NativeErrorCode;
+  /** loadFullScreenAd 실패 코드 (예: 'EXECUTION_ERROR'). */
+  loadFullScreenAd?: NativeErrorCode;
+  /**
+   * getIsTossLoginIntegratedService 실패 코드 (devtools#783 실측: env3 run11,
+   * 2.x/iOS `A1-awaited-is-boolean` 시나리오 — rejected/`Error`/`EXECUTION_ERROR`).
+   */
+  getIsTossLoginIntegratedService?: NativeErrorCode;
+  /**
+   * requestNotificationAgreement 실패 코드 (devtools#783 실측: env3 run11,
+   * 2.x/iOS `happy-force-*`/`A1-empty-templateCode` 시나리오 전부 —
+   * rejected/`Error`/`4000`).
+   */
+  requestNotificationAgreement?: NativeErrorCode;
+  /**
+   * 권한 이름별 실패 코드 (devtools#783 실측: env3 run11, 2.x/iOS
+   * `permissions.ait.test.ts` PERMISSION_NAMES 순회 — `geolocation`/`camera`/
+   * `microphone`만 rejected/`Error`/`NO_PERMISSION`, `clipboard`/`contacts`/
+   * `photos`는 resolved. 31146의 `granite.config.ts`가 `permissions: []`라
+   * 선언 안 된 권한만 거부되는 그림과 정합 — 전역 on/off가 아니라 이름 단위 맵.
+   * 설정된 이름만 reject, 나머지는 기존대로 resolve.
+   */
+  getPermission?: Partial<Record<PermissionName, NativeErrorCode>>;
+  /**
+   * THROTTLED 다이얼 (#834) — 실기기 네이티브 브리지의 per-method rate limit을
+   * 재현한다. `methods`에 적힌 메서드를 `intervalMs` 안에 재호출하면
+   * `APP_BRIDGE_THROTTLED`로 거부된다(2.x envelope / 3.x 맨 Error는 `sdkLine`을 따름).
+   * 미설정이 기본 = zero behavior change.
+   *
+   * 훅이 실제로 삽입된 메서드는 `throttle.ts`의 `THROTTLE_INSTRUMENTED_METHODS`가
+   * 정본이다 — 목록 밖 이름을 넣어도 효과가 없다. 거부된 호출은 창을 갱신하지 않는다.
+   */
+  throttled?: {
+    methods: string[];
+    intervalMs: number;
+  };
+  /**
+   * soft-resolve 다이얼 (#789) — reject가 아니라 "다른 shape로 resolve"하는 env3
+   * 프로비저닝-의존 실패를 재현한다. 켠 API만 실측 대체 shape로 resolve하고, 미설정
+   * API는 선언 타입대로 성공 shape를 유지한다(다이얼 미사용 시 zero behavior change).
+   * shape는 API별 고정(env3 run11 2.x/iOS 실측 — valueKeys만 실측, 문자열 내용은 예시):
+   *   grantPromotionReward/grantPromotionRewardForGame → { errorCode, message }
+   *   getSubscriptionInfo → {}
+   *   checkoutPayment/requestTossPayPaysBilling → { false, reason } (valueKeys=['false','reason'])
+   * payment shape의 리터럴 `false` 키가 하네스 artifact가 아니라 실기기 WebView 관측값임은
+   * 코드로 확정됐다(sdk-example#303: capture는 relay 개입 전 WebView 안에서 계산 — 아래
+   * checkoutPayment 항목 주석). #303/#789.
+   */
+  softResolve?: {
+    grantPromotionReward?: boolean;
+    grantPromotionRewardForGame?: boolean;
+    getSubscriptionInfo?: boolean;
+    /**
+     * checkoutPayment/requestTossPayPaysBilling → `{ false: …, reason: … }`
+     * (valueKeys=['false','reason'], booleanValues=null). env3 run11 실측 shape로,
+     * 리터럴 `false` 키는 실기기 WebView가 실제로 관측한 형태다 — capture는 WebView
+     * 안에서 `Object.keys(value)`로 계산돼 console 문자열로 나오므로(devtools#696
+     * capture.ts) 우리 CDP relay가 개입하기 전이다. 즉 relay 역직렬화 artifact가 아니라
+     * 모든 WebView 소비자가 보는 shape다(sdk-example#303 진단 결론). 성공 분기 기본값
+     * ({ success: true })은 그대로 두고, 미프로비저닝 실패 재현만 다이얼에 붙인다.
+     */
+    checkoutPayment?: boolean;
+    requestTossPayPaysBilling?: boolean;
+  };
+}
+//#endregion
+//#region src/unplugin/index.d.ts
 type SdkVersionSelection = "auto" | "2" | "3";
 /** Resolve the consumer project's installed SDK major without importing it. */
 declare function detectInstalledSdkMajor(cwd?: string): "2" | "3" | null;
@@ -32,12 +356,74 @@ interface AitDevtoolsOptions {
    * true이면 진입점에 floating panel import를 자동 추가한다.
    */
   panel?: boolean;
+  /**
+   * 패널 자동 주입 대상 진입점 파일 패턴 (default:
+   * `/\/(main|index|entry|app)\.[tj]sx?$/i`).
+   *
+   * 기본 패턴은 파일명이 `main`/`index`/`entry`/`app` 중 하나일 때만
+   * 매칭한다 — 이 이름을 쓰지 않는 진입점(예: 커스텀 브리지 파일)은
+   * `panel: true`여도 자동 주입 대상에서 빠진다. 그런 프로젝트는 이
+   * 옵션으로 자체 진입점 패턴을 지정하면 된다.
+   *
+   * ```ts
+   * aitDevtools.vite({ entryPattern: /\/my-bridge\.[tj]sx?$/i });
+   * ```
+   *
+   * `node_modules` 제외, `.tsx?`/`.jsx?` 확장자 제한은 이 옵션과 무관하게
+   * 항상 적용된다 — 이 옵션은 파일명 매칭 부분만 대체한다.
+   *
+   * `g`(global)/`y`(sticky) 플래그는 붙이지 마세요 — 매 진입점 후보 파일마다
+   * 같은 `RegExp` 인스턴스로 `.test()`를 반복 호출하는데, 두 플래그는
+   * `lastIndex`를 전진시켜 두 번째 파일부터 매칭이 간헐적으로 실패한다.
+   */
+  entryPattern?: RegExp;
   /** web-framework facade selection. Auto-detects the consumer SDK by default. */
   sdkVersion?: SdkVersionSelection;
   /**
-   * mock alias 활성화 여부. default: true (development), false (production)
+   * production 빌드에서도 devtools를 활성화한다 (default: false).
+   *
+   * 기본적으로 devtools는 `NODE_ENV === 'production'`이면 mock alias와
+   * 패널 주입을 모두 건너뛴다(`Production 빌드` 섹션 참고). 스테이징
+   * 환경처럼 production 빌드에서도 패널을 띄우고 싶을 때 `true`로 설정한다.
+   * `mock`은 이 옵션과 독립적으로 결정된다 — `mock` 옵션을 명시하지 않으면
+   * production에서는 여전히 OFF(모니터링 전용), `panel`은 이 옵션이
+   * `true`면 production에서도 ON이다.
+   *
+   * ```ts
+   * aitDevtools.vite({ forceEnable: true }); // panel ON, mock OFF
+   * aitDevtools.vite({ forceEnable: true, mock: true }); // panel + mock 모두 ON
+   * ```
+   */
+  forceEnable?: boolean;
+  /**
+   * mock alias 활성화 여부. default: true (development), false (production,
+   * `forceEnable: true`인 production 빌드 포함)
    */
   mock?: boolean;
+  /**
+   * mock 상태의 초기값 커스터마이즈 — `DEFAULT_STATE`에 재귀 병합된다
+   * (객체는 병합, **배열은 통째로 교체** — 예: `iap.products`를 지정하면
+   * 그 배열이 기본 카탈로그를 완전히 대체한다). `vite.config.ts`에서
+   * 선언적으로 mock 카탈로그를 구성할 때 쓴다.
+   *
+   * ```ts
+   * aitDevtools.vite({
+   *   initialState: {
+   *     iap: {
+   *       products: [
+   *         { sku: "my-sku", type: "CONSUMABLE", displayName: "…", displayAmount: "…", iconUrl: "", description: "…" },
+   *       ],
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * **Vite 전용** (webpack/rspack/esbuild/rollup에서는 무시된다) — Vite의
+   * `define`으로 build-time에 JSON 직렬화해 주입하므로, 값은 JSON으로
+   * 직렬화 가능해야 한다(함수 등 비직렬화 값은 조용히 사라진다). `base`
+   * (=`DEFAULT_STATE`)에 없는 키는 무시된다.
+   */
+  initialState?: DeepPartial<AitDevtoolsState>;
   /**
    * Vite dev server에 MCP state endpoint를 추가할지 여부 (default: false).
    *
@@ -50,63 +436,7 @@ interface AitDevtoolsOptions {
    * Vite 전용: webpack/rspack/esbuild/rollup 환경에서는 무시된다.
    */
   mcp?: boolean;
-  /**
-   * 미니앱의 webViewType (`granite.config.ts`의 `webViewProps.type`)을 빌드 상수
-   * `__WEB_VIEW_TYPE__`로 주입한다 (#580). **Vite 전용** (다른 번들러는 무시).
-   *
-   * 미지정 시 `'partner'`(web-framework `webViewProps.type`의 `@default`)로 주입한다.
-   * `game`이면 게임 모드로 자동 진입한다. (granite.config.ts를 config 시점에
-   * 자동으로 읽는 것은 TS 모듈 로더가 필요해 보류 — 명시 옵션으로 신뢰성 확보, #580.)
-   */
-  webViewType?: "partner" | "game";
-  /**
-   * 미니앱의 `granite.config.ts` `navigationBar.transparentBackground` 값
-   * (SDK `@apps-in-toss/plugins@2.8.0` 신규 필드, #587). `true`이면 env-2 launcher
-   * deep-link에 `&navBarTransparent=1`을 주입해 launcher partner bar가 투명 배경으로
-   * 렌더된다. granite.config를 직접 읽지 않는다(version-agnostic, #580 원칙) —
-   * 소비자 vite.config가 `graniteConfig.navigationBar?.transparentBackground`를
-   * import해 이 옵션으로 넘긴다. 미지정 시 주입 안 함(URL 청정, back-compat).
-   */
-  navBarTransparent?: boolean;
-  /**
-   * 미니앱의 `granite.config.ts` `navigationBar.theme` 값
-   * (SDK `@apps-in-toss/plugins@2.8.0` 신규 필드, #587). `'light'` 또는 `'dark'`이면
-   * env-2 launcher deep-link에 `&navBarTheme=<v>`를 주입해 launcher partner bar가
-   * 해당 테마 글자/아이콘 색으로 렌더된다. granite.config를 직접 읽지 않는다
-   * (version-agnostic, #580 원칙). 미지정 시 주입 안 함(URL 청정, back-compat).
-   */
-  navBarTheme?: "light" | "dark";
-  /**
-   * Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, 계정 불필요)로
-   * 외부 노출해 실제 폰에서 미리보기. **Vite dev 모드 전용** — production에서는
-   * 터널을 띄우지 않는다 (의도치 않은 노출 방지). 다른 번들러는
-   * 무시. `true`면 기본 동작, 객체로 세부 설정 가능.
-   */
-  tunnel?: boolean | {
-    /** 노출할 포트 (미지정 시 dev 서버가 실제 listen한 포트 자동 감지). */
-    port?: number;
-    /** 터미널 ASCII QR 출력 (default: true). */
-    qr?: boolean;
-  };
 }
-/**
- * Resolves the effective tunnel option (#425).
- *
- * An explicit `tunnel` value (including `false`) always takes priority over
- * env vars — the `??` operator means `undefined` (= omitted) falls through,
- * but `false` / `true` / an object are preserved as-is (non-breaking).
- *
- * When the option is omitted:
- * - `AIT_TUNNEL=1` enables the screen-preview tunnel.
- * - Not set → `false` (disabled).
- *
- * Extracted as a pure function so it can be unit-tested without standing up
- * a full Vite dev server.
- *
- * @param explicit - The `tunnel` option as passed by the consumer (or `undefined` when omitted).
- * @param env - The process environment (injectable for testing).
- */
-declare function resolveTunnelOption(explicit: AitDevtoolsOptions["tunnel"], env: Record<string, string | undefined>): AitDevtoolsOptions["tunnel"];
 declare const aitDevtoolsPlugin: import("unplugin").UnpluginInstance<AitDevtoolsOptions | undefined, boolean>;
 /**
  * 번들러 플러그인 팩토리의 반환 타입을 의도적으로 any로 풀어놓아요.
@@ -137,4 +467,4 @@ declare const esbuild: BundlerPluginFactory;
 declare const rspack: BundlerPluginFactory;
 declare const aitDevtools: AitDevtoolsUnplugin;
 //#endregion
-export { AitDevtoolsOptions, SdkVersionSelection, aitDevtools as default, detectInstalledSdkMajor, esbuild, resolveTunnelOption, rollup, rspack, vite, webpack };
+export { AitDevtoolsOptions, SdkVersionSelection, aitDevtools as default, detectInstalledSdkMajor, esbuild, rollup, rspack, vite, webpack };