@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/chat/.chat-attachment-bar.md

@@ -0,0 +1,64 @@
+<!-- source-hash: f3fb53b66abf55ba1b2ac14522e64cbb -->
+Provides two composable React primitives for the chat compose-box attachment UX: a `+` add-button rendered inline in the bottom controls row, and a horizontal chip strip rendered above the textarea showing staged file previews with upload progress.
+
+## Key Components
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatAttachmentAddButton` | Component | Borderless `+` icon button for triggering file picker; renders an invisible 28×28 spacer when `attachmentsEnabled` is false to prevent layout shift |
+| `ChatAttachmentChipStrip` | Component | Horizontal strip of file chips above the textarea; returns `null` when no attachments are staged |
+| `StagedAttachment` | Interface | Shape consumed by the chip strip, mirrors the hub's `useChatAttachments` output |
+| `CHAT_ATTACHMENT_MIME_TYPES` | Constant | Allowed MIME types (JPEG, PNG, WebP, GIF, MP4, WebM, QuickTime) — excludes `image/svg+xml` for XSS safety |
+| `CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER` | Constant | Client-side cap of 5 concurrent staged files |
+
+### Internal Helpers
+
+| Name | Purpose |
+|------|---------|
+| `AttachmentChip` | Single chip: inline blob thumbnail (images), progress bar overlay, filename, status text, × remove button |
+| `useObjectUrl` | Hook managing `URL.createObjectURL` lifecycle — revokes on unmount and file change |
+| `formatFileSize` | Human-readable byte formatter (B / KB / MB / GB) |
+| `extLabel` | Extracts up to 3-char file extension for non-image chip placeholders |
+
+## Usage Example
+
+```typescript
+import {
+  ChatAttachmentAddButton,
+  ChatAttachmentChipStrip,
+  StagedAttachment,
+} from './chat-attachment-bar'
+
+function Composebox() {
+  const { attachments, addFiles, removeFile } = useChatAttachments()
+  const { attachmentsEnabled } = useChatIdentity()
+
+  return (
+    <div className="flex flex-col">
+      {/* Chip strip floats above textarea — hidden when empty */}
+      <ChatAttachmentChipStrip
+        attachments={attachments}
+        onRemove={removeFile}
+        disabled={isStreaming}
+      />
+
+      <textarea placeholder="Message…" />
+
+      {/* Bottom controls row */}
+      <div className="flex items-center gap-2">
+        <ChatAttachmentAddButton
+          attachmentsEnabled={attachmentsEnabled}
+          attachmentsCount={attachments.length}
+          onAddFiles={addFiles}
+          disabled={isStreaming}
+        />
+        <ModelDisplay />
+      </div>
+    </div>
+  )
+}
+```
+
+> **Layout stability note:** `ChatAttachmentAddButton` renders an invisible `<span>` placeholder before `attachmentsEnabled` resolves, preventing the bottom-controls row from shifting when chat identity loads asynchronously (~100–500 ms).

package/src/components/chat/.chat-container.md

@@ -1,40 +1,58 @@
-<!-- source-hash: 4cc3dbe8c03ccee87301f7253b7ee038 -->
-React component system for building chat interfaces with connection status indicators and layout management.
+<!-- source-hash: 748948c6317fda009af640633bb6c0e5 -->
+Composable React components for building a full-screen chat interface shell, including layout, header, content area, and footer sections with ODS design token styling.
 
 ## Key Components
 
-- **ConnectionIndicator**: Visual status indicator with animated states (connected, connecting, disconnected)
-- **ChatContainer**: Main wrapper component with responsive padding and full-height layout
-- **ChatHeader**: Header section with user avatar, name, connection status, and optional new chat button
-- **ChatContent**: Flexible content area that fills remaining vertical space
-- **ChatFooter**: Fixed footer section with constrained width for input controls
+| Component | Description |
+|-----------|-------------|
+| `ChatContainer` | Root full-screen wrapper with ODS background and responsive padding |
+| `ChatHeader` | Rich header with avatar, user info, connection status, ticket context, and action buttons |
+| `ChatContent` | Flex-grow scrollable content region between header and footer |
+| `ChatFooter` | Sticky footer wrapper with optional full-width or narrow-column layout |
+| `ConnectionIndicator` | Internal dot badge showing `connected` / `connecting` / `disconnected` states using ODS attention tokens |
 
 ## Usage Example
 
 ```typescript
-import { ChatContainer, ChatHeader, ChatContent, ChatFooter } from './chat-container'
+import {
+  ChatContainer,
+  ChatHeader,
+  ChatContent,
+  ChatFooter,
+} from "./chat-container"
 
-function ChatInterface() {
+export function MyChatShell() {
   return (
     <ChatContainer>
       <ChatHeader
-        userName="Grace 'Fae' Meadows"
+        userName='Grace "Fae" Meadows'
         userTitle="Your Personal Assistant"
-        userAvatar="/avatar.png"
         connectionStatus="connected"
-        serverUrl="api.flamingo.run"
-        showNewChat={true}
-        onNewChat={() => console.log('New chat')}
+        serverUrl="mcp.flamingo.run"
+        showNewChat
+        onNewChat={() => console.log("new chat")}
+        onClose={() => console.log("close")}
+        ticketInfo={{
+          title: "Printer offline – Ticket #4821",
+          meta: "Assigned to: J. Smith",
+          status: "in-progress",
+        }}
+        fullWidth
       />
       <ChatContent>
-        {/* Chat messages go here */}
+        {/* message list */}
       </ChatContent>
-      <ChatFooter>
-        {/* Input controls go here */}
+      <ChatFooter fullWidth>
+        {/* input bar */}
       </ChatFooter>
     </ChatContainer>
   )
 }
 ```
 
-The components use the OpenFrame Design System (ODS) for consistent theming and include responsive design patterns with proper accessibility attributes.
+## Notes
+
+- `fullWidth` on both `ChatHeader` and `ChatFooter` drops the default `max-w-ods-content-narrow` (≈600px) column — use this when embedding the chat in a side panel.
+- `ChatFooter.contentClassName` is a legacy escape hatch for custom `max-w` overrides; prefer `fullWidth` for standard full-panel layouts.
+- `ChatHeader` accepts a `bare` prop to remove card chrome (shadow, border, background) for flush-mounted contexts.
+- All components are `forwardRef`-compatible and spread unknown props to their root `<div>`.

package/src/components/chat/.chat-input.md

@@ -1,39 +1,56 @@
-<!-- source-hash: c743f62070e320de942ce15e154d17a9 -->
-A React component that provides an auto-resizing text input with send functionality for chat interfaces. It supports multiple states including active input, loading, and awaiting response with proper keyboard handling and accessibility features.
+<!-- source-hash: 6d459e335b05378d1756f274a61128f0 -->
+A controlled chat input component with slash-command autocomplete, send/stop functionality, and an imperative ref API for programmatic control.
 
 ## Key Components
 
-- **ChatInput** - Main forwardRef component with auto-expanding textarea
-- **handleSubmit** - Processes message sending and resets input state
-- **handleKeyDown** - Handles Enter key submission (Shift+Enter for new lines)
-- **handleChange** - Auto-resizes textarea based on content height
-- **Awaiting Response UI** - Special state showing typing indicator and status message
+### `ChatInput` (default export)
+A `forwardRef` component that renders a textarea-based chat input with:
+- **Slash command autocomplete** — triggers on `/` prefix, debounced 150ms, keyboard-navigable dropdown
+- **Send/Stop modes** — toggles between send and stop-stream actions based on `sending`/`onStop` props
+- **Awaiting response indicator** — replaces input with `ChatTypingIndicator` while waiting for a reply
+- **Auto-refocus** — restores focus after send completes or streaming stops
+
+### `ChatInputRef` (imperative handle)
+Exposed methods for parent components:
+
+| Method | Description |
+|---|---|
+| `focus()` / `blur()` | Programmatic focus control |
+| `clear()` | Resets input value |
+| `setValue(next)` | Prefills input, places caret at end |
+| `setValueAndCursor(next, offset)` | Prefills input with clamped caret position |
+| `submit(next)` | Fires `onSend` and clears, bypassing user interaction |
+| `getValue()` | Returns current value via stable ref |
+
+### `SLASH_INPUT_TRIGGER`
+Regex `/^\/([a-z][a-z0-9-]*)?$/` — kept in sync with server-side slash command registration to prevent suggesting commands the API would reject.
 
 ## Usage Example
 
 ```typescript
-import { ChatInput } from './chat-input'
-import { useRef } from 'react'
+import { useRef } from "react"
+import { ChatInput } from "./chat-input"
+import type { ChatInputRef } from "./types"
 
-function ChatInterface() {
-  const inputRef = useRef<HTMLTextAreaElement>(null)
+function ChatPanel() {
+  const inputRef = useRef<ChatInputRef>(null)
 
-  const handleSendMessage = (message: string) => {
-    console.log('Sending:', message)
-    // Process message sending logic
+  const prefillSlashCommand = () => {
+    inputRef.current?.setValue("/reboot ")
   }
 
   return (
     <ChatInput
       ref={inputRef}
-      onSend={handleSendMessage}
       sending={false}
       awaitingResponse={false}
-      placeholder="Type your message..."
-      autoFocus={true}
+      onSend={(message) => console.log("Sending:", message)}
+      onStop={() => abortStream()}
+      slashCommands={{
+        fetchCommands: async (prefix, signal) => fetchSlashCommands(prefix, signal),
+      }}
+      autoFocus
     />
   )
 }
-```
-
-The component automatically handles textarea resizing (20px to 160px max height), disables input during sending states, and provides visual feedback through the typing indicator when awaiting responses. It uses Tailwind CSS with ODS (OpenFrame Design System) tokens for consistent styling.
+```

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

@@ -1,63 +1,44 @@
-<!-- source-hash: 6d8a7239cbde9ae7f74f501951edde3f -->
-A comprehensive React component that renders enhanced chat messages with support for multiple content types, avatars, and specialized message segments like tool executions and approval requests.
+<!-- source-hash: d70b1713cdb85568acf904d7a2daa162 -->
+Renders enhanced chat messages with support for multi-segment content, inline/block entity card markers, tool executions, approval flows, and rich markdown — delegating entity resolution and navigation to host-provided callbacks.
 
 ## Key Components
 
-**Main Exports:**
-- `ChatMessageEnhanced` - Memoized forwardRef component for rendering chat messages
-- `normalizeContent()` - Utility function to convert string content to MessageSegment array
-
-**Key Features:**
-- **Multi-segment Content**: Renders text, tool executions, approval requests, and error messages
-- **Assistant Differentiation**: Supports Mingo (cyan) and Fae (pink) assistant types with distinct styling
-- **Avatar System**: Configurable avatars with fallback initials and gradient backgrounds
-- **Tool Expansion**: Collapsible tool execution displays with state management
-- **Performance Optimized**: Memoized with shallow prop comparison for re-render prevention
-
-**Content Types Supported:**
-- Text messages with markdown rendering
-- Tool execution displays (expandable)
-- Approval request messages with actions
-- Error message displays
-- Typing indicators
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatMessageEnhanced` | `forwardRef` component | Main message renderer with role-aware layout (`user`, `error`, assistant variants) |
+| `normalizeContent` | Function | Normalizes `MessageContent` (string or `MessageSegment[]`) to a uniform segment array |
+| `CARD_MARKER_REGEX` | Regex | Shared pattern matching `[card://type:id]` markers — kept in lockstep with `remarkCardLinks` |
+| `renderingPlan` | `useMemo` | Per-message plan splitting text segments at block card markers for accurate streaming position |
+| `cardComponentOverrides` | `useMemo` | Overrides `<a>` tags for `card://` URLs, resolving inline/block entity cards via host callbacks |
+
+### Supporting Displays (composed internally)
+- `ToolExecutionDisplay` — renders tool call segments
+- `ApprovalRequestMessage` / `ApprovalBatchMessage` — approval flow segments
+- `ErrorMessageDisplay` — error role messages
+- `ContextCompactionDisplay` — context compaction events
+- `ThinkingDisplay` — streaming thinking segments
 
 ## Usage Example
 
 ```typescript
-import { ChatMessageEnhanced } from "./chat-message-enhanced"
-
-// Basic text message
 <ChatMessageEnhanced
   role="assistant"
   assistantType="mingo"
-  content="Hello! How can I help you today?"
-  timestamp={new Date()}
-  showAvatar={true}
-/>
-
-// Multi-segment message with tool execution
-<ChatMessageEnhanced
-  role="assistant" 
-  assistantType="fae"
   content={[
-    { type: 'text', text: 'Let me check that for you.' },
-    { 
-      type: 'tool_execution',
-      data: {
-        integratedToolType: 'api',
-        toolFunction: 'getData',
-        status: 'completed'
-      }
-    }
+    { type: 'text', text: 'Here is your ticket [card://ticket:123].' },
+    { type: 'tool_execution', toolName: 'search', result: '...' },
   ]}
-  name="Fae Assistant"
+  chatRefs={{
+    'ticket:123': { type: 'ticket', id: '123', title: 'Login bug', url: '/tickets/123' },
+  }}
+  renderEntityCard={(ref) => <TicketPill ref={ref} />}
+  NavLinkAnchor={({ href, children }) => <Link href={href}>{children}</Link>}
+  showAvatar
 />
+```
 
-// User message
-<ChatMessageEnhanced
-  role="user"
-  content="Can you help me with my query?"
-  name="John Doe"
-  avatar="/user-avatar.png"
-/>
-```
+## Notes
+
+- **Data-agnostic**: the library never imports entity types or routing — the host provides `renderEntityCard` and `NavLinkAnchor`.
+- Block card markers split their text segment so block payloads render at the marker position during streaming, not appended at the end.
+- Three distinct fallbacks for unresolved `card://` hrefs prevent LLM hallucinations from appearing as real cards.

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

@@ -1,54 +1,67 @@
-<!-- source-hash: 4fd65378ba4e066ad8332a944f5ef739 -->
-A scrollable chat interface component that displays a list of chat messages with automatic scrolling behavior, skeleton loading states, and pending approval messages.
+<!-- source-hash: ddaad2500e41f9ee61eff7435b990d72 -->
+A scrollable chat message list component with stick-to-bottom behavior, prepend anchoring for load-older pagination, and streaming indicators.
 
 ## Key Components
 
-- **ChatMessageList**: Main forwardRef component that renders chat messages in a scrollable container
-- **Auto-scroll logic**: Maintains scroll position at bottom when new messages arrive or user sends messages
-- **Scroll detection**: Tracks user scroll behavior to determine when to disable auto-scrolling
-- **Loading states**: Shows skeleton placeholder while messages are loading
-- **Pending approvals**: Sticky section at bottom for approval-required messages
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatMessageList` | `forwardRef` Component | Main scrollable message list with auto-scroll management |
+| `STREAMING_WORDS` | `const` | Flamingo-themed cycling phrases shown during AI streaming |
+| `hasNonEmptyContent` | Helper Function | Checks if a `MessageContent` value carries visible text |
+| `disposeAnchorWatcher` | Helper Function | Idempotent teardown for `AnchorWatcher` instances |
+| `AnchorWatcher` | Interface | Tracks `ResizeObserver` + timeout for top-anchor settle window |
+
+## Key Props (`ChatMessageListProps`)
+
+| Prop | Description |
+|------|-------------|
+| `messages` | Array of chat messages to render |
+| `dialogId` | Triggers instant scroll-to-bottom on dialog change |
+| `isLoading` / `isTyping` | Controls skeleton and streaming indicator visibility |
+| `autoScroll` | Enables/disables stick-to-bottom behavior |
+| `hasNextPage` / `onLoadMore` | Infinite scroll upward (load-older pagination) |
+| `renderEntityCard` | Custom renderer for entity card messages |
 
 ## Usage Example
 
 ```typescript
-import { ChatMessageList } from './chat-message-list'
-import { useRef } from 'react'
+import { ChatMessageList } from "@/components/chat"
+
+const messages = [
+  { id: "1", role: "user", content: "Hello!" },
+  { id: "2", role: "assistant", content: "Hi there!" },
+]
 
-function ChatInterface() {
+export function ChatPanel() {
   const listRef = useRef<HTMLDivElement>(null)
-  
-  const messages = [
-    {
-      id: '1',
-      role: 'user' as const,
-      content: 'Hello!',
-      timestamp: new Date(),
-    },
-    {
-      id: '2', 
-      role: 'assistant' as const,
-      content: 'Hi there! How can I help?',
-      timestamp: new Date(),
-      assistantType: 'mingo' as const
-    }
-  ]
 
   return (
     <ChatMessageList
       ref={listRef}
       messages={messages}
-      dialogId="chat-123"
-      isLoading={false}
+      dialogId="conv-abc123"
       isTyping={false}
       autoScroll={true}
       showAvatars={true}
-      assistantType="mingo"
-      pendingApprovals={[]}
-      className="h-96"
+      hasNextPage={true}
+      onLoadMore={() => fetchOlderMessages()}
     />
   )
 }
 ```
 
-The component handles complex scroll behavior including touch gestures, wheel events, and automatic positioning when dialogs change or new messages arrive.
+## Scroll Management Strategy
+
+The component uses [`use-stick-to-bottom`](https://github.com/stackblitz-labs/use-stick-to-bottom) (same library powering bolt.new) with three additional behaviors layered on top:
+
+```mermaid
+graph TD
+    A["Message Update"] --> B{"Trigger Type?"}
+    B -->|"Dialog changed"| C["scrollToBottom instant"]
+    B -->|"First message"| C
+    B -->|"New user message"| C
+    B -->|"Streaming assistant"| D["Library spring physics"]
+    A --> E{"Content prepended?"}
+    E -->|"Load-older"| F["Preserve viewport via scrollTop delta"]
+    E -->|"No prepend"| G["Update scrollHeight snapshot"]
+```

package/src/components/chat/.chat-message-skeleton.md

@@ -1,36 +1,40 @@
-<!-- source-hash: 200f61920444318158300267a27ad52c -->
-A React component that provides animated skeleton placeholders for chat messages and message lists, supporting both user and AI assistant (Mingo/Fae) message types with contextual styling and avatars.
+<!-- source-hash: dc7cb2f1d39ceeb5b0684dbef38a8d20 -->
+Animated loading skeleton components that simulate the layout of chat messages while content is being fetched, matching the `ChatMessageEnhanced` hanging-avatar layout.
 
 ## Key Components
 
-- **`ChatMessageSkeleton`** - Single message skeleton with avatar, name, timestamp, and content placeholders
-- **`ChatMessageListSkeleton`** - Full chat message list with configurable message count and assistant types
-- **Props interfaces** - `ChatMessageSkeletonProps` and `ChatMessageListSkeletonProps` for type safety
+### `ChatMessageSkeleton`
+Renders a single animated placeholder message with pulsing blocks for the avatar, sender name, timestamp, and multi-line message content.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
+| `showAvatar` | `boolean` | `true` | Whether to render the avatar skeleton |
+| `isUser` | `boolean` | `false` | Applies user-message styling (no card background, no avatar) |
+| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Controls avatar gradient — cyan for Mingo, pink for Fae |
+
+### `ChatMessageListSkeleton`
+Renders a scrollable list of `ChatMessageSkeleton` items, mimicking a full chat viewport during initial load.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `messageCount` | `number` | `6` | Number of skeleton messages to render |
+| `showAvatars` | `boolean` | `true` | Passed through to each `ChatMessageSkeleton` |
+| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Applied to all assistant messages |
+| `contentClassName` | `string` | — | Overrides default horizontal padding on the content wrapper |
 
 ## Usage Example
 
 ```typescript
-// Single message skeleton
-<ChatMessageSkeleton 
-  showAvatar={true}
-  isUser={false}
-  assistantType="mingo"
-  className="my-4"
-/>
+// Single message skeleton (e.g. while streaming)
+<ChatMessageSkeleton assistantType="mingo" showAvatar />
 
-// Full chat list skeleton (loading state)
+// Full chat list skeleton on initial page load
 <ChatMessageListSkeleton
   messageCount={8}
-  showAvatars={true}
   assistantType="fae"
-  contentClassName="px-6"
-/>
-
-// User message skeleton
-<ChatMessageSkeleton 
-  isUser={true}
-  showAvatar={false}
+  showAvatars={true}
 />
 ```
 
-The component features gradient avatar placeholders (cyan for Mingo, pink for Fae), responsive layout with flex containers, and smooth scrolling for the message list. All skeleton elements use the `animate-pulse` class and themed colors from the OpenFrame design system (`ods-*` classes).
+> Every third message (`index % 3 === 0`) is rendered as a user bubble; the rest render as assistant messages with the appropriate Mingo/Fae avatar gradient.

package/src/components/chat/.chat-panel-context.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 1d656526a500eeade83769cf600951b1 -->
+React context providing chat panel affordances to deeply nested descendants without prop drilling.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatPanelHandle` | Interface | Shape of the context value; exposes `closeChat()` |
+| `ChatPanelContext` | `Context<ChatPanelHandle \| null>` | Raw context object; defaults to `null` when no provider is mounted |
+| `useChatPanel` | Hook | Optional consumer; returns `null` safely outside a provider |
+
+## Usage Example
+
+**Provider** (in `EmbeddableChat` or equivalent shell):
+
+```typescript
+import { ChatPanelContext } from './chat-panel-context'
+
+function EmbeddableChat() {
+  const handleClose = () => { /* dismiss panel */ }
+
+  return (
+    <ChatPanelContext.Provider value={{ closeChat: handleClose }}>
+      {/* card dispatcher and all descendants */}
+    </ChatPanelContext.Provider>
+  )
+}
+```
+
+**Consumer** (e.g. `BlogCard`, `ProgramCard`, any inline card):
+
+```typescript
+import { useChatPanel } from './chat-panel-context'
+
+function BlogCard({ href }: { href: string }) {
+  const chatPanel = useChatPanel()
+
+  const handleClick = (e: React.MouseEvent) => {
+    const isSameTab = !e.metaKey && !e.ctrlKey
+    if (isSameTab) {
+      chatPanel?.closeChat() // null-safe — works outside provider too
+    }
+  }
+
+  return <a href={href} onClick={handleClick}>Read more</a>
+}
+```
+
+## Notes
+
+- Returns `null` when consumed outside a provider (tests, standalone card renders) — always use optional chaining (`chatPanel?.closeChat()`).
+- Intentionally minimal; add new affordances to `ChatPanelHandle` only when multiple card types need the same panel-level behavior.

package/src/components/chat/.chat-ref.types.md

@@ -0,0 +1,42 @@
+<!-- source-hash: f33597ddf2bdac88dfe784aaa957aacd -->
+Defines the wire schema for inline entity references emitted by the chat backend and embedded within assistant message bodies.
+
+## Key Components
+
+### `ChatRef` Interface
+
+The primary export — mirrors `ChatRef` from the multi-platform-hub server. Consumed by `<ChatMessageEnhanced renderEntityCard={...} />` to expand `[card://<type>:<id>]` markers in assistant responses into host-rendered JSX cards.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `string` | Opaque document type from the host's RAG config (e.g. `'webinar'`, `'customer_interview'`) |
+| `id` | `string` | Primary key — opaque string downstream |
+| `title` | `string` | Display title used for fallback rendering when host renderer returns null |
+| `url` | `string \| null` | Resolved external URL; null when no public link exists |
+| `sourceRepo` | `string?` | `RagTableConfig.id` driving icon/label lookup; optional for backward-compat |
+| `targetPlatform` | `string \| null \| undefined` | Platform owning the `url` destination — enables deterministic same-app vs. cross-app routing |
+| `date` | `string?` | ISO date for the entity's canonical timestamp |
+| `preview` | `string?` | PII-sanitized hover preview text |
+| `metadata` | `Record<string, unknown>?` | Type-specific extras passed opaquely; used by `slack_message` refs to ship resolved `channelName`/`userName` |
+
+## Usage Example
+
+```typescript
+// Host supplies a renderer; OSS-lib stays agnostic of entity types
+const ref: ChatRef = {
+  type: 'slack_message',
+  sourceRepo: 'slack-messages',
+  id: 'msg_abc123',
+  title: 'Deployment discussion',
+  url: 'https://myworkspace.slack.com/archives/C01/p123',
+  targetPlatform: 'flamingo',
+  date: '2024-11-01T14:30:00Z',
+  preview: 'Discussed rollback strategy for v2.4...',
+  metadata: { channelName: '#deployments', userName: 'alice' },
+}
+
+// Wire payload shape: refs map keyed by "<type>:<id>"
+type RefsMap = Record<`${string}:${string}`, ChatRef>
+```
+
+> The OSS-lib has **no knowledge** of entity types or rendering logic. The host owns both the type vocabulary and the card renderer — `ChatRef` is purely a typed transport contract.