@flamingo-stack/openframe-frontend-core 0.0.217 → 0.0.218-snapshot.20260602043552

package/src/components/chat/hooks/use-slash-commands.ts

@@ -14,6 +14,7 @@
  */
 
 import { useEffect, useState } from "react";
+import { embedAuthedFetch } from "../../../utils/embed-authed-fetch";
 import type {
   SlashCommandActionId,
   SlashCommandSummaryAction,
@@ -44,6 +45,12 @@ export type {
  * (e.g. `https://hub.openframe.ai/api/commands` → the base arg is
  * ignored).
  *
+ * Auth: rides on `embedAuthedFetch` (same bearer-act-as + 401 self-heal
+ * as the chat stream / identity / attachment calls) so a host that runs
+ * proxy-impersonation or a refresh-capable auth adapter gets its creds
+ * attached here too — no host-side `window.fetch` patch required. Hosts
+ * with no adapter fall through to cookie auth unchanged.
+ *
  * Returns the parsed `commands` array; on any non-2xx (auth,
  * rate-limit, chat-disabled) returns an empty array — the autocomplete
  * UI silently shows no suggestions rather than surfacing 401/403/429
@@ -56,7 +63,9 @@ export async function fetchSlashCommands(
 ): Promise<SlashCommandSummary[]> {
   const url = new URL(commandsUrl, window.location.origin);
   if (prefix) url.searchParams.set("q", prefix);
-  const res = await fetch(url.toString(), { signal });
+  // `headers: {}` opts out of the default `Content-Type: application/json`
+  // — this is a bare GET with no body, so no content-type is needed.
+  const res = await embedAuthedFetch(url.toString(), { signal, headers: {} });
   if (!res.ok) return [];
   const data = (await res.json()) as { commands?: SlashCommandSummary[] };
   return data.commands ?? [];

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
@@ -57,6 +58,7 @@ import type {
   UnifiedSendMessageOptions,
   StreamingPhase,
 } from '../types/unified-chat-state.types'
+import type { DialogItem } from '../types/component.types'
 
 // =============================================================================
 // Public types
@@ -578,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 => {
@@ -667,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,
@@ -675,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
@@ -1054,5 +1059,49 @@ export function useSseChatAdapter(
     /** Cross-call usage breakdown (Haiku rewriter/classifier/summarizer
      *  token counts). null until the trailing usage frame lands. */
     currentUsageBreakdown: latestMeta?.breakdown ?? null,
+    // ─── Dialog management — stubs for v1 ────────────────────────────────
+    // Guide mode currently keeps its history in `localStorage` opaquely
+    // under the hood (`runtime.source` namespaced key). Surfacing that
+    // history as a structured dialog list is a follow-up; for now the
+    // shape is satisfied with empty defaults so the unified contract
+    // type-checks and EmbeddableChat hides sidebar affordances when
+    // `dialogs.length === 0`.
+    dialogs: SSE_EMPTY_DIALOGS,
+    activeDialogId: null,
+    selectDialog: noopSelectDialog,
+    startNewDialog: noopStartNewDialog,
+    deleteDialog: noopDeleteDialog,
+    isDialogsLoading: false,
+    isMessagesLoading: false,
+    hasMoreDialogs: false,
+    loadMoreDialogs: noopAsync,
+    hasMoreMessages: false,
+    loadMoreMessages: noopAsync,
+    approveRequest: noopApproveRequest,
+    rejectRequest: noopRejectRequest,
+    dialogTokenUsage: null,
+    connectionState: 'connected' as const,
   }
 }
+
+// ─── Stable no-op references for the Guide-mode dialog-management stubs ──
+// Plain module-scope constants so the adapter's return identity stays
+// stable across renders — consumers that memo on these fields don't get
+// spurious re-runs.
+const SSE_EMPTY_DIALOGS: DialogItem[] = []
+const noopSelectDialog = (_id: string | null): void => {
+  /* Guide mode has no managed dialog list yet */
+}
+const noopStartNewDialog = async (): Promise<string | null> => null
+const noopDeleteDialog = async (_id: string): Promise<void> => {
+  /* no-op until Guide localStorage history is exposed */
+}
+const noopAsync = async (): Promise<void> => {
+  /* no-op pagination stub */
+}
+const noopApproveRequest = async (_id: string): Promise<void> => {
+  /* Guide mode has no tool-call approval workflow */
+}
+const noopRejectRequest = async (_id: string, _reason?: string): Promise<void> => {
+  /* Guide mode has no tool-call approval workflow */
+}

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

@@ -141,6 +141,40 @@ export function useUnifiedChat(
     [activeState],
   )
 
+  // Dialog-management forwards — one thin wrapper per action so the
+  // returned identity stays stable as long as the active adapter's
+  // identity does. We don't recreate per-call to avoid spurious child
+  // re-renders downstream.
+  const selectDialog = useCallback(
+    (id: string | null) => activeState.selectDialog(id),
+    [activeState],
+  )
+  const startNewDialog = useCallback(
+    () => activeState.startNewDialog(),
+    [activeState],
+  )
+  const deleteDialog = useCallback(
+    (id: string) => activeState.deleteDialog(id),
+    [activeState],
+  )
+  const loadMoreDialogs = useCallback(
+    () => activeState.loadMoreDialogs(),
+    [activeState],
+  )
+  const loadMoreMessages = useCallback(
+    () => activeState.loadMoreMessages(),
+    [activeState],
+  )
+  const approveRequest = useCallback(
+    (requestId: string) => activeState.approveRequest(requestId),
+    [activeState],
+  )
+  const rejectRequest = useCallback(
+    (requestId: string, reason?: string) =>
+      activeState.rejectRequest(requestId, reason),
+    [activeState],
+  )
+
   return useMemo<UnifiedChatState>(
     () => ({
       messages: activeState.messages,
@@ -158,6 +192,24 @@ export function useUnifiedChat(
       currentOutputTokens: activeState.currentOutputTokens,
       currentCacheHitRatePct: activeState.currentCacheHitRatePct,
       currentUsageBreakdown: activeState.currentUsageBreakdown,
+      // Dialog management (forwarded from active adapter)
+      dialogs: activeState.dialogs,
+      activeDialogId: activeState.activeDialogId,
+      selectDialog,
+      startNewDialog,
+      deleteDialog,
+      isDialogsLoading: activeState.isDialogsLoading,
+      isMessagesLoading: activeState.isMessagesLoading,
+      hasMoreDialogs: activeState.hasMoreDialogs,
+      loadMoreDialogs,
+      hasMoreMessages: activeState.hasMoreMessages,
+      loadMoreMessages,
+      // Approvals
+      approveRequest,
+      rejectRequest,
+      // Token usage + connection
+      dialogTokenUsage: activeState.dialogTokenUsage,
+      connectionState: activeState.connectionState,
     }),
     [
       activeState,
@@ -166,6 +218,13 @@ export function useUnifiedChat(
       clearMessages,
       discussRef,
       displayRef,
+      selectDialog,
+      startNewDialog,
+      deleteDialog,
+      loadMoreDialogs,
+      loadMoreMessages,
+      approveRequest,
+      rejectRequest,
     ],
   )
 }

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/unified-chat-state.types.ts

@@ -21,6 +21,44 @@ import type { ScrollAnchor } from './message.types'
 import type { ChatRef } from '../chat-ref.types'
 import type { ChatSource } from '../hooks/use-sse-chat-adapter'
 import type { ChatAttachment } from '../utils/chat-attachment-markdown'
+import type { DialogItem } from './component.types'
+
+// ─── Per-dialog token usage (Mingo backend telemetry) ────────────────────────
+
+/**
+ * Token usage snapshot for the active Mingo dialog, hydrated from the
+ * backend's `dialog.tokenUsage` GraphQL field. Mirrors the shape returned
+ * by the openframe `dialogs` GraphQL endpoint so hosts can pass it through
+ * `fetchDialogMessages` without re-mapping.
+ *
+ * Null when no Mingo dialog is active, when the backend hasn't reported
+ * usage yet, or when the active mode is Guide (SSE telemetry surfaces via
+ * `currentInputTokens`/`currentOutputTokens` instead).
+ */
+export interface DialogTokenUsage {
+  /** Backend chat-type discriminator, e.g. `ADMIN_AI_CHAT`. Free-form. */
+  chatType?: string
+  /** Total input tokens consumed so far in this dialog. */
+  inputTokensSize: number
+  /** Total output tokens emitted so far in this dialog. */
+  outputTokensSize: number
+  /** Sum of input + output. May be > input + output when the backend
+   *  counts cache reads in a separate bucket — trust the backend value. */
+  totalTokensSize: number
+  /** Current LLM context-window occupancy in tokens — what the model
+   *  has loaded right now, not the cumulative dialog sum. */
+  contextSize?: number
+}
+
+// ─── Connection state (transport-level) ──────────────────────────────────────
+
+/**
+ * High-level transport connection status. Drives any UI affordance that
+ * needs to communicate "live tail is/isn't healthy" to the user. SSE/Guide
+ * adapter currently reports `'connected'` whenever a turn isn't streaming
+ * — the SSE side is request-response and has no long-lived socket.
+ */
+export type ChatConnectionState = 'connected' | 'connecting' | 'disconnected'
 
 // ─── Streaming phase (unified across transports) ─────────────────────────────
 
@@ -212,4 +250,82 @@ export interface UnifiedChatState {
    * arrives. Always null in Mingo mode.
    */
   currentUsageBreakdown: UnifiedUsageBreakdown | null
+
+  // ─── Dialog management (Mingo: backend; Guide: localStorage) ──────────────
+  //
+  // All fields below are optional in practice: a transport adapter that
+  // doesn't manage multi-dialog history (older `useNatsChatAdapter`
+  // configs, the Guide adapter with localStorage disabled) returns the
+  // empty/null defaults so existing consumers keep working unchanged.
+  // Callers gate UI on `dialogs.length > 0` or `activeDialogId != null`.
+
+  /**
+   * History of dialogs available for the active mode. Mingo: paginated
+   * from the openframe backend. Guide: list of recent threads from
+   * localStorage. Empty when the active adapter doesn't expose dialog
+   * management.
+   */
+  dialogs: DialogItem[]
+
+  /** Currently-selected dialog id, or `null` when no dialog is active
+   *  (draft state — "start a new conversation"). */
+  activeDialogId: string | null
+
+  /** Switch the panel to an existing dialog. Idempotent — selecting the
+   *  active id is a no-op. Pass `null` to drop back to draft state. */
+  selectDialog: (id: string | null) => void
+
+  /** Allocate a fresh dialog on the backend (Mingo) or in localStorage
+   *  (Guide) and switch to it. Returns the new dialog id. When the
+   *  adapter doesn't support creation, resolves to `null`. */
+  startNewDialog: () => Promise<string | null>
+
+  /** Delete a dialog from history. No-op when the adapter doesn't
+   *  expose `deleteDialog` (Guide localStorage always supports it;
+   *  Mingo gates on the host-provided callback). */
+  deleteDialog: (id: string) => Promise<void>
+
+  /** True while the dialog list is being fetched for the first time. */
+  isDialogsLoading: boolean
+
+  /** True while message history for the active dialog is being fetched. */
+  isMessagesLoading: boolean
+
+  /** Whether more dialogs remain on the server (Mingo cursor pagination). */
+  hasMoreDialogs: boolean
+
+  /** Fetch the next page of dialogs. No-op when `hasMoreDialogs` is false. */
+  loadMoreDialogs: () => Promise<void>
+
+  /** Whether more historical messages remain in the active dialog. */
+  hasMoreMessages: boolean
+
+  /** Fetch the next page of historical messages for the active dialog. */
+  loadMoreMessages: () => Promise<void>
+
+  // ─── Approval mutations (Mingo agent tool-call workflow) ──────────────────
+
+  /** Approve an in-flight tool-call request. Errors surface via the
+   *  host-supplied toast in the callback config (lib does not own UI). */
+  approveRequest: (requestId: string) => Promise<void>
+
+  /** Reject an in-flight tool-call request. Optional `reason` is
+   *  forwarded to the backend when supported. */
+  rejectRequest: (requestId: string, reason?: string) => Promise<void>
+
+  // ─── Per-dialog token usage (Mingo only) ──────────────────────────────────
+
+  /** Cumulative token usage for the active Mingo dialog. Null in Guide
+   *  mode or when the backend hasn't reported usage yet. Per-turn
+   *  metadata (`currentInputTokens` etc.) is orthogonal — that fires on
+   *  every SSE `message_start`, while this hydrates from the dialog
+   *  fetch + live `TOKEN_USAGE` events. */
+  dialogTokenUsage: DialogTokenUsage | null
+
+  // ─── Connection state ─────────────────────────────────────────────────────
+
+  /** High-level transport connection state. Drives reconnect UI in
+   *  Mingo mode; always `'connected'` in Guide mode (SSE is request-
+   *  response and has no persistent socket to monitor). */
+  connectionState: ChatConnectionState
 }

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,