@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511

package/src/components/chat/utils/__tests__/resolve-fetched-card-href.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+import { makeComposeContentUrl } from '../../../../utils/content-href'
+import { resolveFetchedCardHref } from '../resolve-fetched-card-href'
+
+const HUB = 'https://www.flamingo.run'
+
+/** The OpenFrame Help Center seam, verbatim in shape from
+ *  `openframe-oss-frontend/src/app/(app)/help-center/help-center-content-href.ts`. */
+const compose = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: HUB,
+  suffixes: {
+    onboarding_guide: 'help-center/onboarding-guides',
+    product_release: 'help-center/releases',
+    blog_post: 'blog',
+    case_study: 'case-studies',
+  },
+  overrides: {
+    roadmap_item: (id) => ({
+      href: `/help-center/roadmap?search=${encodeURIComponent(id)}`,
+      targetPlatform: null,
+    }),
+  },
+})
+
+describe('resolveFetchedCardHref — Mingo cards with no ref metadata', () => {
+  it('override type deep-links on the MARKER id, not the fetched row id', () => {
+    // The `[card://roadmap_item:86ad3qvv5]` id is the ClickUp task id the
+    // roadmap list filters by; the fetched row carries its own db id.
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'roadmap_item',
+        id: '86ad3qvv5',
+        item: { id: 'db-uuid-9', title: 'Deep Google Workspace tenant management' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/roadmap?search=86ad3qvv5', targetPlatform: null })
+  })
+
+  it('hosted type uses the fetched row slug for its in-app detail route', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'product_release',
+        id: 'row-uuid-1',
+        item: { id: 'row-uuid-1', slug: 'v1-2-0' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/releases/v1-2-0', targetPlatform: null })
+  })
+
+  it('hosted type with no slug falls back to the marker id', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'onboarding_guide',
+        id: 'guide-7',
+        item: { id: 'guide-7' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/onboarding-guides/guide-7', targetPlatform: null })
+  })
+
+  it('non-hosted type resolves to the content hub', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: 'cs-1',
+        item: { id: 'cs-1', slug: 'acme-migration' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: `${HUB}/case-studies/acme-migration`, targetPlatform: null })
+  })
+
+  it('legacy rail-vocab alias resolves to the SAME url as the canonical type', () => {
+    // The card registry keys blog entries by `blog_post_existing` (what
+    // `buildListUrl` wants). Both spellings must produce one url — the reported
+    // split was `/blog/what-is-mdr` vs `/blog_post_existing/bitwarden-…`.
+    const canonical = resolveFetchedCardHref({
+      contentRefType: 'blog_post',
+      id: 'p1',
+      item: { id: 'p1', slug: 'bitwarden-review-for-msps' },
+      composeContentUrl: compose,
+    })
+    const alias = resolveFetchedCardHref({
+      contentRefType: 'blog_post_existing',
+      id: 'p1',
+      item: { id: 'p1', slug: 'bitwarden-review-for-msps' },
+      composeContentUrl: compose,
+    })
+    expect(alias).toEqual(canonical)
+    expect(alias).toEqual({
+      href: `${HUB}/blog/bitwarden-review-for-msps`,
+      targetPlatform: null,
+    })
+  })
+
+  it('no seam wired → null (card stays unlinked, pre-existing behavior)', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'roadmap_item',
+        id: '86ad3qvv5',
+        item: { id: '86ad3qvv5' },
+      }),
+    ).toBeNull()
+  })
+
+  it('guards a missing type / id / malformed item', () => {
+    expect(
+      resolveFetchedCardHref({ contentRefType: '', id: 'x', item: {}, composeContentUrl: compose }),
+    ).toBeNull()
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: '',
+        item: {},
+        composeContentUrl: compose,
+      }),
+    ).toBeNull()
+    // A non-object item (or a non-string slug) must not throw — it just loses
+    // the slug hint and falls back to the marker id.
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: 'cs-2',
+        item: { slug: 42 },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: `${HUB}/case-studies/cs-2`, targetPlatform: null })
+  })
+})
+
+describe('makeComposeContentUrl — the new `slug` hint', () => {
+  it('externalUrl still wins over the hint (SSE path unchanged)', () => {
+    expect(
+      compose({
+        type: 'product_release',
+        identifier: 'row-uuid-1',
+        slug: 'from-the-row',
+        externalUrl: `${HUB}/releases/from-the-url`,
+      }),
+    ).toEqual({ href: '/help-center/releases/from-the-url', targetPlatform: null })
+  })
+
+  it('applies to non-hosted types too — hub detail routes are slug-based', () => {
+    expect(compose({ type: 'blog_post', identifier: 'id-1', slug: 'hello-world' })).toEqual({
+      href: `${HUB}/blog/hello-world`,
+      targetPlatform: null,
+    })
+  })
+
+  it('no hint → identifier, unchanged for page-view and SSE callers', () => {
+    expect(compose({ type: 'blog_post', identifier: 'hello-world' })).toEqual({
+      href: `${HUB}/blog/hello-world`,
+      targetPlatform: null,
+    })
+  })
+})

package/src/components/chat/utils/discuss-ref-prompt.ts

@@ -0,0 +1,63 @@
+/**
+ * The ONE place the "Ask Mingo" (discuss) prompt for an inline entity card is
+ * composed — shared by every transport so the affordance reads identically
+ * wherever it is clicked.
+ *
+ * ## Why the two transports still differ underneath
+ *
+ * The prose is UX only. What narrows retrieval differs:
+ *
+ *   - **SSE / guide** — `sendMessage(prompt, { commandOverride: { entityIdFilter:
+ *     { tableId, id } } })`. Retrieval is strictly primary-key-driven; the
+ *     sentence is decoration.
+ *   - **Mingo / NATS** — the agent backend has no entity-id-filtered retrieval
+ *     (`ContextItemType` covers DEVICE / SCRIPT / TICKET / ORGANIZATION / USER /
+ *     KB_ARTICLE / POLICY / QUERY / SCHEDULED_SCRIPT — no content types), so the
+ *     prompt is ALL the agent gets. Hence `includeReference`, which appends the
+ *     type + id so the agent can still identify the exact row by text.
+ *
+ * When the backend grows an id-filter for the agent transport, the Mingo callers
+ * switch to it and drop `includeReference` — the prose stays put.
+ */
+
+import { sanitizeTitleForChat } from './slash-dispatch-utils'
+
+export interface DiscussPromptRef {
+  /** documentType, e.g. `'roadmap_item'`. */
+  type: string
+  /** Primary key — the id from the `[card://type:id]` marker. */
+  id: string
+  /** Display title. May be the bare id on a synthetic ref (Mingo). */
+  title?: string | null
+}
+
+export interface BuildDiscussPromptOptions {
+  /**
+   * Append `(<type> <id>)` so a transport WITHOUT structured entity filtering
+   * still points the agent at the exact row. Default `false` — the SSE path
+   * sends `entityIdFilter` and must keep the sentence clean.
+   */
+  includeReference?: boolean
+}
+
+/**
+ * `Tell me more about <title>` — plus `(<type> <id>)` when
+ * `includeReference` is set and the title alone is ambiguous.
+ *
+ * Falls back to `this item` when the ref has no usable title, matching the
+ * long-standing SSE behavior. A title that is just the id (the synthetic ref a
+ * Mingo `[card://…]` marker produces before its row loads) is treated as
+ * missing, so the prompt never degrades to `Tell me more about 86ad3qvv5`.
+ */
+export function buildDiscussPrompt(
+  reference: DiscussPromptRef,
+  options: BuildDiscussPromptOptions = {},
+): string {
+  const id = (reference.id ?? '').trim()
+  const rawTitle = (reference.title ?? '').trim()
+  const usableTitle = rawTitle && rawTitle !== id ? sanitizeTitleForChat(rawTitle) : ''
+  const prompt = `Tell me more about ${usableTitle || 'this item'}`
+  if (!options.includeReference || !id) return prompt
+  // Only worth the noise when the reference adds something the title doesn't.
+  return `${prompt} (${reference.type} ${id})`
+}

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

@@ -196,4 +196,20 @@ export {
   resolveSourceIcon,
 } from './source-row-cta'
 
+// Post-fetch enrichment for the synthetic ChatRef a `[card://type:id]` marker
+// produces when the transport ships no refs metadata (Mingo/NATS).
+export {
+  resolveFetchedCardHref,
+  readFetchedCardTitle,
+  type FetchedCardHrefInput,
+} from './resolve-fetched-card-href'
+
+// The ONE "Ask Mingo" prompt builder — shared by the SSE adapter, the NATS
+// adapter, and hosts that inject their own Mingo state (openframe-frontend).
+export {
+  buildDiscussPrompt,
+  type DiscussPromptRef,
+  type BuildDiscussPromptOptions,
+} from './discuss-ref-prompt'
+
 export * from './scripted-stream'

package/src/components/chat/utils/resolve-fetched-card-href.ts

@@ -0,0 +1,104 @@
+/**
+ * Post-fetch href fallback for an inline chat card whose `ChatRef` carried no
+ * `externalUrl`.
+ *
+ * ## Why a fetch-mode card can arrive without a URL
+ *
+ * The two chat transports deliver entity references differently:
+ *
+ *   - **SSE / guide transport** — the server ships a `refs` metadata frame, so
+ *     each `[card://type:id]` marker expands into a FULL `ChatRef`
+ *     (`title` / `url` / `targetPlatform` / `sourceRepo`). `resolveSourceRowCTA`
+ *     then routes that `externalUrl` through the host's `composeContentUrl`
+ *     seam and the card is clickable.
+ *   - **Mingo / NATS transport** (`messageData: [{ type: 'GUIDE' | 'TEXT', text }]`)
+ *     — the body carries bare `[card://type:id]` markers and NOTHING else.
+ *     `chat-message-enhanced.tsx` synthesizes a minimal `{ type, id, title: id,
+ *     url: null }` ref so fetch-mode cards can still self-fetch their row, but
+ *     `resolveSourceRowCTA` has no `externalUrl`, no `path` and no
+ *     `targetPlatform` to work with → `href: null` → the card renders with its
+ *     real title and description but goes nowhere when clicked.
+ *
+ * This resolver closes that gap WITHOUT a second URL vocabulary: it calls the
+ * exact same `composeContentUrl` seam the page cards (`resolveContentHref`) and
+ * the SSE cards (`resolveSourceRowCTA`) use, so one host config —
+ * `hostedTypes` / `suffixes` / `overrides` — governs all three.
+ *
+ * `identifier` stays the marker's primary key (that is what `overrides` such as
+ * roadmap's `?search=<task id>` deep-link on); the row's `slug` rides the
+ * separate `slug` hint for hosted types whose detail route is slug-based.
+ *
+ * Pure — no React, no DOM. The caller owns `safeHref` validation.
+ */
+
+import type { ComposeContentUrl } from '../../../utils/content-href'
+import { canonicalContentRefType } from '../../../utils/list-url'
+
+export interface FetchedCardHrefInput {
+  /** Canonical `documentType` for the seam (registry `contentRefType`). */
+  contentRefType: string
+  /** The marker's primary key — `ChatRef.id`, NOT the fetched row's id. */
+  id: string
+  /** The row the card fetched. Shape is per-type and opaque here; only
+   *  `slug` and `platforms` are read, both defensively. */
+  item: unknown
+  /** Host seam. Absent (unwired runtime) → no fallback, same as today. */
+  composeContentUrl?: ComposeContentUrl
+}
+
+/** Read `item.slug` when it is a non-empty string. */
+function readSlug(item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  const slug = (item as { slug?: unknown }).slug
+  return typeof slug === 'string' && slug.trim() ? slug.trim() : null
+}
+
+/**
+ * Human title of a fetched row — `title`, else `name`, else null.
+ *
+ * A Mingo synthetic ref carries `title: <the marker id>` because that is all
+ * the transport shipped. Everything downstream that prints or sends the title
+ * (the "Ask Mingo" prompt, host renderers falling back to `ref.title`) would
+ * otherwise say `86ad3qvv5`. Once the row loads, this is the real title.
+ */
+export function readFetchedCardTitle(item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  for (const key of ['title', 'name'] as const) {
+    const value = (item as Record<string, unknown>)[key]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return null
+}
+
+/** Read `item.platforms` when it is an array — the hub composer keys its
+ *  cross-platform topology off it; the embedder default ignores it. */
+function readPlatforms(item: unknown): Array<{ name?: string }> | undefined {
+  if (!item || typeof item !== 'object') return undefined
+  const platforms = (item as { platforms?: unknown }).platforms
+  return Array.isArray(platforms) ? (platforms as Array<{ name?: string }>) : undefined
+}
+
+/**
+ * Resolve `{href, targetPlatform}` for a freshly fetched card row, or `null`
+ * when the host wired no seam (the caller then keeps the card unlinked, which
+ * is the pre-existing behavior).
+ */
+export function resolveFetchedCardHref({
+  contentRefType,
+  id,
+  item,
+  composeContentUrl,
+}: FetchedCardHrefInput): { href: string; targetPlatform: string | null } | null {
+  if (!composeContentUrl || !contentRefType || !id) return null
+  return composeContentUrl({
+    // The card registry keys some entries by the legacy rail vocabulary
+    // (`blog_post_existing`) because that is what `buildListUrl` expects.
+    // The seam speaks the CANONICAL vocabulary — a host's `hostedTypes` /
+    // `overrides` are written against `blog_post`, so an un-aliased type
+    // misses them all and lands on `<origin>/blog_post_existing/<slug>`.
+    type: canonicalContentRefType(contentRefType),
+    identifier: id,
+    slug: readSlug(item),
+    platforms: readPlatforms(item),
+  })
+}

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

@@ -29,6 +29,7 @@ import { getBaseUrl } from '../../../utils/cn'
 import { safeHref } from './compact-card-classes'
 import type { ChatRef } from '../chat-ref.types'
 import type { ComposeContentUrl } from '../../../utils/content-href'
+import { canonicalContentRefType } from '../../../utils/list-url'
 
 /** Path sanitization — keep alphanumerics, slash, dash, dot, underscore;
  *  strip everything else. Defends against a hostile mapper returning a
@@ -233,7 +234,10 @@ export function resolveSourceRowCTA(
     // from the externalUrl) and everything else to the externalUrl verbatim —
     // the SAME resolver the page-view cards use, so chat + page links match.
     const composed = ctx.composeContentUrl({
-      type: row.documentType,
+      // Canonical vocabulary only — a rail-vocab alias would miss the host's
+      // `hostedTypes` / `overrides` and fall through to the seam's default
+      // `<origin>/<type>/<id>` branch. Same canonicalizer `buildListUrl` uses.
+      type: canonicalContentRefType(row.documentType),
       identifier: idValue,
       externalUrl: row.externalUrl,
       targetPlatform: row.targetPlatform ?? null,

package/src/components/shared/doc-search/__tests__/resolve-search-result-action.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest'
+import { makeComposeContentUrl } from '../../../../utils/content-href'
+import type { SearchResult } from '../../../ui/search-input'
+import { resolveSearchResultAction } from '../resolve-search-result-action'
+
+const HUB = 'https://www.flamingo.run'
+
+/** A RAG row for a guide the hub owns, shaped like `mapDocSearchResults` emits. */
+const guideRow: SearchResult = {
+  id: 'onboarding-guides/deploy-first-device',
+  title: 'Deploy your first device',
+  path: 'onboarding-guides/deploy-first-device',
+  metadata: {
+    documentType: 'onboarding_guide',
+    externalUrl: `${HUB}/onboarding-guides/deploy-first-device`,
+    sourceRepo: 'onboarding-guides',
+    id: 'guide-123',
+    targetPlatform: 'openframe',
+  },
+}
+
+/** The OpenFrame Help Center seam: the two hosted types live under
+ *  `/help-center/...`, list-filter types deep-link with `?search=<id>`. */
+const helpCenterCompose = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: HUB,
+  suffixes: {
+    onboarding_guide: 'help-center/onboarding-guides',
+    product_release: 'help-center/releases',
+    blog_post: 'blog',
+  },
+  overrides: {
+    delivery_item: (id) => ({ href: `/help-center/bug-fixes?search=${id}`, targetPlatform: null }),
+  },
+})
+
+describe('resolveSearchResultAction — composeContentUrl seam', () => {
+  it('no seam wired → the RAG externalUrl verbatim (legacy behavior)', () => {
+    expect(resolveSearchResultAction(guideRow, 'openframe')).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/onboarding-guides/deploy-first-device`,
+    })
+  })
+
+  it('hosted type → the host in-app route, slug recovered from externalUrl', () => {
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('relative composed href stays same-tab even in embed mode', () => {
+    // `decideNewTab` forces new-tab under embed; an in-app path must not be
+    // handed to window.open — the short-circuit runs before that decision.
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'embed', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('override type → the host deep-link, primary key as identifier', () => {
+    const row: SearchResult = {
+      id: 'delivery-1',
+      title: 'Fix the thing',
+      metadata: {
+        documentType: 'delivery_item',
+        externalUrl: `${HUB}/bug-fixes-and-enhancements?search=abc123`,
+        sourceRepo: 'clickup-delivery',
+        id: 'abc123',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/bug-fixes?search=abc123',
+    })
+  })
+
+  it('non-hosted type → the seam returns externalUrl verbatim, opens out', () => {
+    const row: SearchResult = {
+      id: 'blog-1',
+      title: 'Hello',
+      metadata: {
+        documentType: 'blog_post',
+        externalUrl: `${HUB}/blog/hello`,
+        sourceRepo: 'blog-posts',
+        id: 'blog-1',
+        targetPlatform: 'flamingo',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-new-tab',
+      href: `${HUB}/blog/hello`,
+    })
+  })
+
+  it('row without documentType → seam skipped, externalUrl verbatim', () => {
+    const row: SearchResult = {
+      id: 'x',
+      title: 'Untyped',
+      metadata: { externalUrl: `${HUB}/somewhere`, targetPlatform: 'openframe' },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/somewhere`,
+    })
+  })
+
+  it('no externalUrl → unchanged ask-ai / route / noop fallbacks', () => {
+    expect(
+      resolveSearchResultAction(
+        {
+          id: 'cap-1',
+          title: 'Cap Table',
+          metadata: { documentType: 'cap_table', sourceRepo: 'financial-cap-table', id: 'row-9' },
+        },
+        'company-hub',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({
+      kind: 'ask-ai',
+      detail: {
+        source: 'company-hub',
+        ref: { type: 'cap_table', id: 'row-9', title: 'Cap Table', url: null },
+      },
+    })
+
+    expect(
+      resolveSearchResultAction(
+        { id: 'doc', title: 'Doc', path: 'repo/architecture/api.md' },
+        'openframe',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({ kind: 'route', path: 'repo/architecture/api.md' })
+
+    expect(
+      resolveSearchResultAction({ id: 'empty', title: 'Empty' }, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({ kind: 'noop' })
+  })
+})

package/src/components/shared/doc-search/resolve-search-result-action.ts

@@ -3,8 +3,9 @@
  * Returns one of five typed actions so the caller is a single switch.
  *
  * Resolution order:
- *  1. `externalUrl` present → use `decideNewTab` to choose same-tab vs
- *     new-tab against the row's `targetPlatform`.
+ *  1. `externalUrl` present → resolve the href through the host's
+ *     `composeContentUrl` seam (when wired), then use `decideNewTab` to
+ *     choose same-tab vs new-tab against the resolved `targetPlatform`.
  *  2. Row has `id` + `sourceRepo` + `documentType` → synth an Ask-AI
  *     action (entity drill-in via primary key, no URL).
  *  3. Row has only `path` → legacy navigation fallback.
@@ -16,8 +17,16 @@
 
 import type { SearchResult } from '../../ui/search-input'
 import type { ChatRef } from '../../chat/chat-ref.types'
+import type { ComposeContentUrl } from '../../../utils/content-href'
 import { decideNewTab } from '../../chat/utils/decide-new-tab'
 
+/** True for `https://…` and protocol-relative `//…`. A composed href that is
+ *  NOT absolute is an in-app route the host claimed via `hostedTypes` /
+ *  `overrides`. */
+function isAbsoluteHref(href: string): boolean {
+  return /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(href)
+}
+
 export type SearchResultAction =
   | { kind: 'navigate-same-tab'; href: string }
   | { kind: 'navigate-new-tab'; href: string }
@@ -29,29 +38,56 @@ export function resolveSearchResultAction(
   result: SearchResult,
   source: string,
   runtimeMode?: 'host' | 'embed',
+  /** The host's unified content-href seam (`runtime.composeContentUrl`).
+   *  When wired, an entity row's RAG `externalUrl` is re-resolved through it,
+   *  so a type the host serves in-app (`hostedTypes`) or deep-links itself
+   *  (`overrides`) lands on the SAME href the catalog cards and chat cards
+   *  use. Omitted → the legacy verbatim-`externalUrl` behavior. */
+  composeContentUrl?: ComposeContentUrl,
 ): SearchResultAction {
   const meta = result.metadata ?? {}
   const externalUrl = meta.externalUrl as string | undefined
+  const rowId = meta.id as string | undefined
+  const sourceRepo = meta.sourceRepo as string | undefined
+  const documentType = meta.documentType as string | undefined
   if (externalUrl) {
+    const targetPlatform = meta.targetPlatform as string | null | undefined
+    // Unified content-href seam — the same call `resolveSourceRowCTA` makes
+    // for chat rows. Hosted types relativize the slug out of `externalUrl`;
+    // everything else comes back verbatim, so an unwired host (or a row with
+    // no `documentType`) keeps today's behavior byte-for-byte.
+    const composed =
+      composeContentUrl && documentType
+        ? composeContentUrl({
+            type: documentType,
+            identifier: rowId ?? '',
+            externalUrl,
+            targetPlatform: targetPlatform ?? null,
+          })
+        : null
+    const href = composed?.href || externalUrl
+    // A RELATIVE composed href means the host claimed this row as in-app.
+    // Short-circuit BEFORE `decideNewTab`: in embed mode that helper forces
+    // new-tab unconditionally, which would fire `window.open()` on a path
+    // that only resolves inside this app.
+    if (composed && !isAbsoluteHref(href)) {
+      return { kind: 'navigate-same-tab', href }
+    }
     // Same pure helper `useNavLink` and `useUnifiedNav` call — single
     // decision rule across cards, chips, and autocomplete rows. Thread
     // the caller's `source` as `currentSource` so the platform-vs-
     // platform comparison matches the hub's pre-migration behavior.
-    const targetPlatform = meta.targetPlatform as string | null | undefined
     const isNewTab = decideNewTab({
-      href: externalUrl,
-      targetPlatform,
+      href,
+      targetPlatform: composed ? composed.targetPlatform : targetPlatform,
       surface: 'useUnifiedNav',
       runtimeMode,
       currentSource: source,
     })
     return isNewTab
-      ? { kind: 'navigate-new-tab', href: externalUrl }
-      : { kind: 'navigate-same-tab', href: externalUrl }
+      ? { kind: 'navigate-new-tab', href }
+      : { kind: 'navigate-same-tab', href }
   }
-  const rowId = meta.id as string | undefined
-  const sourceRepo = meta.sourceRepo as string | undefined
-  const documentType = meta.documentType as string | undefined
   if (rowId && sourceRepo && documentType) {
     return {
       kind: 'ask-ai',