@ahnseungchan/webviewkit 1.2.0 → 2.0.0

package/README.md

@@ -1,93 +1,115 @@
 # @ahnseungchan/webviewkit
 
-React **WebView·하이브리드 앱**용 스택(push/back) 네비게이션 라이브러리입니다.  
+React **WebView·하이브리드 앱**용 스택(push/back) 네비게이션 + 네이티브 브릿지(RN·Flutter) 라이브러리입니다.  
 `history.pushState`와 CSS 슬라이드 전환으로 네이티브 앱에 가까운 화면 이동을 구현합니다.
 
 ## 설치
 
 ```bash
 npm install @ahnseungchan/webviewkit
-```
-
-**Peer dependencies** (프로젝트에 직접 설치):
-
-```bash
-npm install react react-dom @emotion/react @emotion/styled
+npm install react react-dom @emotion/react @emotion/styled   # peer (react >= 18)
 ```
 
 ## Quick Start
 
 ```tsx
-import { StackRouterProvider, useStackRouter } from "@ahnseungchan/webviewkit";
+import {
+  StackRouterProvider,
+  useParams,
+  useStackRouter,
+} from "@ahnseungchan/webviewkit";
 
 function Home() {
   const { push } = useStackRouter();
-  return <button onClick={() => push("/about")}>About</button>;
+  return <button onClick={() => push("/detail/1?tab=info")}>Detail</button>;
 }
 
-function About() {
+function Detail() {
+  const { id } = useParams<{ id: string }>();
   const { back } = useStackRouter();
-  return <button onClick={back}>Back</button>;
+  return <button onClick={back}>Back from {id}</button>;
 }
 
 export default function App() {
   return (
     <StackRouterProvider
-      maxWidth="600px"
-      enableDevTools
       Activities={[
         { path: "/", element: <Home /> },
-        { path: "/about", element: <About /> },
+        { path: "/detail/:id", element: <Detail /> },
       ]}
       initialActivity={{ path: "/", element: <Home /> }}
+      onBackAtRoot={() => window.close()}
     />
   );
 }
 ```
 
-## Dev Stack Roadmap (1.2.0)
+## 동작 규칙
 
-개발 모드에서 스택이 몇 장 쌓였는지 **눈으로** 확인할 수 있습니다.
-
-| 옵션 | 동작 |
+| 상황 | 동작 |
+|------|------|
+| `push(path)` | 항상 새 엔트리. 전환 중이면 무시(`false`) |
+| 같은 path 다시 push | 새 인스턴스가 쌓인다. 기존 페이지로 가려면 `popTo(path)` |
+| 브라우저·하드웨어 back | popstate 로 스택 pop (URL·화면 항상 일치) |
+| 루트에서 `back()` | history 를 건드리지 않고 `onBackAtRoot()` |
+| 미등록 path | URL 변경 없음, dev 경고 + `onNotFound(path)` |
+| 새로고침·딥링크 | `restoreStack="with-root"`(기본) → `[root, 대상]`, `"top-only"` → `[대상]` |
+| 아래 깔린 페이지 | `visibility: hidden` + `inert` + `aria-hidden` |
+| `prefers-reduced-motion` | 전환 0ms |
+
+## `StackRouterProvider` props
+
+| prop | 기본 | 설명 |
+|------|------|------|
+| `initialActivity` | — | 루트 페이지. 마운트 시 1회만 읽음 |
+| `Activities` | `[]` | `{ path, element }[]`. path 에 `:param` 사용 가능 |
+| `transition` | `"slide"` | `"slide"` · `"fade"` · `"none"` |
+| `duration` | `300` | 전환 ms |
+| `restoreStack` | `"with-root"` | 딥링크 복원 정책 |
+| `onBackAtRoot` / `onNotFound` | — | 콜백 |
+| `isShowHeader` | `false` | `StackHeader` 렌더 |
+| `safeArea` | `false` | `env(safe-area-inset-*)` padding |
+| `maxWidth` | `"600px"` | 본문 최대 폭 |
+| `enableDevTools` | dev 에서 true | 스택 로드맵 오버레이 |
+| `bridge` | — | `true` 또는 `{ allowUrl, onError, emitStackChanged }` — 네이티브 연동 |
+
+## Hooks
+
+| hook | 반환 |
 |------|------|
-| `enableDevTools={true}` | 우하단 로드맵 항상 표시 |
-| `enableDevTools={false}` | 숨김 |
-| 생략 | `development`에서만 표시, production에서는 숨김 |
+| `useStackRouter()` | `push`, `replace`, `reset`, `back`, `pop(n)`, `popTo(path)`, `canGoBack`, `depth`, `currentPath`, `currentState`, `entries`, `isTransitioning` |
+| `useActivity()` | 현재 페이지의 `{ key, path, pattern, params, query, data, index, isTop }` |
+| `useParams()` | `params` |
 
-로드맵에 표시되는 정보:
+테마는 CSS 변수로 바꿉니다: `--wvk-page-bg`, `--wvk-header-bg`, `--wvk-header-border`, `--wvk-header-color`, `--wvk-back-color`.
 
-- **stack × N** — 현재 스택 깊이
-- **점→선** — 쌓인 페이지 순서
-- **경로 목록** — 각 `path`, 최상단에 `← top`
+## Native Bridge
 
 ```tsx
-import { StackDevRoadmap } from "@ahnseungchan/webviewkit";
-
-// StackRouterProvider 없이 디버그 UI만 쓸 때
-<StackDevRoadmap
-  pages={[{ path: "/" }, { path: "/detail" }]}
-  currentPath="/detail"
-/>
+// 1) 스택 라우터와 네이티브를 바로 연결
+<StackRouterProvider bridge {...props} />
+
+// 2) Next.js 등 다른 라우터와 연결
+<WebViewBridgeProvider stack={{ push, replace, pop, reset }} />
+
+// 3) web → native 호출
+import { BridgeError, getStackRouterBridge } from "@ahnseungchan/webviewkit";
+try {
+  const { result } = (await getStackRouterBridge()?.push("/detail")) ?? {};
+} catch (error) {
+  if (error instanceof BridgeError && error.code === "TIMEOUT") { /* ... */ }
+}
 ```
 
-## API
+- inbound·outbound URL 은 기본적으로 **같은 origin 경로만** 허용합니다(`javascript:`·외부 URL 거부). `allowUrl` 로 교체할 수 있습니다.
+- Flutter 브릿지가 늦게 주입돼도(`flutterInAppWebViewPlatformReady`) 감지 후 설치합니다.
+- 하드웨어 back: 네이티브가 `back.request` 를 보내면 웹이 `{ handled }` 로 회신합니다. `handled: false` 면 앱이 종료·닫기를 판단합니다.
 
-| Export | 설명 |
-|--------|------|
-| `StackRouterProvider` | 스택 라우터 루트 |
-| `useStackRouter` | `push`, `back`, `replace`, `forward`, `visiblePages` |
-| `history` | `pushState` / `popstate` 래퍼 (SSR-safe) |
-| `BackRouter` | 뒤로가기 버튼 |
-| `StackHeader` | 경로 표시 헤더 |
-| `StackDevRoadmap` | 스택 로드맵 오버레이 |
-| `STACK_TRANSITION_MS` | 전환 ms 상수 (`500`) |
-| `Direction`, `HistoryAction` | 타입·enum |
+프로토콜 상세: [docs/native-bridge-protocol.md](https://github.com/Ahnseungc/WebViewKit/blob/main/docs/native-bridge-protocol.md)
 
-## 골디 앱 연동 참고
+## 1.x → 2.0
 
-B2C WebView에서는 앱 브릿지(`stackRouterBridge`)와 함께 쓰는 경우가 많습니다.  
-이 패키지는 **웹 단독 스택 UI**이며, RN 브릿지와는 별도 레이어입니다.
+[CHANGELOG](https://github.com/Ahnseungc/WebViewKit/blob/main/CHANGELOG.md#200---2026-11-04) 의 Breaking · Migration 을 참고하세요.
 
 ## License
 

package/dist/index.d.mts

@@ -0,0 +1,451 @@
+import * as _emotion_react_jsx_runtime from '@emotion/react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+declare const BRIDGE_ERROR_CODES: {
+    readonly TIMEOUT: "TIMEOUT";
+    readonly BRIDGE_UNAVAILABLE: "BRIDGE_UNAVAILABLE";
+    readonly INVALID_PAYLOAD: "INVALID_PAYLOAD";
+    readonly URL_NOT_ALLOWED: "URL_NOT_ALLOWED";
+    readonly UNKNOWN_METHOD: "UNKNOWN_METHOD";
+    readonly HANDLER_ERROR: "HANDLER_ERROR";
+};
+type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[keyof typeof BRIDGE_ERROR_CODES];
+declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode | string;
+    constructor(code: BridgeErrorCode | string, message: string, cause?: unknown);
+    toBody(): {
+        code: string;
+        message: string;
+    };
+}
+
+/** WebViewKit native bridge protocol (v1) */
+declare const BRIDGE_PROTOCOL_VERSION: 1;
+declare const BRIDGE_NAMESPACE: "webviewkit";
+type BridgeHostKind = "react-native" | "flutter" | "browser" | "unknown";
+/** Stack navigation — maps to common `stackPush` / `stackPop` WebView handlers */
+declare const STACK_BRIDGE_METHODS: {
+    readonly PUSH: "stack.push";
+    readonly REPLACE: "stack.replace";
+    readonly POP: "stack.pop";
+    readonly RESET: "stack.reset";
+    /** web → native: 웹 스택 깊이 변경 알림 */
+    readonly CHANGED: "stack.changed";
+};
+type StackBridgeMethod = (typeof STACK_BRIDGE_METHODS)[keyof typeof STACK_BRIDGE_METHODS];
+/** native → web: 하드웨어 back. 응답 payload `{ handled }` */
+declare const BACK_REQUEST_METHOD: "back.request";
+/** 요청에 대한 응답 envelope method (`replyTo` 필수) */
+declare const BRIDGE_RESPONSE_METHOD: "bridge.response";
+type StackMeta = Record<string, unknown> | null;
+type StackPushPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+type StackReplacePayload = StackPushPayload;
+type StackResetPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+type StackChangedPayload = {
+    depth: number;
+    path: string;
+};
+type BackRequestResult = {
+    handled: boolean;
+};
+type BridgeErrorBody = {
+    code: BridgeErrorCode | string;
+    message: string;
+};
+type BridgeEnvelope<TPayload = unknown> = {
+    v: typeof BRIDGE_PROTOCOL_VERSION;
+    ns: typeof BRIDGE_NAMESPACE;
+    id: string;
+    method: string;
+    payload?: TPayload;
+    error?: BridgeErrorBody;
+    /** 응답일 때 원 요청 id */
+    replyTo?: string;
+};
+declare function createBridgeId(): string;
+declare function createBridgeEnvelope<TPayload>(method: string, payload?: TPayload, id?: string): BridgeEnvelope<TPayload>;
+declare function createBridgeResponse<TPayload>(request: Pick<BridgeEnvelope, "id">, result: {
+    payload?: TPayload;
+    error?: BridgeErrorBody;
+}): BridgeEnvelope<TPayload>;
+declare function isBridgeEnvelope(value: unknown): value is BridgeEnvelope;
+declare function parseBridgeMessage(raw: string | unknown): BridgeEnvelope | null;
+declare function serializeBridgeMessage(msg: BridgeEnvelope): string;
+/** Flutter InAppWebView legacy handler names */
+declare const FLUTTER_LEGACY_STACK_HANDLERS: {
+    readonly push: "stackPush";
+    readonly replace: "stackReplace";
+    readonly pop: "stackPop";
+    readonly reset: "stackReset";
+};
+/** Unified handler name when native listens on one channel */
+declare const FLUTTER_UNIFIED_HANDLER = "webviewkitBridge";
+/** React Native receives messages via this global handler name suggestion */
+declare const RN_BRIDGE_HANDLER = "webviewkitBridge";
+
+/** flutter_inappwebview 가 JS 브릿지를 붙인 뒤 window 에 dispatch 하는 이벤트 */
+declare const FLUTTER_READY_EVENT = "flutterInAppWebViewPlatformReady";
+declare function detectBridgeHost(): BridgeHostKind;
+declare function isNativeBridgeHost(host: BridgeHostKind): boolean;
+interface WaitForBridgeHostOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * 네이티브 브릿지가 늦게 주입되는 경우(Flutter platformReady 이전)를 기다린다.
+ * 즉시 감지되면 바로, 아니면 ready 이벤트·폴링으로 재감지. 타임아웃·abort 시 현재 판정값.
+ */
+declare function waitForBridgeHost({ timeoutMs, signal, }?: WaitForBridgeHostOptions): Promise<BridgeHostKind>;
+
+type BridgeTransportOptions = {
+    /** Flutter: use stackPush/stackPop handlers (default true) */
+    flutterLegacyHandlers?: boolean;
+};
+interface BridgeTransport {
+    readonly host: BridgeHostKind;
+    /** Flutter 는 callHandler 반환값, RN·browser 는 undefined */
+    send(envelope: BridgeEnvelope): Promise<unknown>;
+}
+declare function createBridgeTransport(host?: BridgeHostKind, options?: BridgeTransportOptions): BridgeTransport;
+
+type AllowUrl = (url: string) => boolean;
+/**
+ * 기본 정책: 같은 앱 안의 경로만 허용.
+ * - `/a/b?x=1` 같은 상대 경로 (`//host` 프로토콜 상대 URL 제외)
+ * - 현재 origin 과 같은 절대 http(s) URL
+ * `javascript:`, `data:`, 외부 도메인은 거부한다.
+ */
+declare function isSafeStackUrl(url: string): boolean;
+/** 같은 origin 절대 URL → 경로로 정규화. 그 밖(상대 경로·커스텀 스킴)은 그대로 */
+declare function toStackPath(url: string): string;
+/** payload 에서 url 을 꺼내 형식·정책 검증 후 경로로 반환. 실패 시 BridgeError */
+declare function assertStackUrl(payload: unknown, allowUrl?: AllowUrl): string;
+
+type WebViewBridgeClientOptions = BridgeTransportOptions & {
+    transport?: BridgeTransport;
+    /** outbound stack URL 검증 (기본 isSafeStackUrl) */
+    allowUrl?: AllowUrl;
+    /** 요청 기본 타임아웃 ms */
+    timeoutMs?: number;
+};
+interface BridgeRequestOptions {
+    timeoutMs?: number;
+    /**
+     * RN: 네이티브가 `bridge.response`(replyTo) 로 회신할 때까지 기다린다.
+     * 기본 false — 전송 즉시 resolve (1.x 네이티브 호환).
+     */
+    expectResponse?: boolean;
+}
+interface BridgeResult<TResult = unknown> {
+    /** 전송한 요청 envelope */
+    envelope: BridgeEnvelope;
+    /** Flutter callHandler 반환값 또는 RN 응답 payload */
+    result?: TResult;
+}
+declare class WebViewBridgeClient {
+    readonly host: ReturnType<typeof detectBridgeHost>;
+    private readonly transport;
+    private readonly allowUrl?;
+    private readonly timeoutMs;
+    constructor(options?: WebViewBridgeClientOptions);
+    /** 응답을 기다리지 않는 단방향 전송 */
+    send(envelope: BridgeEnvelope): Promise<unknown>;
+    request<TPayload = unknown, TResult = unknown>(method: string, payload?: TPayload, options?: BridgeRequestOptions): Promise<BridgeResult<TResult>>;
+    private stackRequest;
+    stackPush(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackReplace(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackPop(options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackReset(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    /** web → native 웹 스택 변경 알림 (응답 없음) */
+    notifyStackChanged(payload: StackChangedPayload): Promise<unknown>;
+}
+declare function createWebViewBridgeClient(options?: WebViewBridgeClientOptions): WebViewBridgeClient;
+
+type StackRouterBridge = {
+    push: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    replace: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    pop: (options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    reset: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+};
+type CreateStackRouterBridgeOptions = BridgeTransportOptions & {
+    allowUrl?: AllowUrl;
+    timeoutMs?: number;
+};
+/**
+ * Web → native stack navigation (Flutter `callHandler` / RN `postMessage`).
+ * Returns null in browser-only environments.
+ */
+declare function createStackRouterBridge(options?: CreateStackRouterBridgeOptions): StackRouterBridge | null;
+/** `window.stackRouterBridge` → 모듈 캐시 → 새로 생성 후 캐시 */
+declare function getStackRouterBridge(): StackRouterBridge | null;
+declare function installStackRouterBridge(options?: CreateStackRouterBridgeOptions): StackRouterBridge | null;
+/** 테스트·호스트 전환용 캐시 초기화 */
+declare function resetStackRouterBridgeCache(): void;
+
+type FlutterInAppWebViewBridge = {
+    callHandler: (handlerName: string, ...args: unknown[]) => Promise<unknown>;
+};
+declare global {
+    interface Window {
+        ReactNativeWebView?: {
+            postMessage: (message: string) => void;
+        };
+        flutter_inappwebview?: FlutterInAppWebViewBridge;
+        /** Native → web: unified protocol ingress */
+        webviewkitBridge?: {
+            postMessage: (message: string | unknown) => void;
+        };
+        /** Web → native stack */
+        stackRouterBridge?: StackRouterBridge;
+        /** Native → web stack */
+        stackPush?: (url: string, meta?: StackMeta) => Promise<boolean>;
+        stackReplace?: (url: string, meta?: StackMeta) => Promise<boolean>;
+        stackPop?: () => Promise<boolean>;
+        stackReset?: (url: string, meta?: StackMeta) => Promise<boolean>;
+    }
+}
+
+type HandlerResult = boolean | Promise<boolean>;
+type StackRouterHostHandlers = {
+    push: (url: string, meta?: StackMeta) => HandlerResult;
+    replace: (url: string, meta?: StackMeta) => HandlerResult;
+    pop: () => HandlerResult;
+    reset: (url: string, meta?: StackMeta) => HandlerResult;
+};
+type InstallBridgeHostOptions = {
+    /** Native → web stack navigation */
+    stack?: StackRouterHostHandlers;
+    /** Custom method handlers keyed by envelope `method` */
+    handlers?: Record<string, (payload: unknown, envelope: BridgeEnvelope) => HandlerResult>;
+    /** native → web `back.request` (하드웨어 back). true = 웹에서 처리함 */
+    onBackRequest?: () => HandlerResult;
+    /** Called for every valid envelope before routing */
+    onMessage?: (envelope: BridgeEnvelope) => void;
+    /** 검증 실패·핸들러 예외 (throw 대신 여기로 전달) */
+    onError?: (error: BridgeError, envelope?: BridgeEnvelope) => void;
+    /** inbound stack URL 검증 (기본 isSafeStackUrl) */
+    allowUrl?: AllowUrl;
+    /** 모든 inbound 요청에 `bridge.response` 회신 (back.request 는 항상 회신) */
+    replyToNative?: boolean;
+    /** 회신용 transport 옵션 */
+    transport?: BridgeTransportOptions;
+    /**
+     * `window.stackRouterBridge` 설치 (web → native).
+     * true 면 `createStackRouterBridge()` 로 생성한다.
+     */
+    exposeStackRouterBridge?: StackRouterBridge | boolean;
+    /** Register `window.stackPush` / `stackPop` for Flutter native→web (default true when `stack`) */
+    legacyInboundHandlers?: boolean;
+};
+/** inbound 메시지 처리. 절대 reject 하지 않는다 (실패는 false + onError) */
+declare function handleBridgeMessage(raw: string | unknown, options: InstallBridgeHostOptions): Promise<boolean>;
+type BridgeHostCleanup = () => void;
+declare function installBridgeHost(options: InstallBridgeHostOptions): BridgeHostCleanup;
+/** Emit a protocol envelope from web (e.g. for tests or custom native listeners) */
+declare function emitBridgeEnvelope(method: string, payload?: unknown): BridgeEnvelope;
+
+type WebViewBridgeProviderProps = {
+    children?: ReactNode;
+    /** Native → web stack handlers (e.g. Next.js `router.push`) */
+    stack?: StackRouterHostHandlers;
+    transport?: CreateStackRouterBridgeOptions;
+    /** Install `window.stackRouterBridge` for web → native */
+    enableOutboundBridge?: boolean;
+    hostOptions?: Omit<InstallBridgeHostOptions, "stack" | "exposeStackRouterBridge" | "legacyInboundHandlers">;
+};
+/**
+ * Mount once near the app root (Next.js `layout`, SPA `App`).
+ * Wires protocol ingress + optional legacy window stack handlers.
+ * `stack`·`hostOptions` 는 최신 값을 ref 로 읽으므로 인라인 객체여도 재설치하지 않는다.
+ */
+declare function WebViewBridgeProvider({ children, stack, transport, enableOutboundBridge, hostOptions, }: WebViewBridgeProviderProps): _emotion_react_jsx_runtime.JSX.Element;
+
+/** push/back 전환 기본 시간 (ms). `StackRouterProvider` `duration` 으로 조정 */
+declare const STACK_TRANSITION_MS = 300;
+/** `history.back()` 이 popstate 를 기다리는 최대 시간 */
+declare const BACK_TIMEOUT_MS = 1000;
+/** 브릿지 요청 응답 기본 타임아웃 */
+declare const BRIDGE_TIMEOUT_MS = 5000;
+
+interface StackBridgeSyncOptions {
+    allowUrl?: AllowUrl;
+    onError?: (error: BridgeError, envelope?: BridgeEnvelope) => void;
+    /** 웹 스택 변경 시 `stack.changed` 전송 (기본 true) */
+    emitStackChanged?: boolean;
+}
+
+interface Activity {
+    /** 정적 경로 또는 동적 세그먼트 패턴 (`/detail/:id`) */
+    path: string;
+    element: React.ReactNode;
+}
+type StackTransitionType = "slide" | "fade" | "none";
+type RestoreStackPolicy = "with-root" | "top-only";
+interface StackRouterProviderProps {
+    initialActivity: Activity;
+    Activities?: Activity[];
+    maxWidth?: string;
+    /** true면 상단에 `StackHeader` 렌더 */
+    isShowHeader?: boolean;
+    /** 개발 시 스택 로드맵 오버레이 (기본: NODE_ENV === "development") */
+    enableDevTools?: boolean;
+    transition?: StackTransitionType;
+    /** 전환 시간 ms (기본 STACK_TRANSITION_MS) */
+    duration?: number;
+    /** 새로고침·딥링크 진입 시 스택 복원 정책 (기본 "with-root") */
+    restoreStack?: RestoreStackPolicy;
+    /** env(safe-area-inset-*) padding 적용 */
+    safeArea?: boolean;
+    /** 루트에서 back 했을 때 (앱 종료·WebView 닫기 위임) */
+    onBackAtRoot?: () => void;
+    /** 등록되지 않은 경로로 이동하려 할 때 */
+    onNotFound?: (path: string) => void;
+    /** 네이티브 브릿지 연동 */
+    bridge?: boolean | StackBridgeSyncOptions;
+}
+interface VisiblePage {
+    path: string;
+    element: React.ReactNode;
+}
+declare enum Direction {
+    FORWARD = "forward",
+    BACKWARD = "backward"
+}
+type DirectionType = Direction.FORWARD | Direction.BACKWARD;
+declare enum HistoryAction {
+    PUSH = "PUSH",
+    POP = "POP",
+    REPLACE = "REPLACE"
+}
+interface HistoryState {
+    /** pathname + search */
+    path: string;
+    data?: unknown;
+    action?: HistoryAction;
+    /** 스택 엔트리 고유 key */
+    key?: string;
+    /** 스택 내 위치 (0 = root) */
+    index?: number;
+}
+type HistoryListener = (state: HistoryState) => void;
+
+type HistoryEntryState = Omit<HistoryState, "path" | "action">;
+/**
+ * `window.history` 래퍼.
+ * - 리스너는 브라우저 popstate(뒤로·앞으로·`go`)에서만 호출된다.
+ * - push/replace 는 동기 실행이며 리스너를 호출하지 않는다 (호출자가 상태를 직접 갱신).
+ * - popstate 구독은 첫 리스너 등록 시점에 건다 (import 부작용 없음).
+ */
+declare const history: {
+    push: (path: string, state?: HistoryEntryState) => void;
+    replace: (path: string, state?: HistoryEntryState) => void;
+    /** `history.go(delta)` 후 popstate 가 오면 true, BACK_TIMEOUT_MS 안에 오지 않으면 false */
+    travel: (delta: number) => Promise<boolean>;
+    back: () => Promise<boolean>;
+    forward: () => void;
+    go: (delta: number) => void;
+    getCurrentState: () => HistoryState;
+    addListener: (listener: HistoryListener) => () => boolean;
+};
+
+interface StackDevRoadmapProps {
+    /** 스택에 쌓인 페이지 경로 (아래 → 위 순) */
+    pages: {
+        path: string;
+    }[];
+    currentPath: string;
+    /** false면 렌더하지 않음 */
+    visible?: boolean;
+}
+/**
+ * 개발 환경에서 스택 깊이·경로를 눈으로 확인하는 로드맵 오버레이.
+ * StackRouterProvider `enableDevTools` 와 함께 사용합니다.
+ */
+declare function StackDevRoadmap({ pages, currentPath, visible, }: StackDevRoadmapProps): _emotion_react_jsx_runtime.JSX.Element | null;
+
+interface BackRouterProps {
+    /** 스크린리더 라벨 */
+    label?: string;
+}
+declare const BackRouter: ({ label }: BackRouterProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+interface StackHeaderProps {
+    /** 기본: 현재 path */
+    title?: React.ReactNode;
+}
+declare const Header: ({ title }: StackHeaderProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+interface ActivityContextValue {
+    key: string;
+    path: string;
+    pattern: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    data?: unknown;
+    /** 스택 내 위치 (0 = root) */
+    index: number;
+    isTop: boolean;
+}
+/** 현재 페이지(Activity) 자신의 path·params·query·data */
+declare function useActivity(): ActivityContextValue;
+/** `/detail/:id` → `{ id }` */
+declare function useParams<TParams extends Record<string, string> = Record<string, string>>(): TParams;
+
+interface PathMatch {
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+declare function parseQuery(search: string): Record<string, string>;
+/**
+ * `pattern`(`/detail/:id`)과 `url`(`/detail/3?tab=a#x`)을 비교한다.
+ * 끝의 `/`와 `#hash`는 무시한다. 불일치면 null.
+ */
+declare function matchPath(pattern: string, url: string): PathMatch | null;
+/** 등록 순서대로 첫 매칭 Activity */
+declare function findActivity(activities: Activity[], url: string): {
+    activity: Activity;
+    match: PathMatch;
+} | null;
+
+interface StackEntry {
+    key: string;
+    /** 실제 URL (pathname + search) */
+    path: string;
+    /** 매칭된 Activity path 패턴 */
+    pattern: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    data?: unknown;
+}
+
+interface StackRouterContextValue {
+    currentPath: string;
+    /** top 엔트리의 history state */
+    currentState: HistoryState;
+    depth: number;
+    canGoBack: boolean;
+    isTransitioning: boolean;
+    entries: StackEntry[];
+    /** 1.x 호환 */
+    visiblePages: VisiblePage[];
+    Activities: Activity[];
+    initialActivity: Activity;
+    push: (path: string, data?: unknown) => boolean;
+    replace: (path: string, data?: unknown) => boolean;
+    reset: (path: string, data?: unknown) => boolean;
+    back: () => boolean;
+    pop: (count?: number) => boolean;
+    popTo: (path: string) => boolean;
+    /** @deprecated 스택과 동기화되지 않는다. 브라우저 forward 는 popstate 로 처리된다 */
+    forward: () => void;
+}
+declare const useStackRouter: () => StackRouterContextValue;
+declare const StackRouterProvider: ({ initialActivity, Activities, maxWidth, isShowHeader, enableDevTools, transition, duration, restoreStack, safeArea, onBackAtRoot, onNotFound, bridge, }: StackRouterProviderProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+export { type Activity, type ActivityContextValue, type AllowUrl, BACK_REQUEST_METHOD, BACK_TIMEOUT_MS, BRIDGE_ERROR_CODES, BRIDGE_NAMESPACE, BRIDGE_PROTOCOL_VERSION, BRIDGE_RESPONSE_METHOD, BRIDGE_TIMEOUT_MS, type BackRequestResult, BackRouter, type BridgeEnvelope, BridgeError, type BridgeErrorBody, type BridgeErrorCode, type BridgeHostCleanup, type BridgeHostKind, type BridgeRequestOptions, type BridgeResult, type BridgeTransport, type BridgeTransportOptions, type CreateStackRouterBridgeOptions, Direction, type DirectionType, FLUTTER_LEGACY_STACK_HANDLERS, FLUTTER_READY_EVENT, FLUTTER_UNIFIED_HANDLER, type FlutterInAppWebViewBridge, HistoryAction, type HistoryListener, type HistoryState, type InstallBridgeHostOptions, RN_BRIDGE_HANDLER, type RestoreStackPolicy, STACK_BRIDGE_METHODS, STACK_TRANSITION_MS, type StackBridgeMethod, type StackBridgeSyncOptions, type StackChangedPayload, StackDevRoadmap, type StackEntry, Header as StackHeader, type StackMeta, type StackPushPayload, type StackReplacePayload, type StackResetPayload, type StackRouterBridge, type StackRouterContextValue, type StackRouterHostHandlers, StackRouterProvider, type StackRouterProviderProps, type StackTransitionType, type VisiblePage, type WaitForBridgeHostOptions, WebViewBridgeClient, type WebViewBridgeClientOptions, WebViewBridgeProvider, type WebViewBridgeProviderProps, assertStackUrl, createBridgeEnvelope, createBridgeId, createBridgeResponse, createBridgeTransport, createStackRouterBridge, createWebViewBridgeClient, detectBridgeHost, emitBridgeEnvelope, findActivity, getStackRouterBridge, handleBridgeMessage, history, installBridgeHost, installStackRouterBridge, isBridgeEnvelope, isNativeBridgeHost, isSafeStackUrl, matchPath, parseBridgeMessage, parseQuery, resetStackRouterBridgeCache, serializeBridgeMessage, toStackPath, useActivity, useParams, useStackRouter, waitForBridgeHost };