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

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

@@ -1,43 +1,52 @@
-<!-- source-hash: 8b8e1235435b49c60314ec7083f68f70 -->
-A loading state component that displays skeleton placeholders for a chat sidebar interface while data is being fetched. Provides animated placeholders for both individual dialog items and the complete sidebar structure.
+<!-- source-hash: aae524b6903a622a00d4f048e78ca2ef -->
+Skeleton loading components for the chat sidebar UI, providing animated placeholder states while chat dialog data is being fetched.
 
 ## Key Components
 
-- **`DialogListItemSkeleton`** - Renders a single animated skeleton placeholder for a chat dialog item, including title, timestamp, and chevron placeholders
-- **`ChatSidebarSkeleton`** - Main skeleton component that displays a complete sidebar with optional "Start New Chat" button and configurable number of dialog item skeletons
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatSidebarSkeleton` | `React.ForwardRefExoticComponent` | Full sidebar skeleton with optional new chat button and configurable dialog count |
+| `DialogListItemSkeleton` | `React.ForwardRefExoticComponent` | Individual chat list item skeleton with animated title, timestamp, and chevron placeholders |
+
+### Props
+
+**`ChatSidebarSkeletonProps`**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
+| `dialogCount` | `number` | `8` | Number of skeleton dialog items to render |
+| `showNewChatButton` | `boolean` | `true` | Toggle the disabled "Start New Chat" button header |
+
+**`DialogListItemSkeletonProps`**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
 
 ## Usage Example
 
 ```typescript
-import { ChatSidebarSkeleton } from './components/chat-sidebar-skeleton'
+import { ChatSidebarSkeleton, DialogListItemSkeleton } from "./chat-sidebar-skeleton"
+
+// Full sidebar skeleton during data load
+function ChatLayout() {
+  const { dialogs, isLoading } = useDialogs()
 
-function ChatInterface() {
-  const { data: dialogs, isLoading } = useDialogs()
-  
   if (isLoading) {
     return (
-      <ChatSidebarSkeleton 
-        dialogCount={5} 
+      <ChatSidebarSkeleton
+        dialogCount={5}
         showNewChatButton={true}
-        className="shadow-lg"
       />
     )
   }
-  
+
   return <ChatSidebar dialogs={dialogs} />
 }
 
-// For individual dialog skeleton during incremental loading
-import { DialogListItemSkeleton } from './components/chat-sidebar-skeleton'
-
-function DialogList({ dialogs, isLoadingMore }) {
-  return (
-    <div>
-      {dialogs.map(dialog => <DialogItem key={dialog.id} {...dialog} />)}
-      {isLoadingMore && <DialogListItemSkeleton />}
-    </div>
-  )
+// Standalone skeleton item for custom lists
+function CustomList() {
+  return <DialogListItemSkeleton className="opacity-50" />
 }
-```
-
-The component uses the OpenFrame Design System (ODS) classes for consistent theming and includes pulse animations for a polished loading experience. Both components are forwardRef-enabled for advanced ref patterns.
+```

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

@@ -1,43 +1,48 @@
-<!-- source-hash: 1f5a70892052e18bb61f57fa7efa791d -->
-A React chat sidebar component with dialog list functionality and infinite scroll support for AI chat interfaces.
+<!-- source-hash: eca198ef18bcc431169bc6caeb87161d -->
+A sidebar component for chat navigation that displays a list of dialogs, supports infinite scroll pagination, and provides controls for creating new chats.
 
 ## Key Components
 
-- **`DialogListItem`** - Individual chat dialog item with click handling, timestamp formatting, and unread message indicators
-- **`ChatSidebar`** - Main sidebar container with new chat button, empty state, and scrollable dialog list
-- **`formatTimestamp()`** - Utility function for formatting dialog timestamps in MM/DD/YYYY, HH:MM format
-
-## Features
-
-- **Infinite Scroll** - Automatically loads more dialogs when scrolling near bottom using IntersectionObserver
-- **Loading States** - Shows skeleton placeholders during initial load and pagination
-- **Empty State** - Displays helpful message when no chats exist
-- **Active Dialog** - Highlights currently selected chat with accent border
-- **Unread Indicators** - Shows unread message count badges or chevron icons
-- **Responsive Design** - Fixed 320px width with proper overflow handling
+### `ChatSidebar`
+The main container component that renders the sidebar with:
+- **New Chat button** — triggers `onNewChat` callback
+- **Dialog list** — scrollable list with infinite scroll via `IntersectionObserver`
+- **Empty state** — shown when no dialogs exist and no `children` are provided
+- **Custom content slot** — renders `children` instead of the dialog list when provided
+- **Loading skeleton** — displays `ChatSidebarSkeleton` when `isLoading` is true and no dialogs are present
+
+### `DialogListItem`
+A single chat entry in the sidebar list. Displays:
+- Chat title (truncated with tooltip)
+- Formatted timestamp (`MM/DD/YYYY, HH:MM`)
+- Unread message badge (capped at `99+`) or a chevron arrow when no unread messages exist
+- Active state with accent border and background highlight
 
 ## Usage Example
 
 ```typescript
-import { ChatSidebar } from './chat-sidebar'
+import { ChatSidebar } from "./chat-sidebar"
 
-function ChatInterface() {
-  const [dialogs, setDialogs] = useState([])
-  const [activeDialogId, setActiveDialogId] = useState(null)
-  
+function App() {
   return (
     <ChatSidebar
-      dialogs={dialogs}
-      activeDialogId={activeDialogId}
-      onDialogSelect={setActiveDialogId}
-      onNewChat={() => console.log('Starting new chat')}
-      hasNextPage={true}
-      onLoadMore={() => console.log('Loading more dialogs')}
+      dialogs={[
+        { id: "1", title: "Network Issue", timestamp: new Date(), unreadMessagesCount: 3 },
+        { id: "2", title: "Server Setup", timestamp: new Date() },
+      ]}
+      activeDialogId="1"
       isLoading={false}
+      isCreatingDialog={false}
+      hasNextPage={true}
       isFetchingNextPage={false}
+      onNewChat={() => console.log("New chat")}
+      onDialogSelect={(id) => console.log("Selected:", id)}
+      onLoadMore={() => fetchNextPage()}
     />
   )
 }
 ```
 
-The component uses OpenFrame's design system classes (`ods-*`) and supports both controlled dialog lists and custom children content for flexible chat interfaces.
+## Infinite Scroll
+
+Pagination is handled automatically using an `IntersectionObserver` anchored to the bottom of the scroll container. When the sentinel element enters the viewport and `hasNextPage` is `true`, `onLoadMore` is called. Skeleton items are shown while `isFetchingNextPage` is active.

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

@@ -0,0 +1,39 @@
+<!-- source-hash: 6e8a04ae19bb53e1b3779c86e3a511c1 -->
+Scrollable list component that renders a collection of `ChatTicketItem` cards with dynamic edge-fade masking based on scroll position.
+
+## Key Components
+
+- **`ChatTicketList`** — `forwardRef` component that wraps a scrollable ticket list with fade-in/out gradient masks at the top and bottom edges to indicate overflow content
+- **`getMask(top, bottom)`** — Pure utility that computes a CSS `linear-gradient` mask string based on whether the scroll container has hidden content above or below
+- **`updateFade`** — Scroll handler that compares `scrollTop`, `scrollHeight`, and `clientHeight` to toggle `fadeTop`/`fadeBottom` state, also triggered via `useLayoutEffect` when the ticket count changes
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `tickets` | `ChatTicketItemData[]` | Array of ticket data to render |
+| `onTicketClick` | `(ticketId: string) => void` | Optional click handler passed to each item |
+| `className` | `string` | Additional CSS classes |
+
+## Usage Example
+
+```typescript
+import { ChatTicketList } from './chat-ticket-list'
+
+const tickets = [
+  { id: 'TKT-001', title: 'VPN not connecting', status: 'open' },
+  { id: 'TKT-002', title: 'Printer offline', status: 'pending' },
+]
+
+function ChatSidebar() {
+  return (
+    <ChatTicketList
+      tickets={tickets}
+      onTicketClick={(id) => console.log('Selected ticket:', id)}
+      className="max-h-96"
+    />
+  )
+}
+```
+
+> Returns `null` when `tickets` is empty. Border radius and top/bottom borders are conditionally removed at scroll edges to visually blend with the fade mask.

package/src/components/chat/.context-compaction-display.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 4f36d6b4b32c3b253b88e445f6e633a8 -->
+A display component that shows context compaction status in a styled card, indicating either an in-progress summarization or a completed one.
+
+## Key Components
+
+- **`ContextCompactionDisplay`** — A forwarded-ref `div` component that renders a status banner with a label and icon based on the `status` prop
+- **`status`** — Accepts `'started'` (in-progress) or any other value (completed), driving both the label text and icon displayed
+- **Icons** — Uses `DotsLoaderIcon` for in-progress state and `CheckCircleIcon` for completed state
+
+## Usage Example
+
+```typescript
+import { ContextCompactionDisplay } from "./context-compaction-display"
+
+// In-progress state
+<ContextCompactionDisplay status="started" />
+// Renders: "Context limit reached. Summarizing earlier messages." + spinner
+
+// Completed state
+<ContextCompactionDisplay status="completed" />
+// Renders: "Earlier context summarized." + check icon
+
+// With custom className
+<ContextCompactionDisplay
+  status="done"
+  className="my-2 w-full"
+/>
+```
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `status` | `string` | `'started'` shows loader; any other value shows check icon |
+| `className` | `string` | Optional additional CSS classes |
+| `ref` | `React.Ref<HTMLDivElement>` | Forwarded ref to the root `div` |

package/src/components/chat/.cycling-phrase.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 9194bff6a46e5277230795354c61e35e -->
+A React component that renders a terminal-style cycling text animation, morphing through a list of words character-by-character with a blinking block cursor.
+
+## Key Components
+
+### `CyclingPhrase`
+The default export. Cycles through `words` indefinitely using a left-to-right character overwrite morph — each character position transitions from the current word to the next, then holds before advancing.
+
+### `CyclingPhraseProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `words` | `readonly string[]` | — | Words to cycle through |
+| `className` | `string` | — | Applied to outer `<span>` |
+| `charMs` | `number` | `60` | Milliseconds per character during morph |
+| `holdMs` | `number` | `4500` | Milliseconds to hold fully-typed word |
+
+### State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Morphing
+    Morphing --> Holding: cursor >= maxLen
+    Holding --> Morphing: after holdMs
+```
+
+## Usage Example
+
+```typescript
+import { CyclingPhrase } from "./cycling-phrase"
+
+export function StatusBanner() {
+  return (
+    <p>
+      Mingo is{" "}
+      <CyclingPhrase
+        words={["Thinking", "Analyzing", "Vibing"]}
+        charMs={60}
+        holdMs={3000}
+        className="font-mono text-yellow-400"
+      />
+    </p>
+  )
+}
+```
+
+## Notes
+
+- **Layout stable**: width is pinned to the longest word using an invisible placeholder `<span>`, preventing layout shift as words change length.
+- **Accessible**: visible text uses `aria-live="polite"`; the cursor block and placeholder are `aria-hidden`.
+- **Style injection**: `BLINK_KEYFRAMES` is injected via `dangerouslySetInnerHTML` once per render tree — safe for multiple instances since CSS `@keyframes` rules are idempotent.
+- A static `...` suffix always follows the word.

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

@@ -0,0 +1,48 @@
+<!-- source-hash: c87e4b417e41397ff1753b0ea0848f78 -->
+Portable, lib-safe port of the hub's `<GlobalAskAI>` chat panel component, decoupled from all hub-only imports by routing navigation, identity, and transport decisions through a `useRequiredChatRuntime()` context hook.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `EmbeddableChat` | Component | Main embeddable chat panel with controlled/uncontrolled open state |
+| `EmbeddableChatProps` | Interface | Full prop surface for the component |
+| `dispatchSlashCommandAction` | Function | Maps slash-command action IDs (`browse`, `search`, `find`, `display`) to `ChatInputRef` mutations |
+| `resolveChipIcon` | Function | Resolves a `ChatSource` to a Lucide icon via the icon registry |
+| `SKELETON_ROW_VARIANTS` | Constant | Deterministic width palette for loading skeleton rows |
+| `FALLBACK_TOP_RETRIEVED` | Constant | Number of fallback source chips shown when the model cites no sources (default: `3`) |
+
+## Usage Example
+
+```typescript
+// Host wires the runtime once at root
+<HubRuntimeProvider source="hub" user={currentUser}>
+  <EmbeddableChat
+    emptyStateGreeting="How can I help you today?"
+    suggestedQueries={['How do I reset a password?', 'Show open tickets']}
+    enabledRagTableIds={enabledTableIds}
+    modes={{
+      guide: { tableIdForDocumentType },
+      mingo: { agentId: 'mingo-agent' },
+    }}
+    defaultActiveMode="guide"
+    extras={{ buildProgramProps, buildProductReleaseProps }}
+  />
+</HubRuntimeProvider>
+
+// Controlled open state
+<EmbeddableChat
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  showInternalTrigger={false}
+/>
+```
+
+## Runtime Substitutions
+
+| Hub Original | Lib Replacement |
+|---|---|
+| `useAuth()` | `useRequiredChatRuntime().user` |
+| `currentPlatform()` | `useRequiredChatRuntime().source` |
+| `useNavLink` / `NavLinkAnchor` | `handleChatNavClick` + `NavLinkAnchorViaRuntime` |
+| `useDocChat(source)` | `useSseChatAdapter()` (source from runtime) |

package/src/components/chat/.expand-chevron.md

@@ -0,0 +1,24 @@
+<!-- source-hash: 53782aa07fbb1aeb83e2d663969c62b0 -->
+A simple animated chevron icon component that rotates 180° when an expanded state is active, commonly used for accordion and collapsible UI elements.
+
+## Key Components
+
+- **`ExpandChevronProps`** — Interface accepting:
+  - `expanded: boolean` — Controls rotation state of the chevron
+  - `className?: string` — Optional class overrides
+- **`ExpandChevron`** — Client component rendering a `Chevron02DownIcon` with a smooth 200ms CSS transition
+
+## Usage Example
+
+```typescript
+import { ExpandChevron } from "./expand-chevron"
+
+// Collapsed state (chevron points down)
+<ExpandChevron expanded={false} />
+
+// Expanded state (chevron rotates 180° to point up)
+<ExpandChevron expanded={true} />
+
+// With custom class
+<ExpandChevron expanded={isOpen} className="text-ods-text-primary" />
+```

package/src/components/chat/.index.md

@@ -1,46 +1,42 @@
-<!-- source-hash: 2ee769935d6198c186d8b48450b66e01 -->
-A centralized export index for Flamingo's AI chat interface components, providing a unified entry point for all chat-related functionality including UI components, hooks, types, and utilities.
+<!-- source-hash: 4f91f1efeb0b18cbf93d3b4ed385c331 -->
+Central barrel export for the `chat` UI package — re-exports every public component, hook, utility, type, and constant from the chat feature module, making the entire surface area available via a single import path.
 
 ## Key Components
 
-### **Component Exports**
-- **Core Components**: `ChatContainer`, `ChatInput`, `ChatMessageEnhanced`, `ChatMessageList` - Primary chat interface elements
-- **Interaction Components**: `ChatQuickAction`, `ChatTypingIndicator`, `ChatSidebar` - User interaction and feedback components  
-- **Message Components**: `ApprovalRequestMessage`, `ErrorMessageDisplay` - Specialized message types
-- **Display Components**: `ToolExecutionDisplay`, `ModelDisplay` - AI tool and model information display
-
-### **Supporting Exports**
-- **Types**: TypeScript interfaces and type definitions for chat functionality
-- **Hooks**: React hooks for chat state management and interactions
-- **Utils**: Utility functions for chat operations and data processing
+| Export | Description |
+|--------|-------------|
+| `EmbeddableChat` | Top-level chat orchestrator; mount once at the app root inside a `ChatRuntimeContext.Provider` |
+| `ChatRef` | Type for imperative chat handle refs |
+| `remarkCardLinks` | Remark plugin for rendering card-style links in chat messages |
+| `NavLinkAnchorViaRuntime` | Runtime-aware navigation anchor component |
+| `SourceActionButton` | Action button with configurable density for source references |
+| `ChatAttachmentAddButton` / `ChatAttachmentChipStrip` | Attachment UI with MIME type constants and upload concurrency limits |
+| `entity-cards` | Suite of 12+ refactored entity card components |
+| `hooks` | All chat-related React hooks |
+| `utils` | Chat utility functions |
+| `types` | Shared chat types and constants |
 
 ## Usage Example
 
 ```typescript
-// Import specific components
-import { 
-  ChatContainer, 
-  ChatInput, 
-  ChatMessageList,
-  ChatTypingIndicator 
-} from '@/components/chat'
-
-// Import types for type safety
-import type { ChatMessage, ChatConfig } from '@/components/chat'
+// Import anything from the chat package via this single entry point
+import {
+  EmbeddableChat,
+  ChatAttachmentAddButton,
+  CHAT_ATTACHMENT_MIME_TYPES,
+  type ChatRef,
+  type EmbeddableChatProps,
+} from '@flamingo/chat'
+
+function AppRoot() {
+  const chatRef = useRef<ChatRef>(null)
 
-// Import hooks for state management
-import { useChatMessages, useChatInput } from '@/components/chat'
-
-function MyChat() {
-  const { messages, addMessage } = useChatMessages()
-  const { input, handleSend } = useChatInput()
-  
   return (
-    <ChatContainer>
-      <ChatMessageList messages={messages} />
-      <ChatTypingIndicator />
-      <ChatInput value={input} onSend={handleSend} />
-    </ChatContainer>
+    <ChatRuntimeContext.Provider value={runtime}>
+      <EmbeddableChat ref={chatRef} />
+    </ChatRuntimeContext.Provider>
   )
 }
-```
+```
+
+> **Note:** This file is marked `'use client'` — all exports are React Client Components or client-safe utilities, intended for browser rendering in Next.js App Router environments.

package/src/components/chat/.mingo-onboarding-card-skeleton.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 494a22f9a73827cd16b9d05722b58535 -->
+Skeleton loading components for `MingoOnboardingCard` and its list container, providing pixel-accurate placeholder UI while slash-command data is fetched from `/api/docs/commands`.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `MingoOnboardingCardSkeleton` | Component | Single-row skeleton matching the live `MingoOnboardingCard` layout — icon slot, title bar, slash-command bar, description lines, and action chips |
+| `MingoOnboardingListSkeleton` | Component | Wraps multiple `MingoOnboardingCardSkeleton` rows in the same bordered container used by the resolved list |
+| `MingoOnboardingCardSkeletonProps` | Interface | Props for controlling bar widths, description line count, and chip configuration per card |
+| `MingoOnboardingListSkeletonProps` | Interface | Props for row count and container className |
+| `ROW_VARIANTS` | Constant | Deterministic width palette cycled by index — prevents uniform appearance without `Math.random` jitter on re-mount |
+
+## Usage Example
+
+```typescript
+// Drop-in list skeleton while data loads
+import { MingoOnboardingListSkeleton } from './mingo-onboarding-card-skeleton'
+
+function SlashCommandPanel() {
+  const { data, isLoading } = useSlashCommands()
+
+  if (isLoading) {
+    return <MingoOnboardingListSkeleton rows={6} />
+  }
+
+  return <MingoOnboardingList commands={data} />
+}
+
+// Single card skeleton with custom widths
+import { MingoOnboardingCardSkeleton } from './mingo-onboarding-card-skeleton'
+
+<MingoOnboardingCardSkeleton
+  titleWidth="w-44"
+  slashWidth="w-28"
+  descriptionLines={1}
+  chipWidths={['w-16', 'w-20']}  // Pass [] to hide chip row
+/>
+```
+
+## Notes
+
+- Wrap `MingoOnboardingCardSkeleton` rows in a `rounded-md border border-ods-border overflow-hidden` container to replicate the divider behaviour — each row's `border-b last:border-b-0` forms a 1px separator matching the live list.
+- `MingoOnboardingListSkeleton` sets `role="status"`, `aria-label`, and `aria-busy` for accessible loading state announcement.

package/src/components/chat/.mingo-onboarding-card.md

@@ -0,0 +1,62 @@
+<!-- source-hash: 86ac59c4c1438a33b694f4b3fbba9291 -->
+A chat empty-state onboarding card component that renders a single slash-command or feature row, supporting optional action buttons, icons, and interactive/non-interactive modes.
+
+## Key Components
+
+### Interfaces
+
+- **`MingoOnboardingCardAction`** — Defines a single action button with `id`, `label`, and `onClick` handler
+- **`MingoOnboardingCardProps`** — Full card configuration including `icon`, `title`, `slashCommand`, `description`, `actions`, `onClick`, and `className`
+
+### Component
+
+- **`MingoOnboardingCard`** — Root component that conditionally renders as a `<button>` (when `onClick` is set and no `actions`) or a `<div>` (when `actions` are present or no `onClick`)
+
+### Behavior Logic
+
+| Condition | Rendered Element |
+|-----------|-----------------|
+| `onClick` set, no `actions` | `<button>` with hover/focus styles |
+| `actions` present | `<div>` with per-action `<button>` chips |
+| Neither | Static `<div>` |
+
+## Usage Example
+
+```typescript
+import {
+  MingoOnboardingCard,
+  MingoOnboardingCardAction,
+} from './mingo-onboarding-card'
+
+// Static card with slash command
+<MingoOnboardingCard
+  icon={<SearchIcon />}
+  title="Search Knowledge Base"
+  slashCommand="/search"
+  description="Find articles, runbooks, and past tickets"
+/>
+
+// Interactive card (renders as <button>)
+<MingoOnboardingCard
+  icon={<RoadmapIcon />}
+  title="View Roadmap"
+  slashCommand="/roadmap"
+  onClick={() => router.push('/roadmap')}
+/>
+
+// Card with action chips (renders as <div>)
+const actions: MingoOnboardingCardAction[] = [
+  { id: 'recent', label: 'Recent', onClick: () => fetchRecent() },
+  { id: 'search', label: 'Search', onClick: (e) => { e.stopPropagation(); openSearch() } },
+]
+
+<MingoOnboardingCard
+  icon={<TicketIcon />}
+  title="Tickets"
+  slashCommand="/tickets"
+  description="Browse and manage open tickets"
+  actions={actions}
+/>
+```
+
+> **Note:** Stack multiple cards inside a `rounded-md` container — the `last:border-b-0` rule automatically removes the bottom divider from the final card, keeping the visual frame clean.

package/src/components/chat/.model-display.md

@@ -1,44 +1,46 @@
-<!-- source-hash: 5dd385e2320af3422b1780f758c64406 -->
-A React component that displays AI model information with provider-specific icons and names in a consistent format.
+<!-- source-hash: 75472e90962007832fb7ea753283d69c -->
+Renders an inline pill showing the AI provider icon, model name, and token usage against the context window. When per-call token breakdown data is available, a hover card expands to show input/output splits across the answer model and any auxiliary Haiku sub-agents (rewriter, classifier, summarizer), plus an optional prompt-cache hit rate.
 
 ## Key Components
 
-- **`ModelDisplay`** - Main React component that renders model name with provider icon
-- **`getProviderIcon`** - Helper function that maps provider names to their corresponding icons
-- **Provider Icons** - Supports Anthropic/Claude, OpenAI, and Google/Gemini providers
-- **Props Interface** - Uses `ModelDisplayProps` type for component configuration
+| Export / Function | Description |
+|---|---|
+| `ModelDisplay` | Primary `forwardRef` component rendering the inline token pill and optional hover card breakdown |
+| `BreakdownRow` | Internal helper rendering a single `label / X in / Y out` row in the hover card |
+| `getProviderIcon` | Maps provider string (`anthropic`, `openai`, `google`, etc.) to the corresponding grey logo icon |
+| `formatTokenCount` | Formats raw token integers to human-readable strings (`1.2K`, `200M`, etc.) |
+| `hasAnyBreakdownRow` | Guards hover card rendering — returns `true` only when at least one Haiku sub-agent row exists |
 
 ## Usage Example
 
 ```typescript
 import { ModelDisplay } from './model-display';
 
-// Basic usage with provider and model name
-<ModelDisplay 
-  provider="anthropic" 
-  modelName="claude-3-sonnet"
+// Minimal — inline pill only (no hover card)
+<ModelDisplay
+  provider="anthropic"
+  modelName="claude-opus-4-5"
+  displayName="Claude Opus"
+  usedTokens={12_400}
+  contextWindow={200_000}
 />
 
-// With custom display name
-<ModelDisplay 
-  provider="openai" 
-  modelName="gpt-4-turbo"
-  displayName="GPT-4 Turbo"
+// With full breakdown — activates hover card on mouse-over
+<ModelDisplay
+  provider="anthropic"
+  modelName="claude-opus-4-5"
+  displayName="Claude Opus"
+  usedTokens={18_750}
+  contextWindow={200_000}
+  inputTokens={15_200}
+  outputTokens={3_550}
+  hitRatePct={34}
+  breakdown={{
+    haikuRewriter:   { input: 420,  output: 80  },
+    haikuClassifier: { input: 310,  output: 45  },
+    haikuSummarizer: { input: 1100, output: 200 },
+  }}
 />
-
-// With additional styling
-<ModelDisplay 
-  provider="google"
-  modelName="gemini-pro"
-  className="text-lg font-bold"
-/>
-
-// Supported provider strings
-const providers = [
-  'anthropic', 'claude',           // Claude icon
-  'openai',                        // OpenAI icon
-  'google', 'gemini', 'google-gemini', 'google_gemini'  // Gemini icon
-];
 ```
 
-The component automatically selects the appropriate icon based on the provider string and displays either the `displayName` or falls back to `modelName`. It uses Tailwind classes for styling and supports all standard div props through forwarded refs.
+> **Note:** The `usedTokens` / `contextWindow` tail renders as soon as `contextWindow` is available, intentionally showing `—/200K tokens used` before the first usage frame arrives so users can see model capacity without waiting for streaming to begin.