@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/chat/utils/.history-merge.md

@@ -0,0 +1,65 @@
+<!-- source-hash: 5df51000b55f2d031915f5b4412ac8e6 -->
+Reconciles persisted dialog history (processed GraphQL pages) with realtime messages accumulated from streaming chunks, preventing both duplicate and lost turns across MSP chat interfaces (Mingo, tickets, openframe-chat).
+
+## Key Components
+
+### Interfaces & Types
+
+- **`MergeableChatMessage`** — Minimal structural contract for mergeable messages; hosts pass their own type and get it back. Includes optional `streamSeq` for per-message coverage resolution.
+- **`HistoryMergeInput<M>`** — Input shape for `mergeHistoryWithRealtime`, encapsulating processed history, existing realtime messages, seq signals, and fetch timestamps.
+
+### Constants
+
+- **`SYNTHETIC_REALTIME_ID_PREFIXES`** — Cross-host contract listing all client-minted ID prefixes (`assistant-`, `user-`, `direct-`, `system-`, `error-`). Centralised here to prevent double-rendering of persisted/synthetic message pairs.
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `mergeHistoryWithRealtime<M>` | Core merge logic. Applies seq-based coverage, per-role max seq, approval batch reconciliation, and wall-clock fallback to produce a single deduplicated message list. |
+| `flattenMessagePagesChronological<T>` | Flattens DESC-sorted GraphQL pages into a single chronological array. |
+| `maxPersistedStreamSeq` | Computes the highest `lastChunkStreamSeq` across all history pages; used as the `historyMaxStreamSeq` input and JetStream replay offset. |
+| `assistantAnswerText` | Extracts rendered text from an assistant message for content-based deduplication fallback. |
+
+## Usage Example
+
+```typescript
+import {
+  mergeHistoryWithRealtime,
+  flattenMessagePagesChronological,
+  maxPersistedStreamSeq,
+} from '@openframe-oss-lib/history-merge'
+
+const processedHistory = flattenMessagePagesChronological(queryData?.pages)
+const historyMaxStreamSeq = maxPersistedStreamSeq(queryData?.pages)
+
+const merged = mergeHistoryWithRealtime({
+  processedHistory,
+  existingMessages: store.messages,
+  streamingMessageId: activeStreamId ?? null,
+  historyFetchedAt: dataUpdatedAt,
+  historyMaxStreamSeq,
+  realtimeSeenStreamSeq: store.lastSeenSeq,
+})
+
+store.setMessages(merged)
+```
+
+## Coverage Resolution Priority
+
+```mermaid
+graph TD
+    A[Synthetic message] --> B{"Per-row streamSeq\navailable?"}
+    B -->|Yes| C{"Same-role history\nmax seq >= synthetic seq?"}
+    B -->|No| D{"Global seq\ncoverage known?"}
+    C -->|Yes| E[Drop synthetic]
+    C -->|No| F[Keep synthetic]
+    D -->|Yes| G{"historyMaxStreamSeq\n>= realtimeSeenSeq?"}
+    D -->|No| H{"Created after\nhistoryFetchedAt?"}
+    G -->|Yes| E
+    G -->|No| F
+    H -->|Yes| F
+    H -->|No| E
+```
+
+> **Source:** [`history-merge.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/history-merge.ts)

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

@@ -1,46 +1,48 @@
-<!-- source-hash: d7e38b48af56d6db68e8de321044b39c -->
-Single source of truth for resolving icon name strings (kebab-case or PascalCase) to React components, with sized rendering helpers.
+<!-- source-hash: 179ff4aa1bbfe40397134cf9b75647a6 -->
+Resolves backend `SlashCommandSummary.iconName` strings to React icon components for the OpenFrame chat UI, supporting brand logos, semantic aliases, and the full `icons-v2-generated` library with a single unified entry point.
 
 ## Key Components
 
-### Exports
+### `resolveIcon(iconName, opts?)`
+The primary export — maps any backend `iconName` to an `IconComponent`. Supports two variants:
+- `'design'` (default): Checks `ICON_ALIASES` first, then falls back to `resolveFromLibrary`, then `FileIcon`.
+- `'brand'`: Delegates to `getIconComponent` from the icon registry (brand-colored social glyphs).
 
-| 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) |
+### `ICON_ALIASES`
+Static registry mapping backend keys and Figma-canonical aliases to specific components. Covers production `/api/docs/commands` contract keys (`clickup`, `slack`, `hubspot`, `github`, `openframe`), legacy announcement-bar names (`megaphone`, `flamingo`, `bell`), and common generic v2 glyphs.
 
-### Key Conventions
+### `resolveFromLibrary(iconName)`
+Generic fallback that resolves any kebab-case name against the full `icons-v2-generated` namespace by convention (`chart-pie` → `ChartPieIcon`). Tries two PascalCase candidates to handle the inconsistent `ai`/`AI` token in generator output.
 
-- **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`
+### `ICON_OPTIONS`
+Curated `ReadonlyArray<IconOption>` for the admin slash-command icon picker (`/admin/chat-config`). Each entry has a `key` (kebab-case DB value) and a `label` (human-readable dropdown text).
+
+### `sizedLogo(Logo)`
+HOC that wraps brand logos (which lack a `size` prop) to satisfy the `IconComponent` contract by driving dimensions via inline `style`.
+
+### `IconComponent` / `IconOption`
+Exported TypeScript types for the shared `{ size, className, color }` icon contract and picker entries.
 
 ## Usage Example
 
 ```typescript
-import { getIconComponent, getDynamicIcon, normalizeIconKey } from './icon-registry'
+import { resolveIcon } from './icon-library'
+
+// Design variant (default) — resolves to SlackLogoGreyIcon
+const SlackIcon = resolveIcon('slack')
 
-// 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)
+// Alias resolution — resolves to Rocket02Icon
+const RocketIcon = resolveIcon('rocket-02')
 
-// 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')
+// Generic library resolution — no alias needed
+const ChartIcon = resolveIcon('chart-pie')
 
-// Normalize a PascalCase key manually
-normalizeIconKey('GitHubIcon')   // → 'github'
-normalizeIconKey('globe')        // → 'globe' (pass-through)
-```
+// Null/unknown input — falls back to FileIcon
+const FallbackIcon = resolveIcon(null)
 
-### Adding a New Icon
+// Brand variant — delegates to getIconComponent
+const BrandSlack = resolveIcon('slack', { variant: 'brand' })
 
-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`
+// Render in JSX
+<SlackIcon size={24} className="text-ods-text-secondary" />
+```

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

@@ -0,0 +1,44 @@
+<!-- source-hash: 7ecf3f317fa8164ab2bb260642085dcc -->
+Centralized icon registry mapping string icon names to React components, serving as the single source of truth for icon lookups across the OpenFrame lib and hub.
+
+## Key Components
+
+### `ICON_REGISTRY`
+A kebab-case keyed record mapping icon names to `IconComponent` types. Covers Lucide React icons, brand icons (Slack, GitHub, HubSpot, LinkedIn, etc.), and the OpenFrame logo. For social platform icons where both a brand and Lucide variant exist, the kebab key resolves to the brand component while a `-lucide` suffix key accesses the outline variant (e.g., `'github'` → `GitHubIcon`, `'github-lucide'` → `Github`).
+
+### `normalizeIconKey(key: string): string`
+Converts PascalCase icon identifiers (from `social_platforms.icon_name` DB column) to their canonical kebab-case registry keys using `PASCAL_TO_KEBAB_ALIASES`. Kebab-case keys pass through unchanged.
+
+### `getIconComponent(iconName)`
+Resolves an icon name to its React component. Handles `null`/`undefined` gracefully, falling back to `FileText` so UI chips always render with a glyph.
+
+### `getDynamicIcon(iconName, size, className)`
+Renders an icon as a `ReactNode` with a size preset (`xs`/`sm`/`md`/`lg`/`xl`) and optional className. Applies per-icon color overrides (e.g., LinkedIn blue, YouTube red) and falls back to `Globe` for unknown names.
+
+### `OpenFrameLogoIcon`
+A local wrapper around `RawOpenFrameLogo` that wires the logo's outer frame color to `currentColor`, making it visible on dark surfaces alongside Lucide icons.
+
+## Usage Example
+
+```typescript
+import { getIconComponent, getDynamicIcon, normalizeIconKey } from './icon-registry'
+
+// Resolve a component for custom rendering
+const Icon = getIconComponent('hubspot')
+// <Icon className="w-5 h-5 text-orange-500" />
+
+// Handle PascalCase keys from social_platforms.icon_name
+const Icon2 = getIconComponent('LinkedInIcon') // resolves to LinkedInIcon component
+
+// Render a sized icon node directly
+const node = getDynamicIcon('rocket', 'lg')           // 32px Rocket
+const node2 = getDynamicIcon('youtube', 'sm')          // 16px YouTubeIcon, color: #FF0000
+
+// Normalize a key manually
+normalizeIconKey('GitHubIcon')  // → 'github'
+normalizeIconKey('github')      // → 'github' (pass-through)
+```
+
+**Adding a new icon:** Import the component, add a `'kebab-key': Component` entry to `ICON_REGISTRY`, and add a `PascalName → 'kebab-key'` row to `PASCAL_TO_KEBAB_ALIASES` if the icon arrives from a PascalCase DB column.
+
+**Source:** [`icon-registry.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/icon-registry.ts)

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

@@ -1,20 +1,21 @@
-<!-- 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.
+<!-- source-hash: 0435e7889d0ba1d3a5186507e28737c9 -->
+Barrel export module for the message processing utilities library, re-exporting all public APIs from specialized sub-modules covering chat message parsing, navigation, attachments, icons, and more.
 
 ## Key Components
 
-| 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` |
+| Export Group | Source Module | Description |
+|---|---|---|
+| Chunk parsing | `chunk-parser` | Parse streaming chunks into actions, detect control/error/metadata chunks |
+| Segment accumulator | `message-segment-accumulator` | Accumulate streaming message segments with callbacks |
+| Historical messages | `process-historical-messages` | Process and reconcile chat history with error extraction |
+| History merge | `history-merge` | Reconcile persisted history with realtime stream data |
+| Navigation | `execute-navigation`, `nav-click-handler`, `decide-new-tab` | Unified navigation primitive for new-tab/same-tab, internal/external, embed/host routing |
+| Chat attachment | `chat-attachment-markdown` | Format and strip attachment markdown, URL/token helpers |
+| Icon registry | `icon-registry`, `icon-library`, `source-icons` | Single source of truth for icon-name → component lookups |
+| Proxy auth | `chat-proxy-auth-storage`, `chat-authed-fetch` | localStorage adapter and authenticated fetch wrapper |
+| Slash commands | `slash-dispatch-utils` | Command parsing, entity filtering, and dispatch utilities |
+| Compact card | `compact-card-classes` | Shared CSS class constants and safe-href guard |
+| Scripted stream | `scripted-stream` | Re-exported wholesale via `export *` |
 
 ## Usage Example
 
@@ -22,32 +23,35 @@ Barrel export module that consolidates and re-exports all message processing, ch
 import {
   parseChunkToAction,
   createMessageSegmentAccumulator,
-  handleChatNavClick,
-  getChatProxyAuth,
-  getIconComponent,
-  formatChatAttachmentMarkdownForBubble,
-  decideNewTab,
+  executeNavigation,
+  resolveIcon,
   getStatusColorScheme,
-} from '@flamingo/chat-utils'
+  mergeHistoryWithRealtime,
+  formatChatAttachmentMarkdownForBubble,
+} from '@openframe/chat-utils'
 
-// Parse a streaming chunk from the AI response
+// Parse a streaming chunk
 const action = parseChunkToAction(rawChunk)
 
-// Accumulate streamed message segments
+// Accumulate message segments from a stream
 const accumulator = createMessageSegmentAccumulator({
-  onSegmentComplete: (segment) => console.log('Segment:', segment),
+  onSegmentComplete: (segment) => console.log('Segment done:', segment),
 })
 
-// Resolve navigation target for a chat link
-const { openInNewTab } = decideNewTab({
-  href: 'https://app.example.com/tickets/123',
-  surface: 'chat-bubble',
-  mode: 'web',
+// Execute navigation respecting new-tab rules
+executeNavigation({
+  href: '/tickets/123',
+  event: clickEvent,
+  surface: 'chat',
 })
 
-// Look up a registered icon by kebab-case key
-const Icon = getIconComponent('clickup')
+// Resolve an icon by name
+const Icon = resolveIcon('clickup')
+
+// Get agent status color scheme
+const colors = getStatusColorScheme('online')
+```
+
+## Source
 
-// Apply agent status color scheme to UI
-const colors = getStatusColorScheme('running')
-```
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

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

@@ -1,35 +1,39 @@
-<!-- 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.
+<!-- source-hash: 44dae2d6eddc55109e9284520b771589 -->
+Determines whether a URL string refers to a cross-origin resource, using purely static string analysis without any `window` or runtime context. Designed to be SSR-deterministic, avoiding React hydration mismatches caused by server/client value divergence.
 
 ## 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
+**`isCrossOriginUrl(url)`**
+Returns `true` if the URL would resolve to a different origin; `false` for relative paths, fragments, query-only strings, and nullish 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)
-```
+| Input pattern | Result | Reason |
+|---|---|---|
+| `null` / `undefined` / `""` | `false` | No URL |
+| `#anchor`, `?tab=x` | `false` | Same-document reference |
+| `/path/to/page` | `false` | Relative path, same origin |
+| `//cdn.example.com/...` | `true` | Protocol-relative, explicit host |
+| `https://flamingo.run/...` | `true` | Absolute URL, explicit host |
+| `http://external.com/...` | `true` | Absolute URL, 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
+// Navigation link — open externally if cross-origin
+const href = buildContentURL(item)
+const openInNewTab = isCrossOriginUrl(href)
+
+// <a href={href} target={openInNewTab ? '_blank' : undefined} />
+
+isCrossOriginUrl('/support')             // false — same-origin relative path
+isCrossOriginUrl('https://flamingo.run') // true  — external absolute URL
+isCrossOriginUrl('#section')             // false — fragment, same page
+isCrossOriginUrl(null)                   // false — safe nullish handling
 ```
 
-## Design Notes
+## 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
+- Intentionally avoids `window.location` comparisons to stay SSR-safe
+- Same-platform absolute URLs (e.g. from `buildContentURL`) are expected to be handled upstream via `targetPlatform` checks before this function is reached
+- Source: [`packages/utils/is-cross-origin-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/packages/utils/is-cross-origin-url.ts)

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

@@ -1,41 +1,62 @@
-<!-- source-hash: 17a77a7a52f5be3583fd5569ca4bb36f -->
-Manages the accumulation and lifecycle of message segments during real-time AI chat streaming, handling text, tool executions, and approval workflows.
+<!-- source-hash: dab060497e2fa3825072e74aa1f72abf -->
+Manages the accumulation and lifecycle of streaming message segments in a chat interface, handling text, tool executions, and approval workflows during real-time or historical message processing.
 
 ## Key Components
 
-- **`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
+### `MessageSegmentAccumulator` (class)
+Core class managing segment state across the message lifecycle.
+
+| Method | Description |
+|---|---|
+| `appendText(text)` | Appends to the last text segment or creates a new one |
+| `appendThinking(text)` | Same coalescing logic for `thinking`-type segments |
+| `addToolExecution(segment)` | Routes `EXECUTING_TOOL` / `EXECUTED_TOOL` events; patches batch approvals or standalone segments |
+| `addApprovalRequest(...)` | Pushes a single `approval_request` segment with callbacks |
+| `addApprovalBatch(...)` | Upserts an `approval_batch` segment by `approvalRequestId` |
+| `initializeWithState(state)` | Restores segments, pending approvals, and executing tool maps (e.g. after page refresh) |
+| `getState()` | Returns serializable `AccumulatorState` snapshot |
+| `reset()` / `resetSegments()` | Clears all state or only segments |
+
+### `AccumulatorCallbacks` (interface)
+Optional `onApprove` / `onReject` async callbacks injected into approval segments.
+
+### Private helpers
+- `applyExecutionToBatch` — merges tool execution results into an existing `approval_batch` segment
+- `resolvePendingApprovalForExecution` — implicitly marks the latest pending `approval_request` as approved when a tool execution arrives (handles observer sessions that never receive `APPROVAL_RESULT`)
 
 ## Usage Example
 
 ```typescript
+import { MessageSegmentAccumulator } from './message-segment-accumulator'
+
 const accumulator = new MessageSegmentAccumulator({
-  onApprove: async (requestId) => await approveRequest(requestId),
-  onReject: async (requestId) => await rejectRequest(requestId),
+  onApprove: async (requestId) => { /* handle approval */ },
+  onReject: async (requestId) => { /* handle rejection */ },
 })
 
-// Restore state after reconnection
-accumulator.initializeWithState({
-  existingSegments: previousSegments,
-  pendingApprovals: savedApprovals,
-})
+// Streaming text chunks
+accumulator.appendText('Hello, ')
+accumulator.appendText('world!')
 
-// Stream incoming chunks
-accumulator.appendText('Checking your ')
-accumulator.appendText('ticket status...')
+// Tool execution lifecycle
+accumulator.addToolExecution({
+  type: 'tool_execution',
+  data: { type: 'EXECUTING_TOOL', toolFunction: 'runScript', integratedToolType: 'shell', toolExecutionRequestId: 'req-1' }
+})
 
-// Handle tool lifecycle
 accumulator.addToolExecution({
   type: 'tool_execution',
-  data: { type: 'EXECUTING_TOOL', toolFunction: 'getTicket', toolTitle: 'Get Ticket', ... },
+  data: { type: 'EXECUTED_TOOL', toolFunction: 'runScript', integratedToolType: 'shell', toolExecutionRequestId: 'req-1', result: 'ok', success: true }
 })
 
-// Retrieve rendered segments
-const segments = accumulator.getSegments()
-```
+// Serialize and restore across reconnects
+const state = accumulator.getState()
+const restored = new MessageSegmentAccumulator()
+restored.initializeWithState(state)
+
+console.log(restored.getSegments())
+```
+
+## Source
+
+[`message-segment-accumulator.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/message-segment-accumulator.ts)

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

@@ -1,44 +1,39 @@
-<!-- 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.
+<!-- source-hash: bdc2b1fb114772393dd4ed7a7eea4c6f -->
+Pure helpers for computing new-tab navigation decisions and assembling `<a>` element attribute objects for chat-rendered links.
 
 ## 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` |
+### `isSameOriginAbsoluteHref(href)` *(internal)*
+Checks whether a given `href` is an absolute `http(s)` URL on the current page's origin. SSR-safe — returns `false` when `window` is undefined.
+
+### `computeIsNewTab(runtime, href, targetPlatform)`
+**Single source of truth** for the new-tab decision across inline cards, source chips, and `NavLinkAnchorViaRuntime`. Implements two modes:
+- **`embed` mode** — opens new tab except for same-origin absolute hrefs (e.g. embedder in-app routes under `/help-center`).
+- **`host` mode** — delegates to `runtime.navigation.decideNewTab` or falls back to `libDecideNewTab`.
+
+### `newTabAnchorAttrs(isNewTab)`
+Returns `{ target: '_blank', rel: 'noopener noreferrer' }` when `isNewTab` is `true`, or `{}` otherwise. Ensures new-tab links always include `noopener noreferrer` to prevent tab-nabbing.
+
+### `buildAnchorProps(href, isNewTab)`
+Combines `href` and new-tab attributes into a single `anchorProps` object. Returns `undefined` (not a falsy object) when `href` is absent, enabling clean conditional rendering between `<a>` and `<span>`.
 
 ## 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>
-}
-```
+import { computeIsNewTab, buildAnchorProps } from './nav-anchor-props'
+
+// Inside a card wrapper component
+const isNewTab = computeIsNewTab(runtime, chatRef.url, targetPlatform)
+const anchorProps = buildAnchorProps(chatRef.url, isNewTab)
+
+// In JSX — renders <a> or <span> based on whether a URL exists
+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"]
+// Or spread newTabAnchorAttrs directly when href is already known
+import { newTabAnchorAttrs } from './nav-anchor-props'
+<a href={href} {...newTabAnchorAttrs(isNewTab)} />
 ```
 
-> **Important:** Do not inline the `embed` short-circuit or `decideNewTab` fallback chain elsewhere. `computeIsNewTab` is the **only** place this logic should live.
+**Source:** [`nav-anchor-props.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/nav-anchor-props.ts)

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

@@ -1,47 +1,43 @@
-<!-- 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.
+<!-- source-hash: dd19b1c249728537a01b0a89f3b94541 -->
+Thin compatibility wrapper that forwards chat-rendered navigation link clicks to the unified `executeNavigation` primitive.
 
 ## 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
+Interface describing the navigation target passed to the handler:
 
-### `NavClickEvent`
-Structural mouse-event interface (subset of `React.MouseEvent`) that keeps the handler callable from non-anchor surfaces without requiring a cast.
+| Field | Type | Description |
+|---|---|---|
+| `href` | `string` | Destination URL |
+| `path` | `string \| null` | Optional soft-nav path override |
+| `targetPlatform` | `string \| null` | Target rendering platform hint |
 
-### `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
+### `handleChatNavClick`
+Delegates directly to [`executeNavigation`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/execute-navigation.ts), preserving the call shape expected by existing chat callers (chip blocks, `<ChatCardNavWrap>`, `<NavLinkAnchorViaRuntime>`). Returns a `boolean` indicating whether the click was handled.
 
-**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`
+> **Deprecated.** New code should call `executeNavigation` directly. The full decision tree (empty-href no-op, modifier/non-primary passthrough, new-tab, same-tab soft-nav with fallback) lives exclusively in `execute-navigation.ts`.
 
 ## 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>
-  )
-}
+import { useRouter } from 'next/navigation'
+
+const router = useRouter()
+
+<a
+  href={href}
+  onClick={(e) =>
+    handleChatNavClick(
+      e,
+      runtime,
+      { href, path: '/dashboard', targetPlatform: 'web' },
+      router.push, // fallback for runtimes without navigation.navigate
+    )
+  }
+>
+  Dashboard
+</a>
 ```
 
-> **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.
+The `fallbackNavigate` parameter accepts `useRouter().push` for same-origin soft-navigation when the `ChatRuntime` does not wire a `navigation.navigate` handler.