@ahnseungchan/webviewkit 1.0.8 → 1.3.0

package/README.md

@@ -1,149 +1,109 @@
-# WebViewKit
+# @ahnseungchan/webviewkit
 
-A modern React library for building stack-based navigation in WebView applications, providing smooth transitions and native-like navigation experience.
+React **WebView·하이브리드 앱**용 스택(push/back) 네비게이션 라이브러리입니다.  
+`history.pushState`와 CSS 슬라이드 전환으로 네이티브 앱에 가까운 화면 이동을 구현합니다.
 
-## Features
+## 설치
 
-- 🚀 **Stack-based Navigation**: Native-like navigation with push/pop transitions
-- 🎨 **Smooth Animations**: GSAP-powered animations for fluid page transitions
-- 📱 **Mobile-First**: Designed specifically for WebView and mobile applications
-- 🔧 **TypeScript Support**: Full TypeScript support with comprehensive type definitions
-- 🎯 **Flexible**: Customizable animations, layouts, and navigation behavior
+```bash
+npm install @ahnseungchan/webviewkit
+```
 
-## Installation
+**Peer dependencies** (프로젝트에 직접 설치):
 
 ```bash
-npm install @webviewkit
-# or
-yarn add @webviewkit
-# or
-pnpm add @webviewkit
+npm install react react-dom @emotion/react @emotion/styled
 ```
 
 ## Quick Start
 
 ```tsx
-import React from "react";
-import { StackRouterProvider } from "@webviewkit";
+import { StackRouterProvider, useStackRouter } from "@ahnseungchan/webviewkit";
+
+function Home() {
+  const { push } = useStackRouter();
+  return <button onClick={() => push("/about")}>About</button>;
+}
 
-function App() {
+function About() {
+  const { back } = useStackRouter();
+  return <button onClick={back}>Back</button>;
+}
+
+export default function App() {
   return (
     <StackRouterProvider
       maxWidth="600px"
+      enableDevTools
       Activities={[
-        {
-          path: "/",
-          element: <HomePage />,
-        },
-        {
-          path: "/about",
-          element: <AboutPage />,
-        },
+        { path: "/", element: <Home /> },
+        { path: "/about", element: <About /> },
       ]}
-      initialActivity={{ path: "/", element: <HomePage /> }}
+      initialActivity={{ path: "/", element: <Home /> }}
     />
   );
 }
 ```
 
-## Usage
+## Dev Stack Roadmap (1.2.0)
 
-### Basic Navigation
+개발 모드에서 스택이 몇 장 쌓였는지 **눈으로** 확인할 수 있습니다.
 
-```tsx
-import { useStackRouter } from "@webviewkit/core";
+| 옵션 | 동작 |
+|------|------|
+| `enableDevTools={true}` | 우하단 로드맵 항상 표시 |
+| `enableDevTools={false}` | 숨김 |
+| 생략 | `development`에서만 표시, production에서는 숨김 |
 
-function HomePage() {
-  const { push, back } = useStackRouter();
+로드맵에 표시되는 정보:
 
-  return (
-    <div>
-      <h1>Home</h1>
-      <button onClick={() => push("/about")}>Go to About</button>
-      <button onClick={back}>Back</button>
-    </div>
-  );
-}
-```
-
-### History Management
+- **stack × N** — 현재 스택 깊이
+- **점→선** — 쌓인 페이지 순서
+- **경로 목록** — 각 `path`, 최상단에 `← top`
 
 ```tsx
-import { history } from "@webviewkit";
-
-// Navigate to a new page
-await history.push("/new-page", { data: "some data" });
+import { StackDevRoadmap } from "@ahnseungchan/webviewkit";
 
-// Replace current page
-await history.replace("/replacement-page", { data: "replacement data" });
-
-// Go back
-await history.back();
-
-// Go forward
-await history.forward();
+// StackRouterProvider 없이 디버그 UI만 쓸 때
+<StackDevRoadmap
+  pages={[{ path: "/" }, { path: "/detail" }]}
+  currentPath="/detail"
+/>
 ```
 
-## API Reference
-
-### StackRouterProvider Props
-
-| Prop              | Type                                              | Default   | Description                           |
-| ----------------- | ------------------------------------------------- | --------- | ------------------------------------- |
-| `maxWidth`        | `string`                                          | `"600px"` | Maximum width of the layout container |
-| `isShowHeader`    | `boolean`                                         | `true`    | Whether to show the header            |
-| `Activities`      | `Array<{path: string, element: React.ReactNode}>` | `[]`      | Array of available routes             |
-| `initialActivity` | `{path: string, element: React.ReactNode}`        | -         | Initial route to display              |
-
-### useStackRouter Hook
-
-Returns an object with navigation methods:
-
-- `currentPath`: Current active path
-- `currentState`: Current history state
-- `push(path, data?)`: Navigate to a new page
-- `replace(path, data?)`: Replace current page
-- `back()`: Go back to previous page
-- `forward()`: Go forward to next page
+## API
 
-### History API
+| Export | 설명 |
+|--------|------|
+| `StackRouterProvider` | 스택 라우터 루트 |
+| `useStackRouter` | `push`, `back`, `replace`, `forward`, `visiblePages` |
+| `history` | `pushState` / `popstate` 래퍼 (SSR-safe) |
+| `BackRouter` | 뒤로가기 버튼 |
+| `StackHeader` | 경로 표시 헤더 |
+| `StackDevRoadmap` | 스택 로드맵 오버레이 |
+| `WebViewBridgeProvider` | RN/Flutter 브릿지 (protocol v1) |
+| `getStackRouterBridge` | web → native 스택 호출 |
+| `STACK_TRANSITION_MS` | 전환 ms 상수 (`500`) |
+| `Direction`, `HistoryAction` | 타입·enum |
 
-- `history.push(path, data?)`: Add new history entry
-- `history.replace(path, data?)`: Replace current history entry
-- `history.back()`: Go back to previous entry
-- `history.forward()`: Go forward to next entry
-- `history.go(delta)`: Go to specific history entry
-- `history.getCurrentState()`: Get current history state
-- `history.addListener(listener)`: Add history change listener
+## Native Bridge (1.3.0)
 
-## Examples
+하이브리드 앱에서 **웹 스택 UI**와 **네이티브(WebView) 스택**을 같은 프로토콜로 맞출 때 사용합니다.  
+React Native · Flutter · 브라우저 단독 모두 지원합니다.
 
-See the `packages/browser` directory for complete examples.
-
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build all packages
-pnpm build
+```tsx
+import { WebViewBridgeProvider, getStackRouterBridge } from "@ahnseungchan/webviewkit";
 
-# Run tests
-pnpm test
+// native → web: router handlers / web → native: bridge client
+<WebViewBridgeProvider stack={{ push, replace, pop, reset }} />;
 
-# Run linting
-pnpm lint
+await getStackRouterBridge()?.push("/detail");
 ```
 
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+- Flutter: `stackPush` / `stackPop` 등 레거시 핸들러 또는 JSON envelope
+- React Native: `ReactNativeWebView.postMessage`
+- 프로토콜 상세: [docs/native-bridge-protocol.md](../../docs/native-bridge-protocol.md)
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT

package/dist/bridge/WebViewBridgeProvider.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import { type InstallBridgeHostOptions, type StackRouterHostHandlers } from "./host";
+import { type CreateStackRouterBridgeOptions } from "./stack-router-bridge";
+export 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.
+ */
+export declare function WebViewBridgeProvider({ children, stack, transport, enableOutboundBridge, hostOptions, }: WebViewBridgeProviderProps): import("@emotion/react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=WebViewBridgeProvider.d.ts.map

package/dist/bridge/WebViewBridgeProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebViewBridgeProvider.d.ts","sourceRoot":"","sources":["../../src/bridge/WebViewBridgeProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,QAAQ,CAAC;AAChB,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,SAAS,CAAC,EAAE,8BAA8B,CAAC;IAC3C,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,IAAI,CAChB,wBAAwB,EACxB,OAAO,GAAG,yBAAyB,GAAG,uBAAuB,CAC9D,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAe,EACf,KAAK,EACL,SAAS,EACT,oBAA2B,EAC3B,WAAW,GACZ,EAAE,0BAA0B,oDAiB5B"}

package/dist/bridge/WebViewBridgeProvider.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebViewBridgeProvider = WebViewBridgeProvider;
+const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
+const react_1 = require("react");
+const host_1 = require("./host");
+const stack_router_bridge_1 = require("./stack-router-bridge");
+/**
+ * Mount once near the app root (Next.js `layout`, SPA `App`).
+ * Wires protocol ingress + optional legacy window stack handlers.
+ */
+function WebViewBridgeProvider({ children = null, stack, transport, enableOutboundBridge = true, hostOptions, }) {
+    (0, react_1.useEffect)(() => {
+        const outbound = enableOutboundBridge
+            ? (0, stack_router_bridge_1.createStackRouterBridge)(transport)
+            : undefined;
+        const cleanup = (0, host_1.installBridgeHost)({
+            stack,
+            legacyInboundHandlers: Boolean(stack),
+            exposeStackRouterBridge: outbound !== null && outbound !== void 0 ? outbound : false,
+            ...hostOptions,
+        });
+        return cleanup;
+    }, [stack, enableOutboundBridge, transport, hostOptions]);
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+}

package/dist/bridge/client.d.ts

@@ -0,0 +1,20 @@
+import { type BridgeTransportOptions } from "./transport";
+import { detectBridgeHost } from "./detect-host";
+import type { BridgeTransport } from "./transport";
+import { type BridgeEnvelope, type StackMeta } from "./protocol";
+export type WebViewBridgeClientOptions = BridgeTransportOptions & {
+    transport?: BridgeTransport;
+};
+export declare class WebViewBridgeClient {
+    readonly host: ReturnType<typeof detectBridgeHost>;
+    private readonly transport;
+    constructor(options?: WebViewBridgeClientOptions);
+    send(envelope: BridgeEnvelope): Promise<void>;
+    request<TPayload = unknown>(method: string, payload?: TPayload): Promise<BridgeEnvelope<TPayload>>;
+    stackPush(url: string, meta?: StackMeta): Promise<BridgeEnvelope>;
+    stackReplace(url: string, meta?: StackMeta): Promise<BridgeEnvelope>;
+    stackPop(): Promise<BridgeEnvelope>;
+    stackReset(url: string, meta?: StackMeta): Promise<BridgeEnvelope>;
+}
+export declare function createWebViewBridgeClient(options?: WebViewBridgeClientOptions): WebViewBridgeClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/bridge/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,SAAS,EAGf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,0BAA0B,GAAG,sBAAsB,GAAG;IAChE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,OAAO,GAAE,0BAA+B;IAM9C,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,OAAO,CAAC,QAAQ,GAAG,OAAO,EAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAMpC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,SAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAOvE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,SAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAO1E,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAInC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,SAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;CAMzE;AAED,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,CAErB"}

package/dist/bridge/client.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebViewBridgeClient = void 0;
+exports.createWebViewBridgeClient = createWebViewBridgeClient;
+const transport_1 = require("./transport");
+const detect_host_1 = require("./detect-host");
+const protocol_1 = require("./protocol");
+class WebViewBridgeClient {
+    constructor(options = {}) {
+        var _a, _b, _c;
+        this.host = (_b = (_a = options.transport) === null || _a === void 0 ? void 0 : _a.host) !== null && _b !== void 0 ? _b : (0, detect_host_1.detectBridgeHost)();
+        this.transport =
+            (_c = options.transport) !== null && _c !== void 0 ? _c : (0, transport_1.createBridgeTransport)(this.host, options);
+    }
+    async send(envelope) {
+        await this.transport.send(envelope);
+    }
+    async request(method, payload) {
+        const envelope = (0, protocol_1.createBridgeEnvelope)(method, payload);
+        await this.send(envelope);
+        return envelope;
+    }
+    stackPush(url, meta = null) {
+        return this.request(protocol_1.STACK_BRIDGE_METHODS.PUSH, {
+            url,
+            meta,
+        });
+    }
+    stackReplace(url, meta = null) {
+        return this.request(protocol_1.STACK_BRIDGE_METHODS.REPLACE, {
+            url,
+            meta,
+        });
+    }
+    stackPop() {
+        return this.request(protocol_1.STACK_BRIDGE_METHODS.POP);
+    }
+    stackReset(url, meta = null) {
+        return this.request(protocol_1.STACK_BRIDGE_METHODS.RESET, {
+            url,
+            meta,
+        });
+    }
+}
+exports.WebViewBridgeClient = WebViewBridgeClient;
+function createWebViewBridgeClient(options) {
+    return new WebViewBridgeClient(options);
+}

package/dist/bridge/detect-host.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeHostKind } from "./protocol";
+export declare function detectBridgeHost(): BridgeHostKind;
+export declare function isNativeBridgeHost(host: BridgeHostKind): boolean;
+//# sourceMappingURL=detect-host.d.ts.map

package/dist/bridge/detect-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-host.d.ts","sourceRoot":"","sources":["../../src/bridge/detect-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,gBAAgB,IAAI,cAAc,CAYjD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEhE"}

package/dist/bridge/detect-host.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectBridgeHost = detectBridgeHost;
+exports.isNativeBridgeHost = isNativeBridgeHost;
+function detectBridgeHost() {
+    var _a, _b;
+    if (typeof window === "undefined")
+        return "unknown";
+    if ((_a = window.ReactNativeWebView) === null || _a === void 0 ? void 0 : _a.postMessage) {
+        return "react-native";
+    }
+    if ((_b = window.flutter_inappwebview) === null || _b === void 0 ? void 0 : _b.callHandler) {
+        return "flutter";
+    }
+    return "browser";
+}
+function isNativeBridgeHost(host) {
+    return host === "react-native" || host === "flutter";
+}

package/dist/bridge/host.d.ts

@@ -0,0 +1,31 @@
+import { type BridgeEnvelope, type StackMeta } from "./protocol";
+import type { StackRouterBridge } from "./stack-router-bridge";
+export type StackRouterHostHandlers = {
+    push: (url: string, meta?: StackMeta) => boolean | Promise<boolean>;
+    replace: (url: string, meta?: StackMeta) => boolean | Promise<boolean>;
+    pop: () => boolean | Promise<boolean>;
+    reset: (url: string, meta?: StackMeta) => boolean | Promise<boolean>;
+};
+export type InstallBridgeHostOptions = {
+    /** Native → web stack navigation */
+    stack?: StackRouterHostHandlers;
+    /** Custom method handlers keyed by envelope `method` */
+    handlers?: Record<string, (payload: unknown, envelope: BridgeEnvelope) => boolean | Promise<boolean>>;
+    /** Called for every valid envelope after routing */
+    onMessage?: (envelope: BridgeEnvelope) => void;
+    /**
+     * Expose `window.stackRouterBridge` for imperative web→native calls.
+     * Requires `createStackRouterBridge()` to be set separately or via `stackRouterBridge` option.
+     */
+    exposeStackRouterBridge?: StackRouterBridge | boolean;
+    /**
+     * Register `window.stackPush` / `stackPop` for Flutter native→web.
+     */
+    legacyInboundHandlers?: boolean;
+};
+export declare function handleBridgeMessage(raw: string | unknown, options: InstallBridgeHostOptions): Promise<boolean>;
+export type BridgeHostCleanup = () => void;
+export declare function installBridgeHost(options: InstallBridgeHostOptions): BridgeHostCleanup;
+/** Emit a protocol envelope from web (e.g. for tests or custom native listeners) */
+export declare function emitBridgeEnvelope(method: string, payload?: unknown): BridgeEnvelope;
+//# sourceMappingURL=host.d.ts.map

package/dist/bridge/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/bridge/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,GAAG,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,oCAAoC;IACpC,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CACf,MAAM,EACN,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAC3E,CAAC;IACF,oDAAoD;IACpD,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IAC/C;;;OAGG;IACH,uBAAuB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC;IACtD;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAqCF,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GAAG,OAAO,EACrB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC;AAE3C,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAsCnB;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,GAChB,cAAc,CAEhB"}

package/dist/bridge/host.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleBridgeMessage = handleBridgeMessage;
+exports.installBridgeHost = installBridgeHost;
+exports.emitBridgeEnvelope = emitBridgeEnvelope;
+const protocol_1 = require("./protocol");
+async function dispatchEnvelope(envelope, options) {
+    var _a, _b, _c, _d, _e;
+    (_a = options.onMessage) === null || _a === void 0 ? void 0 : _a.call(options, envelope);
+    const custom = (_b = options.handlers) === null || _b === void 0 ? void 0 : _b[envelope.method];
+    if (custom) {
+        return Boolean(await custom(envelope.payload, envelope));
+    }
+    const stack = options.stack;
+    if (!stack)
+        return false;
+    const payload = envelope.payload;
+    switch (envelope.method) {
+        case protocol_1.STACK_BRIDGE_METHODS.PUSH:
+            if (!(payload === null || payload === void 0 ? void 0 : payload.url))
+                return false;
+            return Boolean(await stack.push(payload.url, (_c = payload.meta) !== null && _c !== void 0 ? _c : null));
+        case protocol_1.STACK_BRIDGE_METHODS.REPLACE:
+            if (!(payload === null || payload === void 0 ? void 0 : payload.url))
+                return false;
+            return Boolean(await stack.replace(payload.url, (_d = payload.meta) !== null && _d !== void 0 ? _d : null));
+        case protocol_1.STACK_BRIDGE_METHODS.POP:
+            return Boolean(await stack.pop());
+        case protocol_1.STACK_BRIDGE_METHODS.RESET:
+            if (!(payload === null || payload === void 0 ? void 0 : payload.url))
+                return false;
+            return Boolean(await stack.reset(payload.url, (_e = payload.meta) !== null && _e !== void 0 ? _e : null));
+        default:
+            return false;
+    }
+}
+function handleBridgeMessage(raw, options) {
+    const envelope = (0, protocol_1.parseBridgeMessage)(raw);
+    if (!envelope)
+        return Promise.resolve(false);
+    return dispatchEnvelope(envelope, options);
+}
+function installBridgeHost(options) {
+    if (typeof window === "undefined") {
+        return () => undefined;
+    }
+    const inbound = (raw) => {
+        void handleBridgeMessage(raw, options);
+    };
+    window.webviewkitBridge = { postMessage: inbound };
+    if (options.legacyInboundHandlers !== false && options.stack) {
+        const { stack } = options;
+        window.stackPush = (url, meta) => Promise.resolve(stack.push(url, meta !== null && meta !== void 0 ? meta : null)).then(Boolean);
+        window.stackReplace = (url, meta) => Promise.resolve(stack.replace(url, meta !== null && meta !== void 0 ? meta : null)).then(Boolean);
+        window.stackPop = () => Promise.resolve(stack.pop()).then(Boolean);
+        window.stackReset = (url, meta) => Promise.resolve(stack.reset(url, meta !== null && meta !== void 0 ? meta : null)).then(Boolean);
+    }
+    if (options.exposeStackRouterBridge) {
+        if (typeof options.exposeStackRouterBridge === "object") {
+            window.stackRouterBridge = options.exposeStackRouterBridge;
+        }
+    }
+    return () => {
+        delete window.webviewkitBridge;
+        delete window.stackPush;
+        delete window.stackReplace;
+        delete window.stackPop;
+        delete window.stackReset;
+        if (options.exposeStackRouterBridge) {
+            delete window.stackRouterBridge;
+        }
+    };
+}
+/** Emit a protocol envelope from web (e.g. for tests or custom native listeners) */
+function emitBridgeEnvelope(method, payload) {
+    return (0, protocol_1.createBridgeEnvelope)(method, payload);
+}

package/dist/bridge/index.d.ts

@@ -0,0 +1,10 @@
+export { BRIDGE_PROTOCOL_VERSION, BRIDGE_NAMESPACE, STACK_BRIDGE_METHODS, FLUTTER_LEGACY_STACK_HANDLERS, FLUTTER_UNIFIED_HANDLER, RN_BRIDGE_HANDLER, createBridgeId, createBridgeEnvelope, isBridgeEnvelope, parseBridgeMessage, serializeBridgeMessage, } from "./protocol";
+export type { BridgeHostKind, StackBridgeMethod, StackMeta, StackPushPayload, StackReplacePayload, StackResetPayload, BridgeEnvelope, BridgeErrorBody, } from "./protocol";
+export { detectBridgeHost, isNativeBridgeHost } from "./detect-host";
+export { createBridgeTransport, type BridgeTransport, type BridgeTransportOptions, } from "./transport";
+export { WebViewBridgeClient, createWebViewBridgeClient, type WebViewBridgeClientOptions, } from "./client";
+export { installBridgeHost, handleBridgeMessage, emitBridgeEnvelope, type InstallBridgeHostOptions, type StackRouterHostHandlers, type BridgeHostCleanup, } from "./host";
+export { createStackRouterBridge, getStackRouterBridge, installStackRouterBridge, type StackRouterBridge, type CreateStackRouterBridgeOptions, } from "./stack-router-bridge";
+export { WebViewBridgeProvider } from "./WebViewBridgeProvider";
+export type { WebViewBridgeProviderProps } from "./WebViewBridgeProvider";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,6BAA6B,EAC7B,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,0BAA0B,GAChC,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,GACvB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,8BAA8B,GACpC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/bridge/index.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebViewBridgeProvider = exports.installStackRouterBridge = exports.getStackRouterBridge = exports.createStackRouterBridge = exports.emitBridgeEnvelope = exports.handleBridgeMessage = exports.installBridgeHost = exports.createWebViewBridgeClient = exports.WebViewBridgeClient = exports.createBridgeTransport = exports.isNativeBridgeHost = exports.detectBridgeHost = exports.serializeBridgeMessage = exports.parseBridgeMessage = exports.isBridgeEnvelope = exports.createBridgeEnvelope = exports.createBridgeId = exports.RN_BRIDGE_HANDLER = exports.FLUTTER_UNIFIED_HANDLER = exports.FLUTTER_LEGACY_STACK_HANDLERS = exports.STACK_BRIDGE_METHODS = exports.BRIDGE_NAMESPACE = exports.BRIDGE_PROTOCOL_VERSION = void 0;
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "BRIDGE_PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_1.BRIDGE_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "BRIDGE_NAMESPACE", { enumerable: true, get: function () { return protocol_1.BRIDGE_NAMESPACE; } });
+Object.defineProperty(exports, "STACK_BRIDGE_METHODS", { enumerable: true, get: function () { return protocol_1.STACK_BRIDGE_METHODS; } });
+Object.defineProperty(exports, "FLUTTER_LEGACY_STACK_HANDLERS", { enumerable: true, get: function () { return protocol_1.FLUTTER_LEGACY_STACK_HANDLERS; } });
+Object.defineProperty(exports, "FLUTTER_UNIFIED_HANDLER", { enumerable: true, get: function () { return protocol_1.FLUTTER_UNIFIED_HANDLER; } });
+Object.defineProperty(exports, "RN_BRIDGE_HANDLER", { enumerable: true, get: function () { return protocol_1.RN_BRIDGE_HANDLER; } });
+Object.defineProperty(exports, "createBridgeId", { enumerable: true, get: function () { return protocol_1.createBridgeId; } });
+Object.defineProperty(exports, "createBridgeEnvelope", { enumerable: true, get: function () { return protocol_1.createBridgeEnvelope; } });
+Object.defineProperty(exports, "isBridgeEnvelope", { enumerable: true, get: function () { return protocol_1.isBridgeEnvelope; } });
+Object.defineProperty(exports, "parseBridgeMessage", { enumerable: true, get: function () { return protocol_1.parseBridgeMessage; } });
+Object.defineProperty(exports, "serializeBridgeMessage", { enumerable: true, get: function () { return protocol_1.serializeBridgeMessage; } });
+var detect_host_1 = require("./detect-host");
+Object.defineProperty(exports, "detectBridgeHost", { enumerable: true, get: function () { return detect_host_1.detectBridgeHost; } });
+Object.defineProperty(exports, "isNativeBridgeHost", { enumerable: true, get: function () { return detect_host_1.isNativeBridgeHost; } });
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "createBridgeTransport", { enumerable: true, get: function () { return transport_1.createBridgeTransport; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "WebViewBridgeClient", { enumerable: true, get: function () { return client_1.WebViewBridgeClient; } });
+Object.defineProperty(exports, "createWebViewBridgeClient", { enumerable: true, get: function () { return client_1.createWebViewBridgeClient; } });
+var host_1 = require("./host");
+Object.defineProperty(exports, "installBridgeHost", { enumerable: true, get: function () { return host_1.installBridgeHost; } });
+Object.defineProperty(exports, "handleBridgeMessage", { enumerable: true, get: function () { return host_1.handleBridgeMessage; } });
+Object.defineProperty(exports, "emitBridgeEnvelope", { enumerable: true, get: function () { return host_1.emitBridgeEnvelope; } });
+var stack_router_bridge_1 = require("./stack-router-bridge");
+Object.defineProperty(exports, "createStackRouterBridge", { enumerable: true, get: function () { return stack_router_bridge_1.createStackRouterBridge; } });
+Object.defineProperty(exports, "getStackRouterBridge", { enumerable: true, get: function () { return stack_router_bridge_1.getStackRouterBridge; } });
+Object.defineProperty(exports, "installStackRouterBridge", { enumerable: true, get: function () { return stack_router_bridge_1.installStackRouterBridge; } });
+var WebViewBridgeProvider_1 = require("./WebViewBridgeProvider");
+Object.defineProperty(exports, "WebViewBridgeProvider", { enumerable: true, get: function () { return WebViewBridgeProvider_1.WebViewBridgeProvider; } });

package/dist/bridge/protocol.d.ts

@@ -0,0 +1,51 @@
+/** WebViewKit native bridge protocol (v1) */
+export declare const BRIDGE_PROTOCOL_VERSION: 1;
+export declare const BRIDGE_NAMESPACE: "webviewkit";
+export type BridgeHostKind = "react-native" | "flutter" | "browser" | "unknown";
+/** Stack navigation — maps to common `stackPush` / `stackPop` WebView handlers */
+export declare const STACK_BRIDGE_METHODS: {
+    readonly PUSH: "stack.push";
+    readonly REPLACE: "stack.replace";
+    readonly POP: "stack.pop";
+    readonly RESET: "stack.reset";
+};
+export type StackBridgeMethod = (typeof STACK_BRIDGE_METHODS)[keyof typeof STACK_BRIDGE_METHODS];
+export type StackMeta = Record<string, unknown> | null;
+export type StackPushPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+export type StackReplacePayload = StackPushPayload;
+export type StackResetPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+export type BridgeErrorBody = {
+    code: string;
+    message: string;
+};
+export type BridgeEnvelope<TPayload = unknown> = {
+    v: typeof BRIDGE_PROTOCOL_VERSION;
+    ns: typeof BRIDGE_NAMESPACE;
+    id: string;
+    method: string;
+    payload?: TPayload;
+    error?: BridgeErrorBody;
+};
+export declare function createBridgeId(): string;
+export declare function createBridgeEnvelope<TPayload>(method: string, payload?: TPayload, id?: string): BridgeEnvelope<TPayload>;
+export declare function isBridgeEnvelope(value: unknown): value is BridgeEnvelope;
+export declare function parseBridgeMessage(raw: string | unknown): BridgeEnvelope | null;
+export declare function serializeBridgeMessage(msg: BridgeEnvelope): string;
+/** Flutter InAppWebView legacy handler names */
+export 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 */
+export declare const FLUTTER_UNIFIED_HANDLER = "webviewkitBridge";
+/** React Native receives messages via this global handler name suggestion */
+export declare const RN_BRIDGE_HANDLER = "webviewkitBridge";
+//# sourceMappingURL=protocol.d.ts.map

package/dist/bridge/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/bridge/protocol.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAClD,eAAO,MAAM,gBAAgB,EAAG,YAAqB,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhF,kFAAkF;AAClF,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AACnD,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,cAAc,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC/C,CAAC,EAAE,OAAO,uBAAuB,CAAC;IAClC,EAAE,EAAE,OAAO,gBAAgB,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CAKvC;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAC3C,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,QAAQ,EAClB,EAAE,CAAC,EAAE,MAAM,GACV,cAAc,CAAC,QAAQ,CAAC,CAQ1B;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CASxE;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAAG,OAAO,GACpB,cAAc,GAAG,IAAI,CAQvB;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAElE;AAED,gDAAgD;AAChD,eAAO,MAAM,6BAA6B;;;;;CAKhC,CAAC;AAEX,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,qBAAqB,CAAC"}