<!-- source-hash: 6464e6b8e81567378d067bf37a01cd1c -->
Environment-aware shim for `next/navigation` app-router hooks. Provides lightweight `window.location`-backed stubs by default, with an opt-in registration mechanism for full Next.js router integration in host applications.

## Key Components

### `registerNavigation(nav)`
Merges real `next/navigation` exports into the internal registry. Call once at app init in a Next.js host to enable full client-router integration.

### `NavigationImpl` (interface)
Describes the full set of registerable hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`, `redirect`, `permanentRedirect`, `notFound`.

### Exported Hooks & Utilities

| Export | Stub Behavior |
|---|---|
| `useRouter()` | `push`/`replace` → `window.location`; `back`/`forward` → `history`; `refresh` → `reload` |
| `usePathname()` | Returns `window.location.pathname`, popstate-subscribed |
| `useSearchParams()` | Returns `URLSearchParams` from `window.location.search`, popstate-subscribed |
| `useParams<T>()` | Returns `{}` — parse params from `usePathname()` manually |
| `redirect(url)` | `window.location.assign(url)` + throws |
| `permanentRedirect(url)` | `window.location.replace(url)` + throws |
| `notFound()` | Throws with shim message |
| `RedirectType` | Mirrors Next's enum (`push` / `replace`) |
| `ServerInsertedHTMLContext` | `null` stub — importable, non-functional |

## Usage Example

```typescript
// In a Next.js host — lib/embed-shim-registration.ts
import {
  useRouter, usePathname, useSearchParams,
  useParams, redirect, permanentRedirect, notFound,
} from 'next/navigation'
import { registerNavigation } from '@flamingo-stack/openframe-frontend-core/embed-shims'

// Call ONCE at app init — partial registration is safe
registerNavigation({
  useRouter,
  usePathname,
  useSearchParams,
  useParams,
  redirect,
  permanentRedirect,
  notFound,
})
```

```typescript
// In a lib component — works in both Next.js and standalone embed
import { usePathname, useSearchParams } from './next-navigation'

export function ActiveRoute() {
  const pathname = usePathname()
  const params = useSearchParams()
  return <span>{pathname}?{params.toString()}</span>
}
```

> **Note:** The fallback stubs only react to `popstate` events. Programmatic `pushState`/`replaceState` calls will **not** trigger re-renders without a registered real router.