Environment-aware shim for `next/navigation` app-router hooks. Provides lightweight `window.location`/History API fallbacks so library components work outside a Next.js host, with opt-in delegation to real `next/navigation` exports via `registerNavigation`. ## Key Components | Export | Description | |---|---| | `registerNavigation(nav)` | Merges real `next/navigation` exports into the registry. Call once at app init in a Next.js host. | | `useRouter()` | Returns a router stub; fallback uses `pushState`/`replaceState` + synthetic `popstate` for SPA navigation without page reloads. Cross-origin and malformed hrefs fall back to `window.location`. | | `usePathname()` | Returns `window.location.pathname`, subscribed to `popstate`. | | `useSearchParams()` | Returns a `URLSearchParams` view of `window.location.search`, subscribed to `popstate`. | | `useParams()` | Returns `{}` — embedders needing dynamic params should parse from `usePathname()`. | | `redirect()` / `permanentRedirect()` | Best-effort via `window.location.assign` / `.replace`. | | `notFound()` | Throws an error in non-Next environments. | | `RedirectType` | Mirrors Next's `RedirectType` enum (`push` / `replace`). | | `ServerInsertedHTMLContext` | Stub (`null`) so consumers can import without crashing. | | `NavigationImpl` | Interface describing the full registration surface; all fields are optional. | ## Usage Example **In a Next.js host — register once at app init:** ```typescript // lib/embed-shim-registration.ts import { useRouter, usePathname, useSearchParams, useParams, redirect, permanentRedirect, notFound, } from 'next/navigation' import { registerNavigation } from '@flamingo-stack/openframe-oss-lib/embed-shims' registerNavigation({ useRouter, usePathname, useSearchParams, useParams, redirect, permanentRedirect, notFound, }) ``` **In a standalone/embed environment — no setup required:** ```typescript // Works out of the box using History API fallbacks import { useRouter, useSearchParams } from '@flamingo-stack/openframe-oss-lib/next-navigation' function MyComponent() { const router = useRouter() const params = useSearchParams() // SPA navigation — no document reload, popstate fires, subscribers re-render return router.replace('?page=2')}>Next } ``` > **Note:** The fallback `usePathname` / `useSearchParams` hooks react to `popstate` events. Programmatic `pushState`/`replaceState` calls outside this shim will NOT trigger re-renders — register a real router or use the shim's own `useRouter` for mutations. ## Source [`next-navigation.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/next-navigation.tsx)