@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/chat/utils/.clickup-task-type-utils.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 84402bbfdf1a37e83bafc681331451ac -->
+Resolves ClickUp `custom_item_id` numeric values to human-readable label strings for use in chat-inline cards and activity feeds.
+
+## Key Components
+
+- **`CUSTOM_ITEM_ID`** — Const enum-style object mapping 14 ClickUp standard task type names to their numeric IDs (`1000`–`1014`).
+- **`getTaskTypeLabel(customItemId)`** — Returns a display string for a given `custom_item_id`, or `null` for unknown IDs so callers can fall back to a generic label.
+
+## Usage Example
+
+```typescript
+import { getTaskTypeLabel, CUSTOM_ITEM_ID } from './clickup-task-type-utils'
+
+// Resolve a raw ID from a ClickUp task payload
+const label = getTaskTypeLabel(task.custom_item_id) ?? 'Task'
+console.log(label) // e.g. "Bug", "Epic", "Milestone"
+
+// Use the constant directly when constructing queries or comparisons
+if (task.custom_item_id === CUSTOM_ITEM_ID.EPIC) {
+  // handle epic-specific logic
+}
+
+// null and undefined both resolve gracefully
+getTaskTypeLabel(null)      // → null (fall back to "Task")
+getTaskTypeLabel(undefined) // → null
+getTaskTypeLabel(9999)      // → null (unknown ID)
+```
+
+## ID Reference
+
+| Constant | ID | Label |
+|---|---|---|
+| `TASK` | 1000 | Task |
+| `MILESTONE` | 1001 | Milestone |
+| `RECURRING` | 1002 | Recurring |
+| `SUBTASK` | 1003 | Subtask |
+| `FORM` | 1004 | Form |
+| `PLAN` | 1006 | Plan |
+| `STRATEGY` | 1007 | Strategy |
+| `BUG` | 1008 | Bug |
+| `REQUEST` | 1009 | Request |
+| `FEATURE` | 1010 | Feature |
+| `STORY` | 1011 | Story |
+| `EPIC` | 1012 | Epic |
+| `COMPONENT` | 1013 | Component |
+| `INITIATIVE` | 1014 | Initiative |
+
+> `null` input and unrecognized IDs both return `null` — callers should default to `"Task"` as the fallback affordance.

package/src/components/chat/utils/.compact-card-classes.md

@@ -0,0 +1,62 @@
+<!-- source-hash: 727163d193b2d1e3e47ea92637add9ea -->
+Single source of truth for compact card Tailwind class constants and URL safety utilities used across chat-inline `size='sm'` card frames in the OpenFrame chat shell.
+
+## Key Components
+
+### Class Constants
+
+| Export | Purpose |
+|--------|---------|
+| `COMPACT_CARD_OUTER` | Interactive anchor wrap with hover/transition styles |
+| `COMPACT_CARD_OUTER_STATIC` | Non-interactive span wrap (no hover, `cursor-default`) |
+| `COMPACT_CARD_SKELETON_OUTER` | Animated pulse skeleton frame |
+| `COMPACT_CARD_IMAGE_SLOT` | 56×56 cover image container |
+| `COMPACT_CARD_ICON_SLOT` | 56×56 fallback icon container |
+| `COMPACT_CARD_SKELETON_IMAGE_SLOT` | 56×56 skeleton image placeholder |
+| `COMPACT_CARD_TEXT_COL` | Flex column wrapper for text content |
+| `COMPACT_CARD_TITLE_ROW` | Fixed 20px height title row |
+| `COMPACT_CARD_META_ROW_BOX` | Fixed 16px height subtitle row |
+| `COMPACT_CARD_TITLE` | Bold 14px/20px primary text |
+| `COMPACT_CARD_SUBTITLE` | 11px/16px secondary text |
+| `COMPACT_CARD_SUMMARY` | 11px/16px secondary text at 80% opacity |
+| `COMPACT_CARD_META_ROW` | Multi-part 11px metadata row |
+| `COMPACT_CARD_ROW_FILLER` | Non-breaking space to preserve row height |
+
+### Functions
+
+**`safeHref(url)`** — Validates a URL before use in an `<a href>`. Allows `http:`, `https:`, `mailto:`, and same-origin paths (`/path`). Strips control/zero-width characters. Returns the original string or `null`.
+
+## Usage Example
+
+```typescript
+import {
+  COMPACT_CARD_OUTER,
+  COMPACT_CARD_OUTER_STATIC,
+  COMPACT_CARD_IMAGE_SLOT,
+  COMPACT_CARD_TITLE,
+  COMPACT_CARD_SUBTITLE,
+  safeHref,
+} from './compact-card-classes'
+
+const href = safeHref(card.url)
+
+// Interactive card (valid href)
+if (href) {
+  return (
+    <a href={href} className={COMPACT_CARD_OUTER}>
+      <div className={COMPACT_CARD_IMAGE_SLOT}>...</div>
+      <span className={COMPACT_CARD_TITLE}>{card.title}</span>
+      <span className={COMPACT_CARD_SUBTITLE}>{card.subtitle}</span>
+    </a>
+  )
+}
+
+// Non-interactive fallback
+return (
+  <span className={COMPACT_CARD_OUTER_STATIC}>
+    ...
+  </span>
+)
+```
+
+> Card-specific variations (play overlays, status badges, pill counters) are added inside each card component. The outer frame constants remain uniform across all compact card types.

package/src/components/chat/utils/.decide-new-tab.md

@@ -0,0 +1,51 @@
+<!-- source-hash: f8a0a33feba94cc42bfec8295a8e57f2 -->
+Determines whether a navigation action should open in a new browser tab, using a prioritized rule chain to handle embed mode, explicit overrides, platform comparisons, and cross-origin fallbacks.
+
+## Key Components
+
+### Types
+- **`NavSurface`** — Labels the calling surface (`'useNavLink'` | `'useUnifiedNav'`) for trace logging
+- **`RuntimeMode`** — Chat runtime context (`'host'` | `'embed'`)
+- **`DecideNewTabInput`** — Input shape for the decision function
+
+### Function
+- **`decideNewTab(input: DecideNewTabInput): boolean`** — Returns `true` if navigation should open a new tab
+
+## Branch Priority
+
+| Priority | Condition | Result |
+|----------|-----------|--------|
+| 1 | `runtimeMode === 'embed'` | Always new tab |
+| 2 | `openIn === 'new-tab'` | New tab |
+| 3 | `alwaysNewTab === true` | New tab |
+| 4 | `openIn === 'same-tab'` | Same tab |
+| 5 | `targetPlatform` defined + `currentSource` non-empty | New tab if platforms differ |
+| 6 | Fallback: `isCrossOriginUrl(href)` | New tab if cross-origin |
+
+## Usage Example
+
+```typescript
+import { decideNewTab } from './decide-new-tab'
+
+// Embed mode — always opens new tab regardless of other options
+decideNewTab({
+  href: '/dashboard',
+  currentSource: 'flamingo',
+  runtimeMode: 'embed',
+}) // → true
+
+// Platform comparison — cross-app link
+decideNewTab({
+  href: '/tickets',
+  targetPlatform: 'openframe',
+  currentSource: 'flamingo',
+}) // → true (different platforms)
+
+// Explicit override
+decideNewTab({
+  href: '/settings',
+  openIn: 'same-tab',
+  currentSource: 'flamingo',
+  runtimeMode: 'host',
+}) // → false
+```

package/src/components/chat/utils/.external-app-urls.md

@@ -0,0 +1,29 @@
+<!-- source-hash: 20391ac02d557100140a6d8d11a61656 -->
+Builds and exports URL helpers for third-party app deep-links used across chat surfaces (chip clicks, inline-card tracking rows).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `clickupTaskUrl` | `function` | Generates a ClickUp task detail URL from an external task ID |
+
+## Usage Example
+
+```typescript
+import { clickupTaskUrl } from './external-app-urls'
+
+// Valid external ID → returns full URL
+clickupTaskUrl('abc123')
+// → "https://app.clickup.com/t/abc123"
+
+// Missing or nullish ID → returns null (prevents broken `.../t/undefined` links)
+clickupTaskUrl(null)       // → null
+clickupTaskUrl(undefined)  // → null
+clickupTaskUrl('')         // → null
+```
+
+## Notes
+
+- This is the **lib-side subset** of the hub's `external-app-urls.ts` — only helpers consumed by shared/chat surfaces live here.
+- HubSpot and admin route builders remain hub-side as they are only used by hub-internal mappers.
+- Null-safe by design: always check the return value before rendering a link.

package/src/components/chat/utils/.extract-incomplete-message-state.md

@@ -1,48 +1,44 @@
-<!-- source-hash: 9bcf6f0eae9543385fec745e5f5512eb -->
-A utility for extracting incomplete message state from historical assistant messages, enabling seamless continuation of message building across realtime connections when messages contain pending operations or tool executions.
+<!-- source-hash: 05b4580f6cd1fa50abcf196198e4487a -->
+Extracts incomplete message state from the last historical assistant message to enable resumption of in-progress AI responses across realtime connection restarts.
 
 ## Key Components
 
-- **`extractIncompleteMessageState`** - Main function that analyzes the last processed message to extract incomplete state including pending approvals, executing tools, and existing message segments
+### `extractIncompleteMessageState(lastMessage)`
+
+**Parameters:** `lastMessage: ProcessedMessage | undefined`
+
+**Returns:** `{ existingSegments?, pendingApprovals?, executingTools? } | undefined`
+
+Returns `undefined` if the message is complete or not an assistant message with structured segments. Otherwise returns state needed to reinitialize the realtime chunk processor.
+
+**Incomplete state detection by segment type:**
+
+| Segment Type | Condition Flagged Incomplete |
+|---|---|
+| `tool_execution` | Status is `EXECUTING_TOOL` |
+| `approval_request` | Status is `pending` with a `requestId` |
+| `approval_batch` | Not `rejected` AND not all tool calls have `done` executions |
+| `context_compaction` | Status is `started` |
 
 ## Usage Example
 
 ```typescript
 import { extractIncompleteMessageState } from './extract-incomplete-message-state'
-import type { ProcessedMessage } from '../types'
-
-// Extract state from the last assistant message
-const lastMessage: ProcessedMessage = {
-  role: 'assistant',
-  content: [
-    { type: 'text', content: 'Starting deployment...' },
-    { 
-      type: 'tool_execution', 
-      data: { 
-        type: 'EXECUTING_TOOL',
-        integratedToolType: 'kubernetes',
-        toolFunction: 'deployApp',
-        parameters: { namespace: 'prod' }
-      }
-    }
-  ]
-}
 
+const lastMessage = conversationHistory.at(-1)
 const incompleteState = extractIncompleteMessageState(lastMessage)
 
 if (incompleteState) {
-  console.log('Found incomplete message with:')
-  console.log('- Existing segments:', incompleteState.existingSegments?.length)
-  console.log('- Executing tools:', incompleteState.executingTools?.size)
-  console.log('- Pending approvals:', incompleteState.pendingApprovals?.size)
-  
-  // Initialize realtime processor with existing state
   realtimeProcessor.initialize({
     existingSegments: incompleteState.existingSegments,
     pendingApprovals: incompleteState.pendingApprovals,
-    executingTools: incompleteState.executingTools
+    executingTools: incompleteState.executingTools,
   })
 }
 ```
 
-The function returns `undefined` for complete messages or non-assistant messages, and extracts tool executions and approval requests that are still in progress to maintain continuity across connection resets.
+## Notes
+
+- Only processes assistant messages with structured (`MessageSegment[]`) content — string content is ignored
+- `pendingApprovals` and `executingTools` maps are omitted from the return value when empty, reducing unnecessary initialization overhead
+- The `approval_batch` logic ensures post-approval `EXECUTED_TOOL` chunks can correctly merge into the batch segment via `applyExecutionToBatch`

package/src/components/chat/utils/.flatten-assistant-content.md

@@ -0,0 +1,34 @@
+<!-- source-hash: df5859607a7e41cd7507f9527aeed74b -->
+Coerces a chat message's `content` field — either a plain string or a `MessageSegment[]` array — into a flat string suitable for wire transport to the LLM.
+
+## Key Components
+
+- **`flattenAssistantContent(raw: unknown): string`** — Single exported function that normalizes assistant message content before serialization. Handles three cases:
+  - Plain strings are returned as-is
+  - Arrays are filtered to `text`-typed segments, joining their `.text` fields with `\n\n`
+  - Null, undefined, or unknown shapes return `''`
+
+## Why This Exists
+
+When `useChat` streams SSE responses, assistant messages are stored in React state as structured `MessageSegment[]` arrays (text, approval cards, tool executions, thinking blocks). A naive empty-string fallback for non-strings silently drops all context on subsequent turns — Anthropic receives `assistant: ""` and loses conversation history. This function preserves the LLM-visible text while intentionally skipping non-text segments (`approval_request`, `tool_execution`, `thinking`) to avoid bloating the request body.
+
+## Usage Example
+
+```typescript
+import { flattenAssistantContent } from './flatten-assistant-content'
+
+// Plain string — returned as-is
+flattenAssistantContent("Hello world") // → "Hello world"
+
+// Structured segment array — text segments joined
+flattenAssistantContent([
+  { type: 'thinking', content: '...' },          // skipped
+  { type: 'text', text: 'Here is my answer.' },  // included
+  { type: 'tool_execution', id: 'tu_1' },         // skipped
+  { type: 'text', text: 'And a follow-up.' },    // included
+])
+// → "Here is my answer.\n\nAnd a follow-up."
+
+// Null / unknown — safe fallback
+flattenAssistantContent(null) // → ""
+```

package/src/components/chat/utils/.icon-registry.md

@@ -0,0 +1,46 @@
+<!-- source-hash: d7e38b48af56d6db68e8de321044b39c -->
+Single source of truth for resolving icon name strings (kebab-case or PascalCase) to React components, with sized rendering helpers.
+
+## Key Components
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ICON_REGISTRY` | `Record<string, IconComponent>` | Kebab-case map of all registered icon names to React components |
+| `normalizeIconKey(key)` | `(string) => string` | Converts PascalCase icon names to canonical kebab-case; passes kebab keys through unchanged |
+| `getIconComponent(iconName)` | `(string\|null\|undefined) => ComponentType` | Resolves any icon name to a component; falls back to `FileText` |
+| `getDynamicIcon(iconName, size, className)` | `(...) => ReactNode` | Renders a sized icon element directly; falls back to `Globe` |
+| `DynamicIconSize` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | Size preset type (12px–48px) |
+
+### Key Conventions
+
+- **Registry keys** are always kebab-case (e.g. `'dollar-sign'`, `'book-open'`)
+- **Brand vs. Lucide variants** share the same base name: `'github'` → brand icon, `'github-lucide'` → Lucide outline
+- **PascalCase aliases** (`social_platforms.icon_name` column) are resolved via `PASCAL_TO_KEBAB_ALIASES` before lookup
+- **Unknown names** never crash render — `getIconComponent` falls back to `FileText`, `getDynamicIcon` falls back to `Globe`
+
+## Usage Example
+
+```typescript
+import { getIconComponent, getDynamicIcon, normalizeIconKey } from './icon-registry'
+
+// Resolve a component for use in JSX (kebab or PascalCase both work)
+const Icon = getIconComponent('rocket')          // → Rocket
+const Icon2 = getIconComponent('LinkedInIcon')   // → LinkedInIcon (via alias)
+const Icon3 = getIconComponent('unknown-icon')   // → FileText (fallback)
+
+// Render a sized icon node directly
+const node = getDynamicIcon('youtube', 'lg')         // 32px YouTubeIcon with brand color
+const node2 = getDynamicIcon('dollar-sign', 'sm', 'text-green-500')
+
+// Normalize a PascalCase key manually
+normalizeIconKey('GitHubIcon')   // → 'github'
+normalizeIconKey('globe')        // → 'globe' (pass-through)
+```
+
+### Adding a New Icon
+
+1. Import the component at the top of the file
+2. Add a `'kebab-name': Component` entry to `ICON_REGISTRY`
+3. If the icon is stored as PascalCase in any DB column, add a `PascalName → 'kebab-name'` row to `PASCAL_TO_KEBAB_ALIASES`

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

@@ -1,48 +1,53 @@
-<!-- source-hash: 6172cd39304396b46814bbbfee6b9708 -->
-Centralized export module for chat message processing utilities, providing parsing, accumulation, and state management functionality for streaming message data.
+<!-- source-hash: 85c0af6cd361347beeabcd097260378a -->
+Barrel export module that consolidates and re-exports all message processing, chat navigation, UI styling, and content utility functions for chat interfaces.
 
 ## Key Components
 
-**Chunk Processing**
-- `parseChunkToAction` - Converts raw chunks into action objects
-- `isControlChunk`, `isErrorChunk`, `isMetadataChunk` - Type guard functions for chunk classification
-- `extractTextFromChunk` - Extracts text content from message chunks
-
-**Message Accumulation**
-- `MessageSegmentAccumulator` - Class for accumulating streaming message segments
-- `createMessageSegmentAccumulator` - Factory function for creating accumulators
-- `AccumulatorCallbacks` - Type definition for callback functions
-
-**Historical Processing**
-- `processHistoricalMessages` - Processes previously received messages
-- `extractErrorMessages` - Extracts error information from message history
-- `processHistoricalMessagesWithErrors` - Combined processing with error handling
-
-**State Management**
-- `extractIncompleteMessageState` - Retrieves state of partially received messages
+| Category | Exports |
+|----------|---------|
+| **Chunk Parsing** | `parseChunkToAction`, `isControlChunk`, `isErrorChunk`, `isMetadataChunk`, `extractTextFromChunk` |
+| **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
+| **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
+| **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
+| **Proxy Auth** | `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` |
+| **Attachments** | `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` |
+| **UI / Styling** | `chatChipClass`, compact card class constants (`COMPACT_CARD_*`), `getStatusColorScheme` |
+| **Icon Registry** | `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey`, `getDynamicIcon` |
+| **Source Utilities** | `getSourceIconName`, `getSourceLabel`, `resolveSourceRowCTA`, `resolveSourceIcon` |
+| **Slash Commands** | `parseWireCommandOverride`, `sanitizeTitleForChat`, `buildDiscussAddendum` |
 
 ## Usage Example
 
 ```typescript
 import {
-  MessageSegmentAccumulator,
   parseChunkToAction,
-  processHistoricalMessages,
-  extractIncompleteMessageState
-} from './message-utils'
-
-// Parse streaming chunk
+  createMessageSegmentAccumulator,
+  handleChatNavClick,
+  getChatProxyAuth,
+  getIconComponent,
+  formatChatAttachmentMarkdownForBubble,
+  decideNewTab,
+  getStatusColorScheme,
+} from '@flamingo/chat-utils'
+
+// Parse a streaming chunk from the AI response
 const action = parseChunkToAction(rawChunk)
 
-// Create message accumulator
-const accumulator = new MessageSegmentAccumulator({
+// Accumulate streamed message segments
+const accumulator = createMessageSegmentAccumulator({
   onSegmentComplete: (segment) => console.log('Segment:', segment),
-  onError: (error) => console.error('Error:', error)
 })
 
-// Process historical data
-const processed = processHistoricalMessages(messageHistory)
+// Resolve navigation target for a chat link
+const { openInNewTab } = decideNewTab({
+  href: 'https://app.example.com/tickets/123',
+  surface: 'chat-bubble',
+  mode: 'web',
+})
+
+// Look up a registered icon by kebab-case key
+const Icon = getIconComponent('clickup')
 
-// Extract incomplete state
-const state = extractIncompleteMessageState(partialMessages)
+// Apply agent status color scheme to UI
+const colors = getStatusColorScheme('running')
 ```

package/src/components/chat/utils/.is-cross-origin-url.md

@@ -0,0 +1,35 @@
+<!-- source-hash: 4303371bd78ed68ce85468361247ddc3 -->
+Determines whether a URL is cross-origin by checking for an explicit host, used to drive new-tab navigation decisions in chat and link rendering.
+
+## Key Components
+
+### `isCrossOriginUrl(url)`
+- **Input:** `string | null | undefined`
+- **Returns:** `boolean` — `true` if the URL has an explicit host (absolute or protocol-relative), `false` for relative paths or falsy values
+
+## Logic
+
+```text
+null / undefined / ""  → false
+/relative/path         → false  (same-origin by convention)
+//protocol-relative    → true   (explicit host)
+https://example.com    → true   (explicit host)
+http://example.com     → true   (explicit host)
+```
+
+## Usage Example
+
+```typescript
+import { isCrossOriginUrl } from './is-cross-origin-url'
+
+isCrossOriginUrl('/support')                  // false — same-origin
+isCrossOriginUrl('//cdn.example.com/file.js') // true  — cross-origin
+isCrossOriginUrl('https://flamingo.run')      // true  — cross-origin
+isCrossOriginUrl(null)                        // false — falsy guard
+```
+
+## Design Notes
+
+- **SSR-deterministic:** avoids `window.location` comparison, which previously caused React hydration mismatches when SSR (no `window`) and client produced different results for the same URL
+- **Convention-based:** same-origin navigation within the app always uses relative paths; any URL with a host is treated as external regardless of the actual deployment origin
+- **Scope:** only handles the fallback case in `decideNewTab`; absolute same-platform URLs are caught earlier by the `targetPlatform !== currentSource` branch and never reach this function

package/src/components/chat/utils/.message-segment-accumulator.md

@@ -1,50 +1,41 @@
-<!-- source-hash: cff141bf1c94cc3e98e3c44f584a3383 -->
-Manages accumulation and state tracking of message segments during real-time streaming or historical message processing in chat applications.
+<!-- source-hash: 17a77a7a52f5be3583fd5569ca4bb36f -->
+Manages the accumulation and lifecycle of message segments during real-time AI chat streaming, handling text, tool executions, and approval workflows.
 
 ## Key Components
 
-**MessageSegmentAccumulator Class:**
-- `appendText()` - Accumulates text content, merging with existing text segments
-- `addToolExecution()` - Manages tool execution states (EXECUTING_TOOL → EXECUTED_TOOL transitions)
-- `addApprovalRequest()` - Creates approval request segments for user confirmation
-- `processApprovalResult()` - Handles approval responses and updates segment status
-- `initializeWithState()` - Restores accumulator from saved state for session continuity
-- `getState()` / `reset()` - State management for serialization and cleanup
-
-**Helper Functions:**
-- `createMessageSegmentAccumulator()` - Factory function for creating accumulator instances
+- **`MessageSegmentAccumulator`** — Core class that tracks all segment types (`text`, `thinking`, `tool_execution`, `approval_request`, `approval_batch`) in a stateful array
+- **`AccumulatorCallbacks`** — Interface for wiring `onApprove`/`onReject` handlers into approval segments
+- **`initializeWithState()`** — Restores accumulator from serialized state across reconnections or page refreshes
+- **`appendText()` / `appendThinking()`** — Coalesces consecutive same-type segments instead of creating duplicates
+- **`addToolExecution()`** — Routes `EXECUTING_TOOL` → `EXECUTED_TOOL` state transitions, merging into approval batches when a `toolExecutionRequestId` matches
+- **`addApprovalBatch()`** — Upserts batch approval segments by `approvalRequestId` to prevent duplicates during replay
+- **`resolvePendingApprovalForExecution()`** — Implicitly marks the latest pending approval as approved when a tool execution arrives (handles observer streams with no `APPROVAL_RESULT` chunk)
+- **`getState()` / `reset()`** — Serialization and teardown helpers
 
 ## Usage Example
 
 ```typescript
-import { MessageSegmentAccumulator, AccumulatorCallbacks } from './message-segment-accumulator'
-
-// Create accumulator with approval callbacks
-const callbacks: AccumulatorCallbacks = {
-  onApprove: async (requestId) => console.log(`Approved: ${requestId}`),
-  onReject: async (requestId) => console.log(`Rejected: ${requestId}`)
-}
+const accumulator = new MessageSegmentAccumulator({
+  onApprove: async (requestId) => await approveRequest(requestId),
+  onReject: async (requestId) => await rejectRequest(requestId),
+})
 
-const accumulator = new MessageSegmentAccumulator(callbacks)
+// Restore state after reconnection
+accumulator.initializeWithState({
+  existingSegments: previousSegments,
+  pendingApprovals: savedApprovals,
+})
 
-// Accumulate streaming text
-accumulator.appendText('Hello ')
-accumulator.appendText('world!') // Merges into single text segment
+// Stream incoming chunks
+accumulator.appendText('Checking your ')
+accumulator.appendText('ticket status...')
 
-// Add tool execution
+// Handle tool lifecycle
 accumulator.addToolExecution({
   type: 'tool_execution',
-  data: {
-    type: 'EXECUTING_TOOL',
-    integratedToolType: 'filesystem',
-    toolFunction: 'readFile',
-    parameters: { path: '/home/user/file.txt' }
-  }
+  data: { type: 'EXECUTING_TOOL', toolFunction: 'getTicket', toolTitle: 'Get Ticket', ... },
 })
 
-// Process approval request
-accumulator.addApprovalRequest('req-123', 'rm -rf temp/', 'Delete temp files', 'SYSTEM')
-
-// Get final segments
+// Retrieve rendered segments
 const segments = accumulator.getSegments()
 ```

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

@@ -0,0 +1,44 @@
+<!-- source-hash: 24346a4b70daaa3c49e151b19cf6cf28 -->
+Provides pure helper functions for computing new-tab navigation decisions and building `<a>` anchor attribute objects used by chat-rendered links across inline cards, source chips, and runtime nav wrappers.
+
+## Key Components
+
+| Export | Signature | Purpose |
+|--------|-----------|---------|
+| `computeIsNewTab` | `(runtime, href, targetPlatform) → boolean` | Single source of truth for the new-tab rule; always returns `true` in `embed` mode, defers to `decideNewTab` callback or lib default in `host` mode |
+| `newTabAnchorAttrs` | `(isNewTab) → { target?, rel? }` | Returns `_blank` + `noopener noreferrer` pair or empty object; safe to spread directly into JSX `<a>` |
+| `buildAnchorProps` | `(href, isNewTab) → { href, target?, rel? } \| undefined` | Combines href + anchor attrs into a single `anchorProps` slot; returns `undefined` (not `{}`) when href is absent so card components can branch on `!= null` |
+
+## Usage Example
+
+```typescript
+import {
+  computeIsNewTab,
+  buildAnchorProps,
+} from './nav-anchor-props'
+
+// Inside a card dispatcher wrapper
+function CardLink({ runtime, chatRef, targetPlatform }) {
+  const isNewTab = computeIsNewTab(runtime, chatRef.url, targetPlatform)
+  const anchorProps = buildAnchorProps(chatRef.url, isNewTab)
+
+  return anchorProps != null
+    ? <a {...anchorProps}>{children}</a>
+    : <span>{children}</span>
+}
+```
+
+## Navigation Mode Rules
+
+```mermaid
+graph TD
+    A["computeIsNewTab called"] --> B{"href present?"}
+    B -- No --> C["return false"]
+    B -- Yes --> D{"embed mode?"}
+    D -- Yes --> E["return true (always new-tab)"]
+    D -- No --> F{"runtime.decideNewTab defined?"}
+    F -- Yes --> G["call runtime.decideNewTab"]
+    F -- No --> H["call libDecideNewTab fallback"]
+```
+
+> **Important:** Do not inline the `embed` short-circuit or `decideNewTab` fallback chain elsewhere. `computeIsNewTab` is the **only** place this logic should live.

package/src/components/chat/utils/.nav-click-handler.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 52e6bfa6e916758ef4a95f83d0eb97da -->
+Unified click-handler for chat-rendered navigation links. Centralizes the routing decision logic (same-tab vs. new-tab, embed vs. host, modifier-key pass-through) so callers like chip blocks, entity-card wrappers, and markdown anchor wrappers share a single implementation.
+
+## Key Components
+
+### `ChatNavClickInput`
+Input interface describing the navigation target:
+- `href` — destination URL (required)
+- `path` — optional internal route path
+- `targetPlatform` — optional platform hint for routing decisions
+
+### `NavClickEvent`
+Structural mouse-event interface (subset of `React.MouseEvent`) that keeps the handler callable from non-anchor surfaces without requiring a cast.
+
+### `handleChatNavClick(e, runtime, input): boolean`
+The core export. Processes a click event against a `ChatRuntime` and returns:
+- `true` — handler took action and called `preventDefault()`
+- `false` — modifier-click or non-primary button; browser default applies
+
+**Routing rules in priority order:**
+1. Empty `href` → `preventDefault` + no-op
+2. Non-primary button or any modifier key (`meta`, `ctrl`, `shift`, `alt`) → pass through to browser
+3. New-tab decision via `computeIsNewTab` → `runtime.navigation.openExternal` or `window.open`
+4. Same-tab → `runtime.navigation.navigate?.()` → fallback to `window.location.assign`
+
+## Usage Example
+
+```typescript
+import { handleChatNavClick } from './nav-click-handler'
+import { useChatRuntime } from '../../../contexts/chat-runtime-context'
+
+function NavChip({ href, path, targetPlatform }) {
+  const runtime = useChatRuntime()
+
+  return (
+    <button
+      onClick={(e) =>
+        handleChatNavClick(e, runtime, { href, path, targetPlatform })
+      }
+    >
+      {label}
+    </button>
+  )
+}
+```
+
+> **Note:** Pass-through (`return false`) preserves native `<a>` semantics for modifier-clicks (e.g., Cmd+Click opens a new tab), so wrapping anchor elements still behave correctly without extra logic in the caller.