@pmate/bridge 0.1.10 → 0.1.12

package/README.md

@@ -26,3 +26,49 @@ Desktop hosts expose a preload bridge separately from mobile WebViews. Applicati
 `getRuntimeInfo()` returns `environment` (`browser`, `electron`, or `native`), desktop `platform`, `appVersion`, `electronVersion` when supplied by the host, and `capabilities.openNotificationSettings`. Detection uses host injection, never the user agent; it is not an authorization boundary. Native device details remain available through `useDeviceInfo()`.
 
 `openNotificationSettings()` routes to the desktop host or native settings protocol and rejects on unavailable/failed operations. Electron notification permissions are managed by the OS: browser `Notification.permission` does not describe the main-process notification permission. Do not display browser permission prompts or claim OS permission is granted based on notification API support.
+
+## Startup splash
+
+### Background
+
+A native launch may keep its splash above session restoration and first-screen rendering. The web application reports business readiness instead of relying on a fixed timer or FCP. This optional capability is enabled by the host; it does not add a splash to other apps or browsers.
+
+```tsx
+import { startup, useStartupReady } from '@pmate/bridge'
+
+// In React: signal only after the intended screen is committed and can paint.
+const splash = useStartupReady(screenReady)
+// Or explicitly:
+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.10",
+  "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/index.ts

@@ -32,3 +32,5 @@ export type * from "./types"
 
 export { getRuntimeInfo, openNotificationSettings } from "./runtime"
 export type { RuntimeInfo } from "./runtime"
+export { startup, useStartupReady } from "./startup"
+export type { StartupState } from "./startup"

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])
+}

package/src/startup.ts

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react"
+
+export type StartupState = { supported: boolean; visible: boolean }
+type StartupWindow = Window & { PmateBridge?: { call: (name: string) => Promise<unknown> } }
+const unsupported: StartupState = { supported: false, visible: false }
+
+async function callStartup(name: "startup.getState" | "startup.ready"): Promise<StartupState> {
+  const bridge = typeof window === "undefined" ? undefined : (window as StartupWindow).PmateBridge
+  if (!bridge) return unsupported
+  try {
+    const state = await bridge.call(name) as StartupState
+    if (typeof state?.supported !== "boolean" || typeof state.visible !== "boolean") throw new Error("Invalid startup bridge response")
+    return state
+  } catch (error) {
+    // Older hosts explicitly reject this optional capability. Other failures matter.
+    if (error instanceof Error && error.message === `Bridge function not found: ${name}`) return unsupported
+    throw error
+  }
+}
+
+/** Startup belongs to the native launch, not to a document or OAuth navigation. */
+export const startup = {
+  getState: () => callStartup("startup.getState"),
+  ready: () => callStartup("startup.ready"),
+}
+
+/** Report business readiness after React commits and the browser can paint it. */
+export function useStartupReady(ready: boolean): StartupState {
+  const [state, setState] = useState<StartupState>(unsupported)
+  useEffect(() => {
+    let active = true
+    const read = () => { void startup.getState().then(value => { if (active) setState(value) }).catch(() => console.error("STARTUP_STATE_FAILED")) }
+    window.addEventListener("pmate:bridge-ready", read)
+    read()
+    return () => { active = false; window.removeEventListener("pmate:bridge-ready", read) }
+  }, [])
+  useEffect(() => {
+    if (!ready || !state.supported || !state.visible) return
+    let active = true
+    let nextFrame = 0
+    const frame = requestAnimationFrame(() => {
+      nextFrame = requestAnimationFrame(() => {
+        if (!active) return
+        void startup.ready().then(value => { if (active) setState(value) }).catch(() => console.error("STARTUP_READY_FAILED"))
+      })
+    })
+    return () => { active = false; cancelAnimationFrame(frame); cancelAnimationFrame(nextFrame) }
+  }, [ready, state.supported, state.visible])
+  return state
+}