@flamingo-stack/openframe-frontend-core 0.0.509 → 0.0.510-snapshot.20260803134056

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/navigation/header.tsx

@@ -8,8 +8,8 @@ import { Menu01Icon, XmarkIcon } from '../icons-v2-generated';
 import { Button } from '../ui/button';
 import { HeaderButton } from './header-button';
 import { MingoAiButton } from './mingo-ai-button';
-import { TicketAlertsButton } from './ticket-alerts-button';
 import { MOBILE_NAV_PANEL_ID } from './mobile-nav-panel';
+import { TicketAlertsButton } from './ticket-alerts-button';
 import { TopNavigation } from './top-navigation';
 
 export interface HeaderProps {
@@ -20,6 +20,11 @@ export interface HeaderProps {
 // Re-export from types for convenience
 export type { HeaderConfig } from '../../types/navigation';
 
+// Top-level nav-link typography (Figma 2936-6815): the compact h6 step
+// (DM Sans 500, 14/20) with 24px icons. Overrides the `font="regular"` h4
+// label and the Button base's 20px svg cap via cn()'s tailwind-merge.
+const NAV_ITEM_CLASSES = 'text-h6 [&_svg]:h-6 [&_svg]:w-6';
+
 export function Header({ config, platform }: HeaderProps) {
   const [show, setShow] = useState(true);
   const [lastScrollY, setLastScrollY] = useState(0);
@@ -139,9 +144,10 @@ export function Header({ config, platform }: HeaderProps) {
             size="default"
             font="regular"
             className={cn(
-              // Top-level nav links: the default-size button with the h4
-              // (DM Sans 500) `font="regular"` label — Figma 133-740, added
-              // for navigation; dropdown children stay on the h6 step.
+              // Top-level nav links (Figma 2936-6815): compact h6 label
+              // (DM Sans 500, 14/20) with 24px icons — overrides the
+              // font="regular" h4 step and the button's 20px svg cap.
+              NAV_ITEM_CLASSES,
               item.isActive && 'bg-ods-bg-hover', // Active items get subtle gray background
               isOpen && 'bg-ods-bg-hover', // Open dropdowns get gray background
               item.className,
@@ -197,7 +203,11 @@ export function Header({ config, platform }: HeaderProps) {
                   }}
                   className={cn(
                     'flex justify-start w-full',
-                    'text-h6 font-bold',
+                    // Same caption step as the top-level nav links (designer:
+                    // dropdowns follow the h6 caption size/weight too). The
+                    // explicit font-medium beats small-legacy's font-bold via
+                    // tailwind-merge instead of stylesheet order.
+                    'text-h6 font-medium',
                     index < (item.children?.length ?? 0) - 1 && 'mb-1',
                     'text-ods-text-primary', // All dropdown items use primary text color
                     child.isActive && 'bg-ods-bg-hover', // Active dropdown items get gray background
@@ -232,6 +242,7 @@ export function Header({ config, platform }: HeaderProps) {
           size="default"
           font="regular"
           className={cn(
+            NAV_ITEM_CLASSES,
             'hover:bg-ods-bg-hover focus:bg-ods-bg-hover',
             'whitespace-nowrap',
             'text-ods-text-primary', // All items use primary text color
@@ -256,6 +267,7 @@ export function Header({ config, platform }: HeaderProps) {
         size="default"
         font="regular"
         className={cn(
+          NAV_ITEM_CLASSES,
           'hover:bg-ods-bg-hover focus:bg-ods-bg-hover',
           'whitespace-nowrap',
           'text-ods-text-primary', // All items use primary text color
@@ -269,12 +281,6 @@ export function Header({ config, platform }: HeaderProps) {
   };
 
   const hasNav = !!config.navigation && config.navigation.items.length > 0;
-  // Always-visible leading cells (admin-sidebar toggle). The logo zone's
-  // desktop `pl-xxl` (80px) exists to compensate for the ABSENCE of a leading
-  // cell — with one present it reads as a stray gap, so collapse it to the
-  // regular `pl-l` inset. (The marketing burger doesn't count: it is
-  // CSS-hidden on lg, exactly where the 80px inset applies.)
-  const hasLeftCells = !!config.actions?.left?.length;
   const hasCta =
     !!config.actions?.right?.length || !!(config.actions?.persistent && config.actions.persistent.length > 0);
 
@@ -343,11 +349,10 @@ export function Header({ config, platform }: HeaderProps) {
             {config.logo.element}
           </Link>
         }
-        // Logo inset for the hub sites: 12px on mobile (the shell's base p-m),
-        // 16px on tablet (mf token; the shell default is pl-l = 24px there),
-        // desktop unchanged — pl-xxl, collapsed to pl-l when an always-visible
-        // leading cell sits before the logo.
-        logoClassName={cn('md:pl-[var(--spacing-system-mf)]', hasLeftCells && 'lg:pl-[var(--spacing-system-l)]')}
+        // Big-bar rule (Figma 2936-6812): 24px fixed left inset on the logo
+        // zone at every breakpoint — the same 24px also reads as the gap
+        // between a leading cell (burger / admin toggle) and the logo.
+        logoClassName="pl-[var(--spacing-system-lf)] md:pl-[var(--spacing-system-lf)] lg:pl-[var(--spacing-system-lf)]"
         center={
           hasNav ? (
             <nav

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' })
+  })
+})