@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511-snapshot.20260804140004

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

@@ -159,6 +159,16 @@ export interface ApprovalBatchData {
   executions?: Record<string, ApprovalBatchExecutionState>
 }
 
+/** Approve/reject handler stamped onto approval segments. MAY resolve a
+ *  boolean success flag — `false` means the confirm FAILED (expired
+ *  proposal, network error); batch approve-all loops use it to tick the
+ *  row's failure cross. `void` (legacy transports) is treated as
+ *  success. Single source of truth for this signature — component
+ *  props, accumulator callbacks, and adapters all reference it. */
+export type ApprovalResolutionHandler = (
+  requestId?: string,
+) => void | boolean | Promise<void | boolean>
+
 // ========== Message Segment Types ==========
 
 export type TextSegment = {
@@ -192,8 +202,8 @@ export type ApprovalRequestSegment = {
   /** Display name of the user who resolved the request; baked into the client
    *  variant's full-text status pill ("Approved by {name}"). */
   resolvedByName?: string | null
-  onApprove?: (requestId?: string) => void | Promise<void>
-  onReject?: (requestId?: string) => void | Promise<void>
+  onApprove?: ApprovalResolutionHandler
+  onReject?: ApprovalResolutionHandler
 }
 
 export type ApprovalBatchSegment = {
@@ -202,8 +212,8 @@ export type ApprovalBatchSegment = {
   status?: ChatApprovalStatus
   /** Display name of the user who resolved the request; set when the batch is resolved (null/absent for system actions). */
   resolvedByName?: string | null
-  onApprove?: (requestId?: string) => void | Promise<void>
-  onReject?: (requestId?: string) => void | Promise<void>
+  onApprove?: ApprovalResolutionHandler
+  onReject?: ApprovalResolutionHandler
 }
 
 export type ErrorSegment = {

package/src/components/chat/types/unified-chat-state.types.ts

@@ -274,10 +274,13 @@ export interface UnifiedChatState {
   isHydratingHistory?: boolean
 
   // ─── Actions ──────────────────────────────────────────────────────────────
+  /** Resolution MAY carry a boolean success flag (`false` = the request
+   *  failed) — consumed by batch approve-all loops to mark failed rows.
+   *  Callers that only await it are unaffected (`void` = success). */
   sendMessage: (
     text: string,
     options?: UnifiedSendMessageOptions,
-  ) => Promise<void>
+  ) => Promise<void | boolean>
 
   /** Abort the in-flight stream. No-op when idle. */
   stopMessage: () => void

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+import { buildDiscussPrompt } from '../discuss-ref-prompt'
+import { readFetchedCardTitle } from '../resolve-fetched-card-href'
+
+const ROADMAP_REF = {
+  type: 'roadmap_item',
+  id: '86ad3qvv5',
+  title: 'Deep Google Workspace tenant management',
+}
+
+describe('buildDiscussPrompt', () => {
+  it('guide/SSE shape — prose only, retrieval rides entityIdFilter', () => {
+    expect(buildDiscussPrompt(ROADMAP_REF)).toBe(
+      'Tell me more about Deep Google Workspace tenant management',
+    )
+  })
+
+  it('Mingo shape — appends the reference the agent has no filter for', () => {
+    expect(buildDiscussPrompt(ROADMAP_REF, { includeReference: true })).toBe(
+      'Tell me more about Deep Google Workspace tenant management (roadmap_item 86ad3qvv5)',
+    )
+  })
+
+  it('a synthetic ref (title === id) never leaks the id as the subject', () => {
+    const synthetic = { type: 'roadmap_item', id: '86ad3qvv5', title: '86ad3qvv5' }
+    expect(buildDiscussPrompt(synthetic, { includeReference: true })).toBe(
+      'Tell me more about this item (roadmap_item 86ad3qvv5)',
+    )
+  })
+
+  it('missing / blank title falls back to "this item"', () => {
+    expect(buildDiscussPrompt({ type: 'blog_post', id: 'b1' })).toBe('Tell me more about this item')
+    expect(buildDiscussPrompt({ type: 'blog_post', id: 'b1', title: '   ' })).toBe(
+      'Tell me more about this item',
+    )
+  })
+
+  it('no id → no reference suffix', () => {
+    expect(buildDiscussPrompt({ type: 'blog_post', id: '', title: 'Hello' }, { includeReference: true })).toBe(
+      'Tell me more about Hello',
+    )
+  })
+})
+
+describe('readFetchedCardTitle — what upgrades a synthetic ref before the prompt', () => {
+  it('prefers title, then name', () => {
+    expect(readFetchedCardTitle({ title: 'Roadmap row' })).toBe('Roadmap row')
+    expect(readFetchedCardTitle({ name: 'Named row' })).toBe('Named row')
+    expect(readFetchedCardTitle({ title: '  ', name: 'Named row' })).toBe('Named row')
+  })
+
+  it('null for rows with neither (and for non-objects)', () => {
+    expect(readFetchedCardTitle({ headline: 'nope' })).toBeNull()
+    expect(readFetchedCardTitle(null)).toBeNull()
+    expect(readFetchedCardTitle('string')).toBeNull()
+    expect(readFetchedCardTitle({ title: 42 })).toBeNull()
+  })
+
+  it('end to end: fetched row title reaches the prompt', () => {
+    const synthetic = { type: 'roadmap_item', id: '86ad3qvv5', title: '86ad3qvv5' }
+    const row = { id: 'db-9', title: 'Deep Google Workspace tenant management' }
+    const enriched = { ...synthetic, title: readFetchedCardTitle(row) ?? synthetic.title }
+    expect(buildDiscussPrompt(enriched, { includeReference: true })).toBe(
+      'Tell me more about Deep Google Workspace tenant management (roadmap_item 86ad3qvv5)',
+    )
+  })
+})

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/message-segment-accumulator.ts

@@ -14,6 +14,7 @@ import type {
   ApprovalRequestSegment,
   ApprovalBatchSegment,
   ApprovalBatchExecutionState,
+  ApprovalResolutionHandler,
   ContextCompactionSegment,
   ErrorSegment,
   PendingApproval,
@@ -22,10 +23,17 @@ import type {
   ChatApprovalStatus,
   ExecutingToolState,
 } from '../types'
+import {
+  applyApprovalStatusToSegment,
+  nextBatchExecution,
+  withBatchExecution,
+} from '../stream/message-mutations'
 
 export interface AccumulatorCallbacks {
-  onApprove?: (requestId?: string) => Promise<void> | void
-  onReject?: (requestId?: string) => Promise<void> | void
+  /** See `ApprovalResolutionHandler` (message.types) — the SSOT for the
+   *  approve/reject signature incl. the boolean failure flag. */
+  onApprove?: ApprovalResolutionHandler
+  onReject?: ApprovalResolutionHandler
 }
 
 /**
@@ -244,25 +252,13 @@ export class MessageSegmentAccumulator {
       if (!hasCall) return seg
 
       const prev: ApprovalBatchExecutionState | undefined = seg.data.executions?.[execId]
-      // Never downgrade a done slot back to executing (redelivered EXECUTING
-      // after its EXECUTED already landed) — matched, but unchanged.
-      if (toolData.type === 'EXECUTING_TOOL' && prev?.status === 'done') {
-        matched = true
-        return seg
-      }
-      const next: ApprovalBatchExecutionState =
-        toolData.type === 'EXECUTED_TOOL'
-          ? { status: 'done', result: toolData.result, success: toolData.success }
-          : { status: 'executing', result: prev?.result, success: prev?.success }
-
+      // Shared rule (`nextBatchExecution` from message-mutations): the
+      // never-downgrade guard + EXECUTED/EXECUTING ternary — one
+      // implementation with the message-array projection.
+      const next = nextBatchExecution(prev, toolData)
       matched = true
-      return {
-        ...seg,
-        data: {
-          ...seg.data,
-          executions: { ...(seg.data.executions ?? {}), [execId]: next },
-        },
-      }
+      if (next === null) return seg
+      return withBatchExecution(seg, execId, next)
     })
     return matched
   }
@@ -429,15 +425,14 @@ export class MessageSegmentAccumulator {
    * resolved card shows "by {name}"; omit it to leave any existing value untouched.
    */
   updateApprovalStatus(requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null): MessageSegment[] {
-    this.segments = this.segments.map(segment => {
-      if (segment.type === 'approval_request' && segment.data.requestId === requestId) {
-        return { ...segment, status }
-      }
-      if (segment.type === 'approval_batch' && segment.data.approvalRequestId === requestId) {
-        return { ...segment, status, resolvedByName: resolvedByName ?? segment.resolvedByName }
-      }
-      return segment
-    })
+    // ONE rule, two containers: `applyApprovalStatusToSegment` is the
+    // same predicate the message-array projection uses
+    // (`projectApprovalResolutionToMessages`) — anchor status flip AND
+    // batch-row execution tick, so this flat-list path can never drift
+    // from the projection again (it previously missed the row case).
+    this.segments = this.segments.map((segment) =>
+      applyApprovalStatusToSegment(segment, requestId, status, resolvedByName),
+    )
     return this.getSegments()
   }
 

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,