@pmate/bridge 0.1.11 → 0.1.12

package/README.md

@@ -43,3 +43,32 @@ await startup.ready()
 ```
 
 `startup.getState()` and `startup.ready()` resolve `{ supported, visible }`. The first ready call closes the native launch splash; repeat calls, OAuth returns and foreground transitions cannot reopen it. Auth must report ready when an interactive login form or terminal error is rendered, and must not report ready during a silent redirect. Non-native environments and hosts explicitly rejecting this optional method return unsupported; other failures are surfaced. Hosts enforce their trusted-page bridge boundary and provide an actionable startup failure when readiness never arrives.
+
+## Navigation (optional React Router integration)
+
+### Background
+
+Most links should stay within the current WebView and use the application's Router. A few hierarchical pages benefit from native transitions and interactive back gestures. The independent `@pmate/bridge/navigation` entry integrates React Router without importing it from the main Bridge entry. Install React and React Router `^6.22.1 || ^7.0.0` in the consuming application; React Router is an optional peer for consumers that do not use this entry.
+
+```tsx
+import { useNavigation } from "@pmate/bridge/navigation"
+
+function ChatLink() {
+  const navigation = useNavigation() // inside your React Router
+  return <button onClick={() => {
+    void navigation.navigate("/chat/123", { presentation: "push" }).catch(showError)
+  }}>Open chat</button>
+}
+```
+
+- `navigate(to, options?)` defaults to `presentation: "current"`, preserving React Router To/options, relative routes, replace and history state.
+- `navigate("/chat/123?tab=messages#latest", { presentation: "push" })` requests a new native page, preserving the Router basename/hash href. Native push requires a root-relative application path (not an external URL or route-relative path); it accepts no Router-only options such as `state`, `relative` or `replace`. New pages must restore everything they need from their URL and shared application session.
+- `replace(to, options?)` replaces the current Router entry.
+- `back()` navigates back in the current Router only.
+- `close()` pops the current native page. In browsers, older hosts or the native root, it invokes Router back. Applications must choose a suitable destination for a root back button rather than relying on history always containing a previous entry.
+
+All methods return `Promise<void>` so callers can handle native failures. The fallback is used only when there is no bridge, `navigation.getState` explicitly reports unsupported, or an older host explicitly reports that method missing. Unexpected errors, malformed responses and failed native actions reject; they never trigger a second Router navigation. Repeated in-flight native pushes reject.
+
+Native protocol: `navigation.getState` returns `{ supported, canClose }`; `navigation.push({url})` confirms `{opened:true}` and `navigation.close()` confirms `{closed:true}`. URL validation and document/frame origin checks also run natively. iOS hosts wrap their root `PmateWebViewController` in `PmatePageNavigationController`; Merry does this by default. Other iOS integrations without this wrapper report unsupported and retain Router behavior. Android pages use separate Activities in the existing task. Closing restores the retained parent WebView. This API does not synchronize business state between documents or convert existing Router links automatically.
+
+Run `bun test packages/bridge/tests`, `pnpm exec tsc -p packages/bridge/tsconfig.json`, and `pnpm --filter @pmate/bridge exec playwright test` from the workspace.

package/package.json

@@ -1,25 +1,35 @@
 {
   "name": "@pmate/bridge",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "files": [
     "src",
     "global.d.ts"
   ],
   "types": "./global.d.ts",
   "peerDependencies": {
-    "react": "*"
+    "react": "*",
+    "react-router": "^6.22.1 || ^7.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-router": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/react": "^19.2.7",
-    "react": "^19.1.1"
+    "react": "^19.1.1",
+    "react-router": "^6.22.1",
+    "@playwright/test": "1.60.0",
+    "react-dom": "^19.1.1",
+    "@remix-run/router": "^1.23.3",
+    "vite": "^7.3.1"
   },
   "main": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./navigation": "./src/navigation/index.ts"
   }
 }

package/src/navigation/core.ts

@@ -0,0 +1,62 @@
+import type { NavigateFunction, NavigateOptions, To } from "react-router"
+
+export type NavigationOptions = NavigateOptions & { presentation?: "current" }
+export type PushOptions = { presentation: "push" }
+export interface Navigation {
+  navigate(to: To, options?: NavigationOptions): Promise<void>
+  navigate(to: string, options: PushOptions): Promise<void>
+  replace(to: To, options?: Omit<NavigateOptions, "replace">): Promise<void>
+  back(): Promise<void>
+  close(): Promise<void>
+}
+export type NavigationState = { supported: boolean; canClose: boolean }
+type Bridge = { call(name: string, params?: unknown): Promise<unknown> }
+
+function bridge(): Bridge | undefined {
+  return typeof window === "undefined" ? undefined : (window as Window & { PmateBridge?: Bridge }).PmateBridge
+}
+
+async function state(host: Bridge): Promise<NavigationState> {
+  try {
+    const result = await host.call("navigation.getState") as NavigationState
+    if (typeof result?.supported !== "boolean" || typeof result.canClose !== "boolean") throw new Error("Invalid navigation bridge response")
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === "Bridge function not found: navigation.getState") return { supported: false, canClose: false }
+    throw error
+  }
+}
+
+/** Router integration is supplied by the hook; the native protocol never imports React Router. */
+export function createNavigation(routerNavigate: NavigateFunction, rootHref: string): Navigation {
+  let opening = false
+  return {
+    async navigate(to: To, options?: NavigationOptions | PushOptions) {
+      const { presentation = "current", ...routerOptions } = options ?? {}
+      if (presentation === "current") { await routerNavigate(to, routerOptions); return }
+      if (presentation !== "push") throw new Error("Invalid navigation presentation")
+      // A native page must be reconstructible from its URL, unlike history.state.
+      if (Object.keys(routerOptions).length) throw new Error("Native push does not accept Router options")
+      if (typeof to !== "string" || !to.startsWith("/") || to.startsWith("//") || to.includes("\\")) throw new Error("Native push requires an absolute application path starting with /")
+      if (opening) throw new Error("A native page is already opening")
+      opening = true
+      try {
+        const host = bridge()
+        if (!host || !(await state(host)).supported) { await routerNavigate(to); return }
+        const url = new URL(`${rootHref.replace(/\/?$/, "/")}${to.slice(1)}`, window.location.href)
+        if (url.origin !== window.location.origin || url.username || url.password) throw new Error("Native navigation must stay within the application origin")
+        const result = await host.call("navigation.push", { url: url.href }) as { opened: boolean }
+        if (result?.opened !== true) throw new Error("Native page opening was not confirmed")
+      } finally { opening = false }
+    },
+    async replace(to, options) { await routerNavigate(to, { ...options, replace: true }) },
+    async back() { await routerNavigate(-1) },
+    async close() {
+      const host = bridge()
+      const current = host ? await state(host) : undefined
+      if (!host || !current?.supported || !current.canClose) { await routerNavigate(-1); return }
+      const result = await host.call("navigation.close") as { closed: boolean }
+      if (result?.closed !== true) throw new Error("Native page closing was not confirmed")
+    },
+  }
+}

package/src/navigation/index.ts

@@ -0,0 +1,11 @@
+import { useMemo } from "react"
+import { useHref, useNavigate } from "react-router"
+import { createNavigation } from "./core"
+export type { Navigation, NavigationOptions, NavigationState, PushOptions } from "./core"
+
+/** Must be used inside the application's React Router, including its basename/hash configuration. */
+export function useNavigation() {
+  const navigate = useNavigate()
+  const rootHref = useHref("/")
+  return useMemo(() => createNavigation(navigate, rootHref), [navigate, rootHref])
+}