@flamingo-stack/openframe-frontend-core 0.0.218 → 0.0.219

package/src/components/chat/hooks/use-chat-identity.ts

@@ -28,11 +28,20 @@
  *   3. The fetch is cheap and short — no perf justification for a
  *      cache layer
  *
+ * For INDEPENDENT surfaces that can't share identity through props because
+ * they live in different React subtrees (e.g. a persistent chat widget in
+ * the app shell + a tickets page in the router outlet), mount the optional
+ * `<ChatIdentityProvider>` (below) near the embed root. It lifts the SAME
+ * resolver into ONE shared resolution for the whole subtree — still no cache
+ * (see the provider's own doc), just the drill-from-parent pattern
+ * formalized as a provider. Omit it and every consumer self-fetches (the
+ * hub's behavior, unchanged).
+ *
  * Endpoint URL: read from `useRequiredChatRuntime().endpoints.identityUrl`
  * so embedded apps with their own reverse-proxy topology can override.
  */
 
-import { useEffect, useState } from 'react'
+import { createContext, createElement, useContext, useEffect, useState, type ReactNode } from 'react'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
 import { chatAuthedFetch } from '../utils/chat-authed-fetch'
 import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
@@ -86,7 +95,18 @@ const ANON_DEFAULTS: ChatIdentityResponse = {
   user: null,
 }
 
-export function useChatIdentity(): ChatIdentitySurface {
+/**
+ * Internal resolver — the actual fetch-into-state loop (plain
+ * `useEffect` + `useState`, the no-cache contract above). Shared by the
+ * standalone `useChatIdentity` hook AND `ChatIdentityProvider`.
+ *
+ * `enabled === false` short-circuits the fetch. `useChatIdentity` passes
+ * `enabled = false` whenever a `ChatIdentityProvider` is already resolving
+ * identity above it, so the consumer reads the provider's single resolution
+ * instead of issuing the duplicate request we're eliminating. The resolver
+ * is still called unconditionally (Rules of Hooks); only its effect bails.
+ */
+function useResolveChatIdentity(enabled: boolean): ChatIdentitySurface {
   const runtime = useRequiredChatRuntime()
   const url = runtime.endpoints.identityUrl
   // `getChatProxyAuth()` reads localStorage every render. If the user
@@ -95,9 +115,13 @@ export function useChatIdentity(): ChatIdentitySurface {
   const proxyEmail = getChatProxyAuth()?.email ?? null
 
   const [data, setData] = useState<ChatIdentityResponse>(ANON_DEFAULTS)
-  const [isLoading, setIsLoading] = useState(true)
+  // Only "loading" if THIS instance will actually fetch. A disabled
+  // consumer (provider present) is never loading — its value comes from
+  // context, not from this idle resolver.
+  const [isLoading, setIsLoading] = useState(enabled)
 
   useEffect(() => {
+    if (!enabled) return
     let cancelled = false
     const ctrl = new AbortController()
 
@@ -129,8 +153,50 @@ export function useChatIdentity(): ChatIdentitySurface {
     }
     // `proxyEmail` in deps → refetch the moment the user pastes creds
     // (or rotates them) and triggers a re-render. `url` is stable for
-    // the chat session but listed for completeness.
-  }, [url, proxyEmail])
+    // the chat session but listed for completeness. `enabled` is stable
+    // per tree (a provider is either mounted above or it isn't).
+  }, [url, proxyEmail, enabled])
 
   return { ...data, isLoading }
 }
+
+/**
+ * Optional shared-identity context. When a `<ChatIdentityProvider>` is
+ * mounted above, every `useChatIdentity()` in the subtree reads this ONE
+ * resolution. `null` (no provider) → consumers self-resolve, which is the
+ * default and exactly what the hub does today (unchanged).
+ */
+const ChatIdentityContext = createContext<ChatIdentitySurface | null>(null)
+
+/**
+ * Opt-in identity provider. Resolves the identity capability bag ONCE for
+ * its whole subtree and shares it via context.
+ *
+ * This is the "drill from a parent" pattern (above) lifted to a provider —
+ * so INDEPENDENT surfaces in different React subtrees (a persistent chat
+ * widget in the app shell + a tickets page in the router outlet) share a
+ * single `/identity` resolution instead of each fetching their own. It is
+ * NOT the reverted client cache: just one lifted `useState`/`useEffect`
+ * (the same resolver the standalone hook uses), so it still refetches on
+ * credential rotation (`proxyEmail`) and never persists stale identity.
+ *
+ * Mount once near the embed root, INSIDE your `ChatRuntimeContext.Provider`
+ * (the resolver reads `runtime.endpoints.identityUrl`). Omit it and every
+ * `useChatIdentity()` self-fetches as before.
+ */
+export function ChatIdentityProvider({ children }: { children: ReactNode }) {
+  const identity = useResolveChatIdentity(true)
+  // `createElement` (not JSX) keeps this module a `.ts` file alongside the
+  // hook + response types — no `.tsx` rename, no orphaned doc sidecar.
+  return createElement(ChatIdentityContext.Provider, { value: identity }, children)
+}
+
+export function useChatIdentity(): ChatIdentitySurface {
+  // Read a provider's shared resolution when present; otherwise self-resolve.
+  // The resolver is ALWAYS called (Rules of Hooks) but its fetch is disabled
+  // when a provider supplies identity, so there is no duplicate request — the
+  // provider's value wins.
+  const provided = useContext(ChatIdentityContext)
+  const selfResolved = useResolveChatIdentity(provided === null)
+  return provided ?? selfResolved
+}

package/src/components/chat/hooks/use-sse-chat-adapter.ts

@@ -13,10 +13,11 @@
  *
  * Two key contracts vs hub-side chat hooks:
  *
- *   1. `source` is READ FROM THE RUNTIME, not a parameter. Throws loudly
- *      if `runtime.source` is empty so embedders that forget to wire
- *      identity get an immediate signal rather than a silently-empty
- *      localStorage namespace.
+ *   1. `source` is READ FROM THE RUNTIME, not a parameter. It is OPTIONAL —
+ *      platform-agnostic embedders leave it unset; an empty `source` falls back
+ *      to a stable constant (`DEFAULT_CHAT_SOURCE`) for the localStorage history
+ *      namespace. It is NEVER sent on the wire (the hub resolves source
+ *      server-side via `currentPlatform()`).
  *
  *   2. Navigation is runtime-provided. The hub-side `useDocSearch` keeps
  *      its own `decideNewTab` + `useDocNavigation.navigate` plumbing for
@@ -579,6 +580,11 @@ function mergeTurnMeta(
 
 const CHAT_STORAGE_VERSION = 1
 
+/** localStorage history namespace used when no `source` is configured on the
+ *  runtime. Embedders are platform-agnostic (see `ChatRuntime.source`), so any
+ *  stable string works here — the hub passes its real platform instead. */
+const DEFAULT_CHAT_SOURCE = 'embed'
+
 /** Storage key — includes the proxy-auth impersonation email when
  *  present so each impersonated customer keeps a SEPARATE chat history. */
 const chatStorageKey = (source: DocSource): string => {
@@ -668,7 +674,8 @@ function savePersistedChat(source: DocSource, state: PersistedChatState) {
  * decision) the lib's `<ChatContainer>` consumes.
  *
  * Source identity comes from `useRequiredChatRuntime().source` — no
- * parameter. Throws if `runtime.source` is empty.
+ * parameter. An empty `source` falls back to `DEFAULT_CHAT_SOURCE` (used only for
+ * the localStorage history namespace; never sent on the wire).
  */
 export function useSseChatAdapter(
   options?: UseSseChatAdapterOptions,
@@ -676,15 +683,12 @@ export function useSseChatAdapter(
   // Chat-specific code REQUIRES a runtime — the lib's `<HubRuntimeProvider>`
   // (hub) / embedder's provider must wrap the tree.
   const runtime = useRequiredChatRuntime()
-  const source = runtime.source
-  if (!source) {
-    throw new Error(
-      '[useSseChatAdapter] runtime.source is required — got empty string. ' +
-        'Wire `source` on your <ChatRuntimeContext.Provider value={...}>. ' +
-        'Hub default: <HubRuntimeProvider source={currentPlatform()}>; ' +
-        'embedded apps: pass your own platform/tenant identifier.',
-    )
-  }
+  // `source` is OPTIONAL — embedders are platform-agnostic (see ChatRuntime.source).
+  // Here it's used ONLY for the localStorage history namespace + client-side meta
+  // labels; it is NEVER sent on the wire (the hub resolves source server-side via
+  // currentPlatform()). Fall back to a stable constant so the persistence key stays
+  // well-formed when the embedder leaves source unset.
+  const source = runtime.source || DEFAULT_CHAT_SOURCE
   // Fall back to the lib-baked hub-canonical map when the embedder
   // didn't supply an override. Keeps Ask + Display working in any
   // mount that doesn't have a custom documentType registry. Embedders

package/src/components/chat/nav-link-anchor-via-runtime.tsx

@@ -24,6 +24,7 @@
 
 import type { ReactNode, MouseEvent } from 'react'
 import { useRequiredChatRuntime } from '../../contexts/chat-runtime-context'
+import { useRouter } from '../../embed-shims/next-navigation'
 import { handleChatNavClick } from './utils/nav-click-handler'
 import { resolveHrefForRuntime } from './utils/chat-nav-resolution'
 import { computeIsNewTab, newTabAnchorAttrs } from './utils/nav-anchor-props'
@@ -47,6 +48,7 @@ export function NavLinkAnchorViaRuntime({
   children,
 }: NavLinkAnchorViaRuntimeProps) {
   const runtime = useRequiredChatRuntime()
+  const router = useRouter()
   const panel = useChatPanel()
   const resolvedHref = resolveHrefForRuntime(href, runtime)
   const isNewTab = computeIsNewTab(runtime, resolvedHref, targetPlatform ?? null)
@@ -56,7 +58,7 @@ export function NavLinkAnchorViaRuntime({
       href: resolvedHref,
       path,
       targetPlatform,
-    })
+    }, router.push)
     if (handled && !isNewTab && panel?.closeChat) panel.closeChat()
   }
   return (

package/src/components/chat/types/component.types.ts

@@ -34,6 +34,12 @@ export interface ChatHeaderTicketInfo {
   title: React.ReactNode
   meta?: React.ReactNode
   status?: string
+  /** Lifecycle (custom-status) display name. */
+  statusName?: string
+  /** Lifecycle (custom-status) hex color, used when the kind isn't canonical. */
+  statusColor?: string
+  /** Lifecycle (custom-status) kind — drives canonical-vs-color styling. */
+  statusKind?: string
 }
 
 export interface ChatHeaderProps extends HTMLAttributes<HTMLDivElement> {
@@ -287,7 +293,7 @@ export interface ChatInputProps extends Omit<TextareaHTMLAttributes<HTMLTextArea
   /** Source-compatible widening: returning `false` (or a Promise resolving to
    *  `false`) tells the input to KEEP the draft (e.g. a failed send). `void` /
    *  `true` clears as before — preserves every existing caller's behavior. */
-  onSend?: (message: string) => void | boolean | Promise<boolean>
+  onSend?: (message: string) => void | boolean | Promise<boolean | void>
   onStop?: () => void | Promise<void>
   sending?: boolean
   awaitingResponse?: boolean

package/src/components/chat/utils/__tests__/source-row-cta.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import { resolveSourceRowCTA } from '../source-row-cta'
+import { getBaseUrl } from '../../../../utils/cn'
+
+/**
+ * Doc-chip CTA resolution — the per-`documentType` `docPlatformTargets` path (the
+ * unified, dynamic mechanism) plus the legacy `chipBasePlatform` / in-app `baseRoute`
+ * fallbacks. The headline guarantee: a chat surfacing MULTIPLE doc sources routes EACH
+ * row to its own home — something a single static fallback cannot do.
+ */
+describe('resolveSourceRowCTA — doc-chip platform routing', () => {
+  const markdownRow = {
+    documentType: 'markdown',
+    id: 'd1',
+    title: 'Install guide',
+    path: 'getting-started/install',
+  }
+  const dataRoomRow = {
+    documentType: 'data_room_doc',
+    id: 'd2',
+    title: 'Cap table',
+    path: 'financials/cap-table.pdf',
+  }
+
+  const docPlatformTargets = {
+    markdown: { platform: 'flamingo', basePath: 'knowledge-base' },
+    data_room_doc: { platform: 'company-hub', basePath: 'data-room' },
+  }
+
+  const expectHref = (platform: string, base: string, path: string) =>
+    new URL(path, `${getBaseUrl(platform)}/${base}/`).toString()
+
+  it('routes EACH doc source to its own platform from ONE shared context (mixed sources)', () => {
+    const md = resolveSourceRowCTA(markdownRow, { docPlatformTargets })
+    const dr = resolveSourceRowCTA(dataRoomRow, { docPlatformTargets })
+
+    expect(md.href).toBe(expectHref('flamingo', 'knowledge-base', 'getting-started/install'))
+    expect(md.targetPlatform).toBe('flamingo')
+
+    expect(dr.href).toBe(expectHref('company-hub', 'data-room', 'financials/cap-table.pdf'))
+    expect(dr.targetPlatform).toBe('company-hub')
+  })
+
+  it('tolerates leading/trailing slashes in basePath', () => {
+    const md = resolveSourceRowCTA(markdownRow, {
+      docPlatformTargets: { markdown: { platform: 'flamingo', basePath: '/knowledge-base/' } },
+    })
+    expect(md.href).toBe(expectHref('flamingo', 'knowledge-base', 'getting-started/install'))
+  })
+
+  it('docPlatformTargets WINS over the legacy chipBasePlatform', () => {
+    const md = resolveSourceRowCTA(markdownRow, { docPlatformTargets, chipBasePlatform: 'openframe' })
+    expect(md.targetPlatform).toBe('flamingo')
+  })
+
+  it('falls back to chipBasePlatform (legacy single) when no docPlatformTargets — hub parity', () => {
+    const md = resolveSourceRowCTA(markdownRow, { chipBasePlatform: 'flamingo' })
+    expect(md.href).toBe(expectHref('flamingo', 'knowledge-base', 'getting-started/install'))
+    expect(md.targetPlatform).toBe('flamingo')
+  })
+
+  it('falls back to an in-app relative path from baseRoute (host serves the viewer)', () => {
+    const md = resolveSourceRowCTA(markdownRow, { baseRoute: '/data-room', currentPlatform: 'openmsp' })
+    expect(md.href).toBe('/data-room/getting-started/install')
+    expect(md.targetPlatform).toBe('openmsp')
+  })
+
+  it('no target configured → no href (Ask-only) but still askable', () => {
+    const md = resolveSourceRowCTA(markdownRow, {})
+    expect(md.href).toBeNull()
+    expect(md.askable).toBe(true)
+  })
+
+  it('a doc row WITH a public externalUrl skips doc routing and uses the URL verbatim', () => {
+    const md = resolveSourceRowCTA({ ...markdownRow, externalUrl: 'https://example.com/x' }, { docPlatformTargets })
+    expect(md.href).toBe('https://example.com/x')
+  })
+})

package/src/components/chat/utils/execute-navigation.ts

@@ -0,0 +1,127 @@
+'use client'
+
+/**
+ * THE single navigation-EXECUTION primitive for the whole lib.
+ *
+ * Link BUILDING is unified by `composeContentUrl`; the new-tab DECISION is
+ * unified by `computeIsNewTab`/`decideNewTab`. This is the third leg: ONE place
+ * that EXECUTES a navigation — encoding new-tab-vs-same-tab + internal-vs-external
+ * + embed-vs-host + the runtime-then-router-then-window fallback chain. Every
+ * surface routes through it:
+ *   - chat cards / chips / markdown links → `executeNavigation` (click form),
+ *     via the thin `handleChatNavClick` wrapper.
+ *   - buttons / page rows / form redirects → `executeNavigationImperative` directly.
+ *
+ * Decision tree (the SAME one `handleChatNavClick` used — copied verbatim so
+ * behavior is byte-identical; the hub's chat-click behavior MUST NOT change):
+ *   1. empty href → no-op (click form preventDefaults + reports handled)
+ *   2. (click form) modifier / non-primary button → NOT handled — let the
+ *      browser do its native thing (`<a>` opens a new tab, etc.)
+ *   3. `computeIsNewTab` true → `runtime.navigation.openExternal(href)` else
+ *      `window.open(href, '_blank', noopener,noreferrer)`
+ *   4. else (same-tab) → `runtime.navigation.navigate({href,path,targetPlatform})`;
+ *      if the host didn't handle it → `fallbackNavigate(stripped)` else
+ *      `window.location.assign(stripped)`
+ *
+ * `runtime` is nullable: surfaces with no `ChatRuntimeContext` mounted (e.g. the
+ * announcement bar) pass `null` and get the plain same-tab fallback — there's no
+ * new-tab/embed decision to make without a runtime.
+ */
+
+import { computeIsNewTab } from './nav-anchor-props'
+import { NEW_TAB_FEATURES, stripSameOriginToPath } from './chat-nav-resolution'
+import type { ChatRuntime } from '../../../contexts/chat-runtime-context'
+
+/** Minimal mouse-event surface — structural so chip buttons / tiles can call it
+ *  without casting `React.MouseEvent`. */
+export interface NavClickEvent {
+  preventDefault(): void
+  button?: number
+  metaKey?: boolean
+  ctrlKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+}
+
+export interface ExecuteNavigationClickArgs {
+  event: NavClickEvent
+  runtime: ChatRuntime | null | undefined
+  href: string
+  path?: string | null
+  targetPlatform?: string | null
+  /** Host router fallback for same-origin soft-nav when the runtime doesn't wire
+   *  `navigation.navigate` — pass `useRouter().push`. Without it, falls back to a
+   *  full-page `window.location.assign`. */
+  fallbackNavigate?: (path: string) => void
+}
+
+export interface ExecuteNavigationImperativeArgs {
+  runtime: ChatRuntime | null | undefined
+  href: string
+  targetPlatform?: string | null
+  fallbackNavigate?: (path: string) => void
+}
+
+/** Core: make the new-tab decision (when a runtime is present) and execute. */
+function runNavigation(
+  runtime: ChatRuntime | null | undefined,
+  href: string,
+  path: string | null | undefined,
+  targetPlatform: string | null | undefined,
+  fallbackNavigate?: (path: string) => void,
+): void {
+  // No runtime → no embed/new-tab decision possible; plain same-tab fallback.
+  const isNewTab = runtime ? computeIsNewTab(runtime, href, targetPlatform ?? null) : false
+  if (isNewTab) {
+    if (runtime?.navigation.openExternal) runtime.navigation.openExternal(href)
+    else window.open(href, '_blank', NEW_TAB_FEATURES)
+    return
+  }
+  const handled = runtime?.navigation.navigate?.({ href, path, targetPlatform }) ?? false
+  if (!handled) {
+    const target = stripSameOriginToPath(href)
+    if (fallbackNavigate) fallbackNavigate(target)
+    else window.location.assign(target)
+  }
+}
+
+/**
+ * Click-handler form. Returns `true` when it took action (called
+ * `preventDefault`); `false` for modifier / non-primary clicks the browser
+ * should handle natively. Spread the result into your anchor's `onClick`.
+ */
+export function executeNavigation({
+  event,
+  runtime,
+  href,
+  path,
+  targetPlatform,
+  fallbackNavigate,
+}: ExecuteNavigationClickArgs): boolean {
+  if (!href) {
+    event.preventDefault()
+    return true
+  }
+  // Modifier / non-primary clicks → NOT handled; let the browser do its native thing.
+  // Deliberately NOT the shared `isModifierClick` (chat-nav-resolution): that predicate
+  // treats an UNDEFINED `button` as a modifier (`button !== 0`), but a structural
+  // NavClickEvent from a chip tile may omit `button` and MUST be a primary click (navigate).
+  if (event.button !== undefined && event.button !== 0) return false
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false
+  event.preventDefault()
+  runNavigation(runtime, href, path, targetPlatform, fallbackNavigate)
+  return true
+}
+
+/**
+ * Imperative form — for buttons, list-row onClicks, and post-action redirects
+ * that aren't anchor clicks. Same decision tree, no event/modifier handling.
+ */
+export function executeNavigationImperative({
+  runtime,
+  href,
+  targetPlatform,
+  fallbackNavigate,
+}: ExecuteNavigationImperativeArgs): void {
+  runNavigation(runtime, href, undefined, targetPlatform, fallbackNavigate)
+}

package/src/components/chat/utils/index.ts

@@ -48,6 +48,16 @@ export {
   handleChatNavClick,
   type ChatNavClickInput,
 } from './nav-click-handler'
+// The unified navigation-execution primitive — single source of truth for
+// new-tab/same-tab + internal/external + embed/host + the runtime→router→window
+// fallback. Every surface routes through it (handleChatNavClick is now a wrapper).
+export {
+  executeNavigation,
+  executeNavigationImperative,
+  type ExecuteNavigationClickArgs,
+  type ExecuteNavigationImperativeArgs,
+  type NavClickEvent,
+} from './execute-navigation'
 export {
   computeIsNewTab,
   newTabAnchorAttrs,

package/src/components/chat/utils/nav-click-handler.ts

@@ -1,34 +1,19 @@
+'use client'
+
 /**
- * Pure click-handler helper for chat-rendered nav links.
- *
- * Single click router shared by:
- *   - The chip block inside EmbeddableChat
- *   - `<ChatCardNavWrap>` inside the entity-card dispatcher
- *   - `<NavLinkAnchorViaRuntime>` (markdown-body anchor wrapper)
- *
- * Returns `true` when the handler took action (called preventDefault); the
- * caller can treat that as "I handled it" and skip any further routing.
- * Returns `false` for modifier-clicks / non-primary buttons — those pass
- * through to the browser's default behavior (open in new tab, etc.).
+ * Click router for chat-rendered nav links — chip block, `<ChatCardNavWrap>`,
+ * `<NavLinkAnchorViaRuntime>`.
  *
- * The new-tab decision (`computeIsNewTab` — embed-mode short-circuit +
- * `runtime.navigation.decideNewTab` + lib fallback) is the single source
- * of truth and is consumed here directly. No caller needs to duplicate
- * the embed-vs-host logic.
- *
- * Routing rules:
- *   - Empty href → preventDefault + return true (no-op nav)
- *   - Non-primary mouse button OR any modifier key → return false (let
- *     the browser handle it; `<a>` semantics take over)
- *   - new-tab (`computeIsNewTab` true) → `runtime.navigation.openExternal`
- *     or `window.open(href, '_blank')`. Covers embed mode and
- *     cross-platform host mode uniformly.
- *   - same-tab → `runtime.navigation.navigate?.(…)` → fallback
- *     `window.location.assign(stripSameOriginToPath(href))`
+ * @deprecated Thin wrapper around the unified `executeNavigation` primitive
+ * (`execute-navigation.ts`). Kept so the existing chat callers' call shape
+ * (`handleChatNavClick(e, runtime, {href,path,targetPlatform}, fallbackNavigate)`)
+ * keeps working unchanged. New code should call `executeNavigation` directly.
+ * The decision tree (empty-href no-op, modifier/non-primary passthrough,
+ * new-tab via openExternal/window.open, same-tab via navigate→fallback→
+ * window.location) lives ONCE in `executeNavigation` now.
  */
 
-import { computeIsNewTab } from './nav-anchor-props'
-import { NEW_TAB_FEATURES, stripSameOriginToPath } from './chat-nav-resolution'
+import { executeNavigation, type NavClickEvent } from './execute-navigation'
 import type { ChatRuntime } from '../../../contexts/chat-runtime-context'
 
 export interface ChatNavClickInput {
@@ -37,45 +22,13 @@ export interface ChatNavClickInput {
   targetPlatform?: string | null
 }
 
-/**
- * Minimal mouse-event surface the click handler needs. Accepting a
- * structural type rather than `React.MouseEvent<HTMLAnchorElement>` keeps
- * the helper callable from non-anchor surfaces (chip buttons, tile
- * containers) without forcing a cast.
- */
-interface NavClickEvent {
-  preventDefault(): void
-  button?: number
-  metaKey?: boolean
-  ctrlKey?: boolean
-  shiftKey?: boolean
-  altKey?: boolean
-}
-
 export function handleChatNavClick(
   e: NavClickEvent,
   runtime: ChatRuntime,
   { href, path, targetPlatform }: ChatNavClickInput,
+  /** Host-router fallback for same-origin soft-nav when the runtime does NOT
+   *  wire `navigation.navigate` (pass `useRouter().push`). */
+  fallbackNavigate?: (path: string) => void,
 ): boolean {
-  if (!href) {
-    e.preventDefault()
-    return true
-  }
-  if (e.button !== undefined && e.button !== 0) return false
-  if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return false
-
-  e.preventDefault()
-  const isNewTab = computeIsNewTab(runtime, href, targetPlatform ?? null)
-  if (isNewTab) {
-    if (runtime.navigation.openExternal) {
-      runtime.navigation.openExternal(href)
-    } else {
-      window.open(href, '_blank', NEW_TAB_FEATURES)
-    }
-    return true
-  }
-  const handled =
-    runtime.navigation.navigate?.({ href, path, targetPlatform }) ?? false
-  if (!handled) window.location.assign(stripSameOriginToPath(href))
-  return true
+  return executeNavigation({ event: e, runtime, href, path, targetPlatform, fallbackNavigate })
 }