Unified navigation execution primitive that centralizes all navigation actions — new-tab vs. same-tab, internal vs. external, embed vs. host, and runtime/router/window fallback chain — into a single module consumed by every interactive surface in the library. ## Key Components ### Interfaces - **`NavClickEvent`** — Minimal structural mouse-event interface (subset of `React.MouseEvent`) so chip buttons and tiles can call the handler without casting. - **`ExecuteNavigationClickArgs`** — Arguments for the click-handler form: event, runtime, `href`, optional `path`, `targetPlatform`, and `fallbackNavigate`. - **`ExecuteNavigationImperativeArgs`** — Arguments for the imperative form: same as above minus the event. ### Functions - **`runNavigation`** *(internal)* — Core decision engine. Computes new-tab vs. same-tab, routes same-page hash anchors through `navigateSamePageHash`, delegates to `runtime.navigation.navigate`, and falls back to `fallbackNavigate` or `window.location.assign`. - **`executeNavigation`** — Click-handler form. Skips modifier/non-primary clicks (returning `false` so the browser handles them natively), calls `preventDefault`, then delegates to `runNavigation`. Returns `true` when it took action. - **`executeNavigationImperative`** — Imperative form for buttons, list rows, and post-action redirects. Same decision tree, no event/modifier logic. ## Usage Example ```typescript // Click-handler form (anchor / chip) import { executeNavigation } from './execute-navigation' function ChatCard({ href, runtime }) { return ( executeNavigation({ event, runtime, href, targetPlatform: 'web' }) } > Open ) } // Imperative form (button / post-submit redirect) import { executeNavigationImperative } from './execute-navigation' function handleFormSuccess(runtime, href) { executeNavigationImperative({ runtime, href, fallbackNavigate: router.push, // useRouter().push }) } ``` > **No runtime?** Pass `null` — the module skips the new-tab/embed decision and falls back to `window.location.assign` (or your `fallbackNavigate`). Safe for surfaces like announcement bars that have no `ChatRuntimeContext`.