@flamingo-stack/openframe-frontend-core 0.0.290 → 0.0.291-snapshot.20260618233000

package/dist/utils/scroll-into-view.d.ts

@@ -33,6 +33,18 @@
  *
  * Honors `prefers-reduced-motion` (jumps instantly) and cancels on genuine user
  * scroll intent (wheel / touch) so we never fight the user.
+ *
+ * WINDOW *OR* A SCROLLABLE ANCESTOR: the helper is not hard-wired to the window
+ * scroller. It walks up from the target to the nearest ancestor that is an
+ * actual scroll container (`overflow-y: auto | scroll | overlay` AND
+ * `scrollHeight > clientHeight`) and drives THAT element; only when none exists
+ * does it fall back to `window`. This is what makes it work inside app shells
+ * that put page content in a fixed-height `<main class="overflow-y-auto">`
+ * (e.g. OpenFrame's `AppLayout`) where the document/window never scrolls — the
+ * old window-only version was a silent no-op there. Note `overflow: clip` /
+ * `hidden` are deliberately NOT treated as scroll containers, so a list wrapper
+ * that uses `overflow-clip` only to round its corners still bubbles the scroll
+ * up to the real container (matches the `<HelpCenterCard>` list intent).
  */
 export interface ScrollElementIntoViewOptions {
     /** Pixels to subtract from the target element's `top` so it lands BELOW

package/dist/utils/scroll-into-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;+EAC2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;oFACgF;IAChF,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;6EAGyE;IACzE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAqBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAmEN"}
+{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;+EAC2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;oFACgF;IAChF,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;6EAGyE;IACzE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAsCD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAgFN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.290",
+  "version": "0.0.291-snapshot.20260618233000",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/chat-message-enhanced.tsx

@@ -12,10 +12,21 @@ import { ThinkingDisplay } from "./thinking-display"
 import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
+import { remarkMentionChips } from "./remark-mention-chips"
 import { BlockCard, type BlockCardProps } from "./entity-cards/block-card"
 import { ChatContextChipStrip } from "./chat-context-picker"
 import type { MessageSegment, MessageContent, ChatMessageEnhancedProps } from "./types"
 
+/** Inline `@marker:id` mention token in the message body (sibling of the
+ *  `[card://]` grammar) — used to filter out items rendered inline from the
+ *  chip strip below. MUST mirror the left-boundary `(^|\s)` of `MENTION_REGEX`
+ *  in `remark-mention-chips.ts`: without it this regex is WIDER than the plugin
+ *  (e.g. it matches `x@device:1` mid-word, which the plugin skips), so a context
+ *  item would be stripped from the chip strip yet never rendered inline — lost
+ *  from display entirely. The id is capture group 2 (group 1 is the boundary).
+ *  Marker lowercase; id is the mention-token charset. */
+const MENTION_MARKER_REGEX = /(^|\s)@[a-z]+:([A-Za-z0-9_.+/=-]+)/g
+
 /**
  * Same regex shape as `remarkCardLinks` — kept in lockstep so the
  * pre-scan and the remark plugin see the SAME set of markers. If the
@@ -32,7 +43,7 @@ function normalizeContent(content: MessageContent): MessageSegment[] {
 }
 
 const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>(
-  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderEntityCard, NavLinkAnchor, ...props }, ref) => {
+  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderMention, renderEntityCard, NavLinkAnchor, ...props }, ref) => {
     const isUser = role === 'user'
     const isError = role === 'error'
     const authorType = authorTypeProp ?? (isUser ? 'user' : assistantType === 'mingo' ? 'mingo' : 'fae')
@@ -51,13 +62,48 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
     // title — or, if even the ref is unknown, the bare cardId. Never
     // renders the literal `[card://...]` URL.
     const hasMarkerSupport = !!chatRefs || !!renderEntityCard
-    const cardRemarkPlugins = useMemo(
-      () => (hasMarkerSupport ? [remarkCardLinks] : []),
-      [hasMarkerSupport],
-    )
 
     const segments = useMemo(() => normalizeContent(content), [content])
 
+    // Inline `@marker:id` mentions: the composer commits these tokens when the
+    // user picks context via the `@`-flow, and the ASSISTANT routinely echoes
+    // the same `@device:machineId` token back in its reply. The lib detects the
+    // token and delegates rendering to the host's `renderMention` (mirror of
+    // `renderEntityCard`): the host returns a SELF-FETCHING chip per entity
+    // type. Enabled whenever the host opts in by supplying `renderMention`.
+    const hasMentionSupport = !!renderMention
+
+    // Ids that appear as `@marker:id` in the body → rendered inline, so they are
+    // excluded from the chip strip below (no duplicate inline + strip).
+    const inlineMentionIds = useMemo(() => {
+      const ids = new Set<string>()
+      if (!hasMentionSupport) return ids
+      for (const seg of segments) {
+        if (seg.type !== 'text' || !seg.text || !seg.text.includes('@')) continue
+        for (const mm of seg.text.matchAll(MENTION_MARKER_REGEX)) ids.add(mm[2])
+      }
+      return ids
+    }, [hasMentionSupport, segments])
+
+    // Chip strip = only context NOT already shown inline (e.g. `+`-added items).
+    const stripContextItems = useMemo(
+      () =>
+        inlineMentionIds.size > 0 && contextItems
+          ? contextItems.filter((it) => !inlineMentionIds.has(it.id))
+          : contextItems,
+      [contextItems, inlineMentionIds],
+    )
+
+    // Markdown plugins per message: card markers (assistant) + mention tokens
+    // (user). Each is gated independently so neither fires without its data.
+    const cardRemarkPlugins = useMemo(
+      () => [
+        ...(hasMarkerSupport ? [remarkCardLinks] : []),
+        ...(hasMentionSupport ? [remarkMentionChips] : []),
+      ],
+      [hasMarkerSupport, hasMentionSupport],
+    )
+
     // Cross-render cache of rendered inline-card nodes, keyed by `type:id`.
     // A fetch-mode card lives inside the assistant message, which re-renders on
     // every stream chunk (and the whole list re-renders when a new message
@@ -230,7 +276,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
     }, [hasMarkerSupport, chatRefs, renderEntityCard, segments])
 
     const cardComponentOverrides = useMemo(() => {
-      if (!hasMarkerSupport) return undefined
+      if (!hasMarkerSupport && !hasMentionSupport) return undefined
       const refs = chatRefs ?? {}
       const inlineByKey = renderingPlan?.inlineByKey
       return {
@@ -240,6 +286,19 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
         // paragraph as siblings — the inline pill stays at the marker
         // position. Other href schemes pass through unchanged.
         a: ({ href, children, className: linkClassName, ...rest }: any) => {
+          // Inline entity mention `@marker:id`, emitted as a `mention://marker:id`
+          // link by `remarkMentionChips`. Delegate to the host's `renderMention`
+          // (mirror of the `card://` → `renderEntityCard` path): the host returns
+          // a self-fetching chip for that entity type. Null/unknown → raw token.
+          if (typeof href === 'string' && href.startsWith('mention://')) {
+            const stripped = href.slice('mention://'.length)
+            const sepIdx = stripped.indexOf(':')
+            const marker = sepIdx === -1 ? stripped : stripped.slice(0, sepIdx)
+            const id = sepIdx === -1 ? '' : stripped.slice(sepIdx + 1)
+            const node = renderMention?.({ marker, id })
+            if (node != null) return <>{node}</>
+            return <span className="text-ods-text-secondary opacity-60">{children}</span>
+          }
           if (typeof href === 'string' && href.startsWith('card://')) {
             const stripped = href.slice('card://'.length)
             const sepIdx = stripped.lastIndexOf(':')
@@ -313,7 +372,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           )
         },
       }
-    }, [hasMarkerSupport, chatRefs, renderingPlan, NavLinkAnchor])
+    }, [hasMarkerSupport, hasMentionSupport, renderMention, chatRefs, renderingPlan, NavLinkAnchor])
 
     const getAvatarProps = () => {
       const displayName = name || (isUser ? "User" : assistantType === 'mingo' ? "Mingo" : "Fae")
@@ -529,9 +588,9 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
 
           {/* Attached entity-context chips (user bubbles). Read-only — no
               remove affordance once the message is sent (Figma 31:28709). */}
-          {contextItems && contextItems.length > 0 && (
+          {stripContextItems && stripContextItems.length > 0 && (
             <ChatContextChipStrip
-              items={contextItems}
+              items={stripContextItems}
               resolveIcon={resolveContextIcon}
               className="mt-2"
             />
@@ -566,6 +625,9 @@ const MemoizedChatMessageEnhanced = memo(ChatMessageEnhanced, (prevProps, nextPr
     // message (it's set once on the optimistic send and never mutated).
     prevProps.contextItems === nextProps.contextItems &&
     prevProps.resolveContextIcon === nextProps.resolveContextIcon &&
+    // Host keeps this stable (module const / useCallback), so reference
+    // equality holds across streaming chunks.
+    prevProps.renderMention === nextProps.renderMention &&
     prevProps.renderEntityCard === nextProps.renderEntityCard &&
     prevProps.NavLinkAnchor === nextProps.NavLinkAnchor
   )

package/src/components/chat/chat-message-list.tsx

@@ -107,6 +107,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       onLoadMore,
       renderEntityCard,
       resolveContextIcon,
+      renderMention,
       NavLinkAnchor,
       ...props
     },
@@ -538,6 +539,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
                   chatRefs={message.chatRefs}
                   contextItems={message.contextItems}
                   resolveContextIcon={resolveContextIcon}
+                  renderMention={renderMention}
                   renderEntityCard={renderEntityCard}
                   NavLinkAnchor={NavLinkAnchor}
                 />

package/src/components/chat/embeddable-chat.tsx

@@ -259,6 +259,18 @@ export interface EmbeddableChatProps {
    * `config.search`. Omit to disable the feature entirely.
    */
   contextPicker?: ChatContextPickerConfig
+  /**
+   * Host renderer for inline AI mentions `@marker:id` (e.g. the assistant
+   * echoing `@device:<machineId>` in its reply). DIRECT MIRROR of
+   * `renderEntityCard` for the `[card://]` grammar: the lib detects the token,
+   * parses `{marker, id}`, and renders whatever the host returns — typically a
+   * SELF-FETCHING chip (each entity type has its own fetcher) that resolves its
+   * own display name by id. SEPARATE from `contextPicker`/`contextItems` (the
+   * USER's attachments). Keep the function identity stable (module const /
+   * `useCallback`) so the thread's streaming memo holds. Return null for a
+   * marker the host can't render → the lib falls back to the bare token.
+   */
+  renderMention?: (reference: { marker: string; id: string }) => React.ReactNode
 }
 
 // =============================================================================
@@ -269,6 +281,22 @@ export interface EmbeddableChatProps {
 const formatRelativePath = (p: string): string =>
   p.replace(/^\/+/, '').replace(/\/+$/, '')
 
+/**
+ * The committed `@`-mention text token, derived from a `type:id` identity key.
+ * The TYPE is replaced with its backend mention MARKER (`markerByType`, e.g.
+ * `KB_ARTICLE → 'kb'`), falling back to a lowercased type when the host didn't
+ * declare one (`@device:…`, not `@DEVICE:…`); the `id` is left verbatim. The
+ * structured context items keep the original (upper) entity-kind for the wire
+ * enum, so this only affects the inline draft token. `[A-Za-z…]` in the input
+ * regex matches either case, so commit/strip/detect stay symmetric.
+ */
+const mentionTokenOf = (key: string, markerByType: Map<string, string>): string => {
+  const ci = key.indexOf(':')
+  const type = ci === -1 ? key : key.slice(0, ci)
+  const id = ci === -1 ? '' : key.slice(ci + 1)
+  return `${markerByType.get(type) ?? type.toLowerCase()}:${id}`
+}
+
 /**
  * Fallback fan-out when the model didn't cite any source. Show the top-N
  * retrieved sources instead of zero chips. Mirrors Perplexity's behavior.
@@ -662,6 +690,7 @@ function EmbeddableChatInner({
   mingoWelcome,
   guideWelcome,
   contextPicker,
+  renderMention,
 }: EmbeddableChatProps) {
   // `shell === 'none'` means the consumer hosts us inside their own panel
   // (e.g. AppLayoutDrawer in openframe-frontend). Several drawer-shell
@@ -972,6 +1001,15 @@ function EmbeddableChatInner({
     mentionKeyRef.current = null
   }, [activeDialogId, activeMode])
 
+  // Map each entity type to its backend mention marker (host-declared on the
+  // entity type). Drives the committed `@marker:id` token; missing markers fall
+  // back to a lowercased type inside `mentionTokenOf`.
+  const mentionMarkerByType = useMemo(() => {
+    const m = new Map<string, string>()
+    for (const t of contextPicker?.entityTypes ?? []) if (t.marker) m.set(t.type, t.marker)
+    return m
+  }, [contextPicker?.entityTypes])
+
   const toggleContextItem = useCallback(
     (item: ChatContextItem) => {
       const key = `${item.type}:${item.id}`
@@ -990,7 +1028,7 @@ function EmbeddableChatInner({
         )
         const grows = !alreadySelected && !mentionKeyRef.current
         if (grows && contextItems.length >= contextMaxItems) return
-        chatInputRef.current?.commitMention(key)
+        chatInputRef.current?.commitMention(mentionTokenOf(key, mentionMarkerByType))
         setContextItems((prev) => {
           const withoutPrevMention = mentionKeyRef.current
             ? prev.filter((p) => `${p.type}:${p.id}` !== mentionKeyRef.current)
@@ -1010,7 +1048,7 @@ function EmbeddableChatInner({
         return [...prev, item]
       })
     },
-    [contextMaxItems, contextItems],
+    [contextMaxItems, contextItems, mentionMarkerByType],
   )
 
   const removeContextItem = useCallback((item: ChatContextItem) => {
@@ -1022,10 +1060,10 @@ function EmbeddableChatInner({
     if (mentionKeyRef.current === key) {
       mentionKeyRef.current = null
       const cur = chatInputRef.current?.getValue() ?? ''
-      const next = cur.replace(`@${key}`, '').replace(/\s{2,}/g, ' ').trimStart()
+      const next = cur.replace(`@${mentionTokenOf(key, mentionMarkerByType)}`, '').replace(/\s{2,}/g, ' ').trimStart()
       chatInputRef.current?.setValue(next)
     }
-  }, [])
+  }, [mentionMarkerByType])
 
   // Draft → context reconciliation: when the user deletes the `@type:id` token
   // text, drop the matching mention item. `+`-added items have no token in the
@@ -1033,11 +1071,11 @@ function EmbeddableChatInner({
   const handleContextValueChange = useCallback((value: string) => {
     const key = mentionKeyRef.current
     if (!key) return
-    if (!value.includes(`@${key}`)) {
+    if (!value.includes(`@${mentionTokenOf(key, mentionMarkerByType)}`)) {
       setContextItems((prev) => prev.filter((p) => `${p.type}:${p.id}` !== key))
       mentionKeyRef.current = null
     }
-  }, [])
+  }, [mentionMarkerByType])
 
   const openContextPicker = useCallback(() => {
     setMentionQuery(null)
@@ -1078,6 +1116,11 @@ function EmbeddableChatInner({
     return (item: ChatContextItem) => byType.get(item.type)
   }, [contextEntityTypes])
 
+  // `renderMention` is HOST-provided (see the prop doc): the per-type renderer
+  // for inline AI mentions `@marker:id` (mirror of `renderEntityCard`). The lib
+  // forwards it verbatim to the message list and calls it from the `mention://`
+  // override; the host returns a self-fetching chip.
+
   // Resolve base route. Hub default mapping: flamingo → /knowledge-base,
   // anything else → /data-room. Embedders override per platform. An embedder that
   // doesn't host an in-app doc viewer should NOT pass an empty baseRoute (that just
@@ -1515,6 +1558,7 @@ function EmbeddableChatInner({
                       assistantIcon={mingoAssistantIcon}
                       renderEntityCard={renderEntityCard}
                       resolveContextIcon={resolveContextIcon}
+                      renderMention={renderMention}
                       NavLinkAnchor={NavLinkAnchorViaRuntime}
                       className="flex-1"
                       // No inner `px`/`pb`: the panel wrapper already pads with

package/src/components/chat/hooks/use-realtime-chunk-processor.ts

@@ -365,6 +365,7 @@ export function useRealtimeChunkProcessor(
             displayName: action.displayName,
             userId: action.userId,
             streamSeq,
+            contextItems: action.contextItems,
           })
           break
 

package/src/components/chat/index.ts

@@ -38,6 +38,7 @@ export * from './model-display'
 export * from './chat-sidebar'
 export type { ChatRef } from './chat-ref.types'
 export { remarkCardLinks } from './remark-card-links'
+export { remarkMentionChips } from './remark-mention-chips'
 
 // Card-supporting UI migrated from hub `components/shared/*` + `components/blog/*`
 export {

package/src/components/chat/remark-mention-chips.ts

@@ -0,0 +1,72 @@
+/**
+ * Remark plugin that walks markdown text leaves and replaces inline entity
+ * mentions `@<marker>:<id>` (e.g. `@device:64f0a1`, `@kb:5`) with synthetic
+ * `link` mdast nodes whose `url` is `mention://<marker>:<id>` (a non-standard
+ * scheme). The downstream `<a>` component override in `chat-message-enhanced`
+ * detects that scheme and renders an inline `<Tag>`-style chip, resolving the
+ * display name from the message's `contextItems`.
+ *
+ * Sibling of `remark-card-links` (which handles the ASSISTANT-side
+ * `[card://type:id]` markers). This one handles the USER-side `@marker:id`
+ * tokens the composer commits when picking context via the `@`-mention flow.
+ *
+ * Why a remark plugin (NOT a regex on the raw markdown source): it splits only
+ * TEXT leaves, so bold / italic / list / code wrappers around a mention stay
+ * intact, and the marker disappears before any rehype-raw HTML pass.
+ *
+ * Grammar:
+ *   - marker: `[a-z]+` — the backend `ContextItemType.marker()` short form
+ *     (`device`, `script`, `ticket`, `organization`, `user`, `kb`, `policy`,
+ *     `query`, …). Always lowercase.
+ *   - id: `[A-Za-z0-9_.+/=-]+` — the mention-token charset (UUIDs with hyphens,
+ *     fleet numeric ids, etc.). Matches the composer's `MENTION_TOKEN`.
+ *   - A LEFT boundary (start-of-text or whitespace) keeps `@marker:` from
+ *     matching inside emails / mid-word (`user@host:1234` never starts a token
+ *     because the `@` isn't at a boundary).
+ */
+
+import type { Plugin } from 'unified'
+import type { Root, Text, Link } from 'mdast'
+import { visit, SKIP } from 'unist-util-visit'
+
+const MENTION_REGEX = /(^|\s)@([a-z]+):([A-Za-z0-9_.+/=-]+)/g
+
+export const remarkMentionChips: Plugin<[], Root> = () => {
+  return (tree: Root) => {
+    visit(tree, 'text', (node: Text, index, parent) => {
+      if (!parent || typeof index !== 'number') return
+      const text = node.value
+      if (!text || !text.includes('@')) return
+
+      const parts: Array<Text | Link> = []
+      let lastIndex = 0
+      MENTION_REGEX.lastIndex = 0
+      let match: RegExpExecArray | null
+      while ((match = MENTION_REGEX.exec(text)) !== null) {
+        const lead = match[1] // '' or the whitespace char before '@'
+        const marker = match[2]
+        const id = match[3]
+        const tokenStart = match.index + lead.length // position of '@'
+        if (tokenStart > lastIndex) {
+          parts.push({ type: 'text', value: text.slice(lastIndex, tokenStart) })
+        }
+        parts.push({
+          type: 'link',
+          url: `mention://${marker}:${id}`,
+          // Keep the raw token as the visible children so an unresolved mention
+          // (no matching context item) falls back to the literal text.
+          children: [{ type: 'text', value: `@${marker}:${id}` }],
+        })
+        lastIndex = match.index + match[0].length
+      }
+      if (lastIndex === 0) return // no matches
+
+      if (lastIndex < text.length) {
+        parts.push({ type: 'text', value: text.slice(lastIndex) })
+      }
+
+      parent.children.splice(index, 1, ...parts)
+      return [SKIP, index + parts.length]
+    })
+  }
+}

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

@@ -167,7 +167,7 @@ export interface RealtimeChunkCallbacks {
   /** Called when a user message request is received (echo). `streamSeq` (when
    *  the transport carries one) lets hosts stamp the synthetic so the history
    *  merge can dedup it against its persisted twin by sequence. */
-  onUserMessage?: (text: string, metadata?: { ownerType?: string; displayName?: string; userId?: string; streamSeq?: number }) => void
+  onUserMessage?: (text: string, metadata?: { ownerType?: string; displayName?: string; userId?: string; streamSeq?: number, contextItems?: Array<{ type: string; id: string }> }) => void
   /** Called when TOKEN_USAGE chunk is received with token stats */
   onTokenUsage?: (data: TokenUsageData) => void
   /** Called when a direct message is received (immediately displayed). Carries

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

@@ -132,6 +132,20 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    * glyph). Optional — chips render label-only when omitted.
    */
   resolveContextIcon?: (item: ChatContextItem) => ReactNode
+  /**
+   * Host renderer for inline AI mentions `@marker:id` — the ASSISTANT echoing
+   * `@device:<machineId>` (etc.) in its reply. DIRECT MIRROR of
+   * `renderEntityCard` for the `[card://]` grammar: the lib detects the token
+   * (via `remark-mention-chips`), parses `{marker, id}`, and renders whatever
+   * node the host returns — typically a SELF-FETCHING chip (each entity type
+   * has its own fetcher) that resolves its own display name by id. The lib
+   * stays data-agnostic: it knows nothing about entity types or how to fetch
+   * them. Return null/undefined for a marker the host can't render → the lib
+   * falls back to the bare token text. SEPARATE from `contextItems` (the user's
+   * own attachments). Keep the function identity stable (e.g. a module const or
+   * `useCallback`) so the message memo holds across streaming chunks.
+   */
+  renderMention?: (reference: { marker: string; id: string }) => React.ReactNode
   /**
    * Host-provided renderer for inline entity cards (v6.1 §B.2.7 — DRY
    * duplications #2). The OSS-lib delegates all entity-specific rendering
@@ -201,6 +215,10 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
   /** Lead-icon resolver for per-message context chips (maps a context item to
    *  its entity-type glyph). Forwarded to every message's ChatMessageEnhanced. */
   resolveContextIcon?: (item: ChatContextItem) => ReactNode
+  /** Host renderer for inline AI mentions `@marker:id` (mirror of
+   *  `renderEntityCard`). Forwarded verbatim to every message's
+   *  ChatMessageEnhanced; returns a self-fetching chip per entity type. */
+  renderMention?: (reference: { marker: string; id: string }) => React.ReactNode
   /** Host-provided renderer for inline entity cards. Forwarded verbatim
    *  to every message's ChatMessageEnhanced. v6.1 §B.2.7. */
   renderEntityCard?: (reference: ChatRef) => React.ReactNode

package/src/components/chat/types/context-item.types.ts

@@ -33,6 +33,11 @@ export interface ChatContextEntityType {
   label: string
   /** Optional icon element rendered at the row lead (host-supplied). */
   icon?: React.ReactNode
+  /** Optional backend mention marker — the SHORT token used for the committed
+   *  inline `@marker:id` reference (e.g. `'device'`, `'kb'`). When omitted the
+   *  composer falls back to a lowercased `type`. Lets the host map each kind to
+   *  the backend's exact mention vocabulary without the lib knowing it. */
+  marker?: string
 }
 
 /**

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

@@ -20,7 +20,14 @@ export type ParsedChunkAction =
   | { action: 'approval_request'; requestId: string; command: string; explanation?: string; approvalType: string }
   | { action: 'approval_batch'; requestId: string; approvalType: string; toolCalls: PendingToolCallData[] }
   | { action: 'approval_result'; requestId: string; approved: boolean; approvalType: string; resolvedByName?: string | null }
-  | { action: 'message_request'; text: string; ownerType?: string; displayName?: string; userId?: string }
+  | {
+      action: 'message_request'
+      text: string
+      ownerType?: string
+      displayName?: string
+      userId?: string
+      contextItems?: Array<{ type: string; id: string }>
+    }
   | { action: 'token_usage'; data: TokenUsageData }
   | { action: 'direct_message'; text: string; ownerType?: string; displayName?: string; userId?: string }
   | { action: 'system'; text: string }

package/src/components/chat/utils/chunk-parser.ts

@@ -155,6 +155,17 @@ export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
         ownerType: typeof data.ownerType === 'string' ? data.ownerType : undefined,
         displayName: typeof data.displayName === 'string' ? data.displayName : undefined,
         userId: typeof data.userId === 'string' ? data.userId : undefined,
+        // Entity-context refs the user attached to this message (backend
+        // `MESSAGE_REQUEST` chunk → `contextItems: [{ type, id }]`). The wire
+        // shape carries no label; the host resolves display text + icon. `label`
+        // is REQUIRED on `ChatContextItem`, so fall back to the id (same as the
+        // historical path in `process-historical-messages.ts`) — keeps both
+        // message sources producing an identical shape.
+        contextItems: Array.isArray(data.contextItems)
+          ? (data.contextItems as Array<{ type?: unknown; id?: unknown }>)
+              .filter((it) => typeof it?.type === 'string' && typeof it?.id === 'string')
+              .map((it) => ({ type: it.type as string, id: it.id as string, label: it.id as string }))
+          : undefined,
       }
 
     case MESSAGE_TYPE.TOKEN_USAGE:

package/src/components/chat/utils/nav-anchor-props.ts

@@ -15,9 +15,14 @@
  * `decideNewTab` fallback chain anywhere else.
  *
  * Rules:
- *   - `embed` mode → ALWAYS new-tab. The chat lives on the embedder
- *     origin; content lives on the hub. Same-tab nav would leave the
- *     embedder entirely.
+ *   - `embed` mode → new-tab, EXCEPT for same-origin absolute hrefs. The chat
+ *     lives on the embedder origin and most content lives on the hub (→ new
+ *     tab), but an embedder may host a few content types in-app (e.g. OpenFrame
+ *     serves releases / roadmap / guides under `/help-center`). Those are
+ *     emitted as ABSOLUTE same-origin URLs by the embedder's `composeContentUrl`;
+ *     keep them same-tab so they soft-nav in-app instead of opening a redundant
+ *     new tab on the same origin. Relative hrefs stay new-tab — in embed mode
+ *     they're hub-relative (absolutized against `defaultContentOrigin`).
  *   - `host` mode → defer to the runtime's `decideNewTab` callback
  *     (cross-platform → new-tab) or the lib's default.
  */
@@ -25,13 +30,26 @@
 import type { ChatRuntime } from '../../../contexts/chat-runtime-context'
 import { decideNewTab as libDecideNewTab } from './decide-new-tab'
 
+/** An ABSOLUTE `http(s)` URL on the current page's origin. Relative hrefs return
+ *  false (in embed mode they're hub-relative, not in-app), as do cross-origin
+ *  and non-http URLs. SSR-safe: no `window` → false. */
+function isSameOriginAbsoluteHref(href: string): boolean {
+  if (typeof window === 'undefined') return false
+  if (!/^https?:\/\//i.test(href)) return false
+  try {
+    return new URL(href).origin === window.location.origin
+  } catch {
+    return false
+  }
+}
+
 export function computeIsNewTab(
   runtime: ChatRuntime,
   href: string | null | undefined,
   targetPlatform: string | null,
 ): boolean {
   if (!href) return false
-  if (runtime.navigation.mode === 'embed') return true
+  if (runtime.navigation.mode === 'embed') return !isSameOriginAbsoluteHref(href)
   return (
     runtime.navigation.decideNewTab?.({ href, targetPlatform }) ??
     libDecideNewTab({

package/src/components/chat/utils/process-historical-messages.ts

@@ -144,6 +144,16 @@ export function processHistoricalMessages(
       const userAuthorType: AuthorType = msg.owner?.type === OWNER_TYPE.ADMIN ? 'admin' : 'user'
       messageDataArray.forEach((data) => {
         if (data.type === MESSAGE_TYPE.TEXT && 'text' in data && data.text) {
+          // `TextData.contextItems` (server: `[{ type, id }]`) — the entity
+          // context the user attached to this message. Surface it so the bubble
+          // renders its chip strip from history (no label on the wire → fall
+          // back to the id, matching the realtime path).
+          const rawContext = (data as { contextItems?: Array<{ type?: unknown; id?: unknown }> }).contextItems
+          const contextItems = Array.isArray(rawContext)
+            ? rawContext
+                .filter((c) => typeof c?.type === 'string' && typeof c?.id === 'string')
+                .map((c) => ({ type: c.type as string, id: c.id as string, label: c.id as string }))
+            : undefined
           processedMessages.push({
             id: msg.id,
             role: 'user',
@@ -152,6 +162,7 @@ export function processHistoricalMessages(
             avatar: getOwnerAvatar(msg.owner),
             authorType: userAuthorType,
             timestamp: new Date(msg.createdAt),
+            ...(contextItems && contextItems.length > 0 ? { contextItems } : {}),
           })
         }
       })
@@ -522,6 +533,16 @@ export function processHistoricalMessagesWithErrors(
       const userAuthorType: AuthorType = msg.owner?.type === OWNER_TYPE.ADMIN ? 'admin' : 'user'
       messageDataArray.forEach((data) => {
         if (data.type === MESSAGE_TYPE.TEXT && 'text' in data && data.text) {
+          // `TextData.contextItems` (server: `[{ type, id }]`) — the entity
+          // context the user attached to this message. Surface it so the bubble
+          // renders its chip strip from history (no label on the wire → fall
+          // back to the id, matching the realtime path).
+          const rawContext = (data as { contextItems?: Array<{ type?: unknown; id?: unknown }> }).contextItems
+          const contextItems = Array.isArray(rawContext)
+            ? rawContext
+                .filter((c) => typeof c?.type === 'string' && typeof c?.id === 'string')
+                .map((c) => ({ type: c.type as string, id: c.id as string, label: c.id as string }))
+            : undefined
           processedMessages.push({
             id: msg.id,
             role: 'user',
@@ -530,6 +551,7 @@ export function processHistoricalMessagesWithErrors(
             avatar: getOwnerAvatar(msg.owner),
             authorType: userAuthorType,
             timestamp: new Date(msg.createdAt),
+            ...(contextItems && contextItems.length > 0 ? { contextItems } : {}),
           })
         }
       })

package/src/components/features/.paths-display.md

@@ -44,7 +44,7 @@ import { PathsDisplay, getOpenFramePaths } from '@flamingo/ui-kit/components/fea
 | `title` | `string` | — | Optional heading above the list |
 | `description` | `string` | — | Optional subtext below the title |
 | `showCopyButtons` | `boolean` | `true` | Toggle copy button visibility |
-| `copyIconSize` | `string` | `'w-5 h-5'` | Tailwind size classes for the copy icon |
+| `copyIconSize` | `string` | `'w-6 h-6'` | Tailwind size classes for the copy icon |
 | `className` | `string` | — | Additional CSS classes for the container |
 
 > **Note:** The component renders `null` when `paths` is empty or undefined. Copy buttons only render when both `showCopyButtons` is `true` **and** `onCopyPath` is provided.

package/src/components/features/command-box.tsx

@@ -98,7 +98,7 @@ export function CommandBox({
           {title}
         </div>
       )}
-      <div className="bg-ods-card border border-ods-border rounded-[6px] p-4">
+      <div className="bg-ods-bg border border-ods-border rounded-[6px] p-4">
         <div
           className={cn(
             'text-ods-text-primary font-mono text-[14px] md:text-[16px] leading-relaxed break-all',