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

package/src/components/chat/types/entities/.onboarding-guide.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 5421df27f5f23a658e7a9769d35c1b32 -->
+Brief description of the file's purpose in 1-2 sentences.
+
+Defines the shared TypeScript wire types for the onboarding guide feature, covering the full row shape returned by `/api/onboarding-guides` and the chat onboarding-guide card. These types are intentionally client-safe — DAL mutations stay hub-side.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `OnboardingGuide` | `interface` | Full row shape: identity, ordering, body content, video pipeline, images, SEO, workflow, and audit fields |
+| `OnboardingGuideFilters` | `interface` | Query parameters for list endpoints (`status`, `search`, `section`, `platform`, pagination, `ids`) |
+| `OnboardingGuideListResponse` | `interface` | Paginated list response wrapping `OnboardingGuide[]` with a total `count` |
+| `OnboardingGuideSectionSummary` | `interface` | Lightweight section rollup: name, ordering, and guide count |
+
+## Usage Example
+
+```typescript
+import type {
+  OnboardingGuide,
+  OnboardingGuideFilters,
+  OnboardingGuideListResponse,
+} from './onboarding-guide';
+
+// Fetch guides for a specific platform section
+async function fetchGuides(
+  filters: OnboardingGuideFilters
+): Promise<OnboardingGuideListResponse> {
+  const params = new URLSearchParams({
+    ...(filters.status && { status: filters.status }),
+    ...(filters.platform && { platform: filters.platform }),
+    ...(filters.section && { section: filters.section }),
+    limit: String(filters.limit ?? 20),
+    offset: String(filters.offset ?? 0),
+  });
+
+  const res = await fetch(`/api/onboarding-guides?${params}`);
+  return res.json() as Promise<OnboardingGuideListResponse>;
+}
+
+// Resolve video source (Mux/MP4 preferred, YouTube as fallback)
+function resolveVideoUrl(guide: OnboardingGuide): string | null {
+  return guide.main_video_url ?? guide.youtube_url ?? null;
+}
+```
+
+## Notes
+
+- **Video pipeline**: `main_video_url` (Mux/MP4) and `youtube_url` are independent columns — consumers should use whichever is populated, matching the `<VideoSourceSelector>` admin toggle.
+- **Multi-platform**: `onboarding_guide_platforms` is a junction array; a single guide can be featured across multiple platforms with independent `featured_order` values.
+- **Ordering**: Use `section_order` + `step_order` together for deterministic sort within a section.

package/src/components/chat/types/entities/.program-types.md

@@ -0,0 +1,57 @@
+<!-- source-hash: a31da27a1da7444bbcbd4a8716703941 -->
+Defines the Unified Program System's TypeScript type hierarchy, providing base interfaces, database row types, program-specific extensions, configuration objects, and pure transform utilities for events, podcasts, and webinars across a single set of generic components.
+
+## Key Components
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ProgramHost` | Interface | Host/speaker info (name, avatar, role, etc.) |
+| `LumaEventRow` / `PodcastEpisodeRow` / `WebinarRow` | Interfaces | Raw DB row shapes for each program source table |
+| `BaseProgramItem` | Interface | Shared contract all program items must satisfy |
+| `EventItem` / `PodcastItem` / `WebinarItem` | Interfaces | Extended shapes with program-specific fields |
+| `ProgramType` | Type | `'event' \| 'podcast' \| 'webinar'` discriminant |
+| `ProgramConfig<T>` | Interface | Configuration object that drives generic component behavior (labels, routing, icons, sort order) |
+| `ProgramLabels` | Interface | Display strings (singular, plural, archive, empty, etc.) |
+| `ProgramListResponse<T>` / `ProgramItemResponse<T>` | Interfaces | Generic API response wrappers |
+| `ProgramFilter` / `AdminProgramFilter` | Interfaces | Query/filter option shapes |
+| `transformEventToProgram` | Function | Maps `LumaEventRow` → `EventItem` |
+| `transformPodcastToProgram` | Function | Maps `PodcastEpisodeRow` → `PodcastItem` |
+| `transformWebinarToProgram` | Function | Maps `WebinarRow` → `WebinarItem` |
+
+## Usage Example
+
+```typescript
+import type {
+  ProgramConfig,
+  EventItem,
+  ProgramLabels,
+} from './program-types';
+import { transformEventToProgram } from './program-types';
+import { CalendarDays } from 'lucide-react';
+
+// Define a typed config for events
+const eventConfig: ProgramConfig<EventItem> = {
+  type: 'event',
+  table: 'luma_events',
+  apiEndpoint: '/api/events',
+  dateField: 'start_at',
+  detailRoute: '/events',
+  externalLinkLabel: 'View on Luma',
+  icon: <CalendarDays />,
+  sortOrder: 'asc',
+  labels: {
+    singular: 'Event',
+    plural: 'Events',
+    upcoming: 'Next Event',
+    upcomingSection: 'Upcoming Events',
+    archive: 'Past Events',
+    empty: 'No events yet',
+  },
+};
+
+// Transform a raw DB row into a typed EventItem
+const row = await db.from('luma_events').select('*').single();
+const eventItem: EventItem = transformEventToProgram(row);
+```
+
+> `BaseProgramItem` is the generic constraint used throughout — any new program type only needs to extend it and supply a matching `ProgramConfig` to plug into all shared components automatically.

package/src/components/chat/types/entities/.roadmap-item.md

@@ -0,0 +1,58 @@
+<!-- source-hash: ad455db496eef8ee2c54f68792ebfef2 -->
+Defines the canonical wire-shape interfaces for roadmap items consumed by the chat roadmap card and the public `/api/roadmap` endpoint.
+
+## Key Components
+
+### `RoadmapItem`
+Strongly-typed entity mirroring the `roadmap_items` projection produced by `transformTask()` in `clickup-sync-utils.ts`. Represents a single ClickUp task surfaced as a public roadmap entry.
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique identifier |
+| `status` / `statusColor` | `string` | Display status and its hex/named color |
+| `icon` | `string \| null` | Optional icon URL |
+| `figmaUrl` | `string \| null` | Linked Figma design |
+| `screenshots` | `string[]` | Attached screenshot URLs |
+| `targetVersion` | `string \| null` | Planned release version |
+| `upvotes` / `downvotes` | `number` | Community voting counts |
+| `quarter` | `string` | Planning quarter label |
+| `clickupUrl` | `string` | Canonical ClickUp task URL |
+| `customItemId` | `number \| null` | ClickUp task-type taxonomy ID (e.g. `1008`=Bug, `1009`=Request, `1010`=Feature) — drives type icons via `getTaskTypeIcon` |
+
+### `RoadmapStaleness`
+Tracks cache freshness for roadmap data synced from ClickUp.
+
+| Field | Type | Description |
+|---|---|---|
+| `lastSyncedAt` | `string \| null` | ISO timestamp of last successful sync |
+| `staleSinceMs` | `number` | Milliseconds elapsed since last sync |
+
+## Usage Example
+
+```typescript
+import type { RoadmapItem, RoadmapStaleness } from '@/components/chat/types/entities/roadmap-item';
+
+const item: RoadmapItem = {
+  id: 'task_abc123',
+  title: 'Dark mode support',
+  description: 'Add system-level dark mode across all views',
+  status: 'In Progress',
+  statusColor: '#f5a623',
+  icon: null,
+  figmaUrl: 'https://figma.com/file/...',
+  screenshots: [],
+  targetVersion: 'v2.4.0',
+  upvotes: 42,
+  downvotes: 3,
+  quarter: 'Q3 2025',
+  clickupUrl: 'https://app.clickup.com/t/abc123',
+  customItemId: 1010, // Feature
+};
+
+const staleness: RoadmapStaleness = {
+  lastSyncedAt: '2025-07-01T12:00:00Z',
+  staleSinceMs: 3600000, // 1 hour
+};
+```
+
+> **Import note:** Always import from `@/components/chat/types/entities/roadmap-item` for the strongly-typed shape. The legacy `RoadmapItem` stub in `product-release/release-detail-page.tsx` is untyped (`{ id: string; [key: string]: unknown }`) and will be reconciled in a follow-up.

package/src/components/chat/types/entities/.slack-message.md

@@ -0,0 +1,35 @@
+<!-- source-hash: 5dd665815decf79ecf870dd4eb652947 -->
+Defines the minimal wire shape for Slack message data as displayed in the chat RAG result card, representing a post-retrieval projection stripped of community-feature fields like reactions and threading.
+
+## Key Components
+
+### `SlackMessageItem` interface
+
+A lean projection of a `slack_messages` RAG table row containing only the fields required to render the `slack-message-card` UI component.
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Slack message ID (`ts` or URL-derived) |
+| `title` | `string` | Display title — typically `"author · channel"` |
+| `preview` | `string?` | PII-sanitized message body preview |
+| `channel` | `string?` | Channel name parsed from URL or stored row |
+| `dateUpdated` | `string \| number \| null?` | ISO timestamp or millisecond epoch |
+| `url` | `string \| null?` | Full Slack permalink (`https://*.slack.com/archives/...`) |
+
+## Usage Example
+
+```typescript
+import { SlackMessageItem } from '@/types/slack-message';
+
+// Mapping a RAG table row to the card's wire shape
+const item: SlackMessageItem = {
+  id: '1712345678.000100',
+  title: 'jane.doe · #support',
+  preview: 'Has anyone seen the ticket for the VPN issue?',
+  channel: 'support',
+  dateUpdated: '2024-04-05T14:22:00.000Z',
+  url: 'https://acme.slack.com/archives/C01AB2CD3EF/p1712345678000100',
+};
+```
+
+> **Naming note:** This interface is intentionally distinct from the broader `SlackMessage` type in `src/types/slack.ts`, which covers the full Slack Community feature shape including reactions, threading, and user objects.

package/src/components/chat/utils/.agent-status-message.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 75abfd053b43306b990d3311c7dd4813 -->
+Resolves a status string to an abstract color scheme name for use in `StatusBadge` components across job, ClickUp task, and log-level status surfaces.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ColorScheme` | `type` | Union type: `'success' \| 'error' \| 'warning' \| 'cyan' \| 'default'` |
+| `getStatusColorScheme` | `function` | Maps a status string to a `ColorScheme` value |
+
+### Resolution Strategy
+
+`getStatusColorScheme` applies a two-pass lookup:
+
+1. **Exact match** — case-sensitive switch on common statuses
+2. **Partial match** — lowercase substring checks for ClickUp-style freeform statuses (e.g. `"In Progress"`, `"Complete"`)
+
+| ColorScheme | Matched statuses |
+|-------------|-----------------|
+| `success` | `completed`, `success`, `active`, `*complete*`, `*done*` |
+| `error` | `failed`, `failure`, `cancelled`, `error`, `*blocked*`, `*failed*` |
+| `cyan` | `running`, `processing`, `closed`, `*review*` |
+| `warning` | `pending`, `warning`, `*working*`, `*progress*` |
+| `default` | `draft`, `info`, or any unmatched value |
+
+## Usage Example
+
+```typescript
+import { getStatusColorScheme } from './agent-status-message'
+
+// Exact match
+getStatusColorScheme('completed')   // → 'success'
+getStatusColorScheme('failed')      // → 'error'
+getStatusColorScheme('running')     // → 'cyan'
+
+// Partial match (ClickUp-style)
+getStatusColorScheme('In Progress') // → 'warning'
+getStatusColorScheme('Done')        // → 'success'
+getStatusColorScheme('Code Review') // → 'cyan'
+
+// Consumed by StatusBadge
+<StatusBadge colorScheme={getStatusColorScheme(task.status)} label={task.status} />
+```
+
+> **Note:** This is the lib-side subset of the hub's `agent-status-message.ts`. CSS class resolvers and the `AgentStatusMessage` SSE builder live hub-side, as they reference hub-only ODS class names.

package/src/components/chat/utils/.auto-continuation-directive.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 202df1de78269679793058f2735da78c -->
+Brief description of the file's purpose and what it does.
+
+Defines the shared cross-process contract for the post-approval auto-continuation directive, providing a single source of truth for both server-side routing and client-side message construction.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AUTO_CONTINUATION_DIRECTIVE_PREFIX` | `const string` | Sentinel prefix used by both `decideRoute` (server) and `autoContinueRef` (client) to identify hidden directive messages |
+| `BuildAutoContinuationOptions` | `interface` | Options bag for `ticketId` and `status` to branch directive logic |
+| `buildAutoContinuationDirective` | `function` | Builds the hidden synthetic user message injected after every successful tool approval |
+
+## Directive Branches
+
+```mermaid
+graph TD
+    A["buildAutoContinuationDirective(toolName, opts)"] --> B{"toolName?"}
+    B -->|"create_ticket"| C["§1a — Ask 2-4 diagnostic\nfollow-up questions"]
+    B -->|"update_ticket + CLOSED"| D["§1b — Ask ONE closing\nresolution question"]
+    B -->|"update_ticket (other)"| E["Acknowledge change,\nask if anything else needed"]
+    C --> F["Prefix + prose only\nNo tool call this turn"]
+    D --> F
+    E --> F
+```
+
+## Usage Example
+
+```typescript
+import {
+  AUTO_CONTINUATION_DIRECTIVE_PREFIX,
+  buildAutoContinuationDirective,
+} from './auto-continuation-directive'
+
+// After a create_ticket approval — injects diagnostic follow-up Qs
+const directive = buildAutoContinuationDirective('create_ticket', {
+  ticketId: '4821',
+})
+// → "[internal-auto-continuation] The user just approved create_ticket (ticket #4821). ..."
+
+// After closing a ticket
+const closeDirective = buildAutoContinuationDirective('update_ticket', {
+  ticketId: '4821',
+  status: 'CLOSED',
+})
+// → "[internal-auto-continuation] The user just approved closing ticket #4821. ..."
+
+// Server-side route guard — tools disabled for directive turns
+if (rawUserQuery.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX)) {
+  disableTools()
+}
+```
+
+## Important Constraints
+
+- **Never drift the prefix** — server `decideRoute` and client `autoContinueRef` must both import from this file. A mismatched literal silently re-enables tools, causing the LLM to duplicate the just-approved tool call.
+- **Tools are hard-disabled** on the directive turn — all branches instruct the LLM to respond with prose only.
+- `toolName` is typed as `string` (not a const-union) intentionally, keeping the module generic across hub deployments.

package/src/components/chat/utils/.chat-attachment-markdown.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 3113ae48366d1440e4d993a3e0404da3 -->
+Shared utility providing a single source of truth for formatting and parsing chat attachment markdown between the host-side bubble renderer and server-side LLM input cleaner, preventing drift between the two systems.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `CHAT_ATTACHMENT_VIEW_URL_PREFIX` | `const` | Hub-default proxy URL prefix for attachment view routes |
+| `CHAT_ATTACHMENT_VIEW_TOKEN_QUERY_PARAM` | `const` | Query param name (`t`) for the HMAC view token |
+| `ANTHROPIC_SUPPORTED_IMAGE_MIME` | `const` | Image MIME types renderable as Anthropic image blocks |
+| `ChatAttachment` | `interface` | Wire shape for a single chat attachment |
+| `buildChatAttachmentViewUrl` | `function` | Constructs the signed proxy URL for an attachment |
+| `escapeMarkdownInline` | `function` | Sanitizes filenames against markdown injection attacks |
+| `formatChatAttachmentMarkdownForBubble` | `function` | Produces the `![]()` or `[Attached: ...]` markdown line |
+| `CHAT_ATTACHMENT_MARKDOWN_PATTERN` | `RegExp` | Anchored regex matching both image and link attachment forms |
+| `stripChatAttachmentMarkdown` | `function` | Strips attachment markdown from text and extracts storage paths |
+
+## Usage Example
+
+```typescript
+import {
+  CHAT_ATTACHMENT_VIEW_URL_PREFIX,
+  formatChatAttachmentMarkdownForBubble,
+  stripChatAttachmentMarkdown,
+} from './chat-attachment-markdown'
+
+// Host-side: format attachment for user bubble (pass runtime prefix)
+const attachment: ChatAttachment = {
+  storagePath: 'org-123/chat/screenshot.png',
+  viewToken: 'hmac-signed-token',
+  contentType: 'image/png',
+  fileName: 'screenshot.png',
+  size: 204800,
+}
+
+// Embedded app overrides prefix; hub uses the constant directly
+const markdown = formatChatAttachmentMarkdownForBubble(
+  attachment,
+  'https://hub.example.com/api/storage/view/chat-attachments/',
+)
+// → "\n\n![screenshot.png](https://hub.example.com/api/storage/view/...?t=...)"
+
+// Server-side: strip attachment lines before sending to LLM
+const userMessage = `Please review this\n\n![screenshot.png](/api/storage/view/chat-attachments/org-123/chat/screenshot.png?t=abc)`
+const { stripped, storagePaths } = stripChatAttachmentMarkdown(userMessage)
+// stripped    → "Please review this"
+// storagePaths → ["org-123/chat/screenshot.png"]
+```
+
+## Security Notes
+
+- **Markdown injection**: `escapeMarkdownInline` escapes `[`, `]`, `(`, `)`, `\`, `<`, `>`, and `"` from filenames — preventing a crafted name like `screenshot](https://evil.com).png` from hijacking the image URL.
+- **Anthropic image blocks**: raw Supabase signed URLs are used (not the proxy) because Anthropic's fetcher does not reliably follow `302` redirects.
+- **View tokens**: HMAC-signed server-side; the client never generates them.

package/src/components/chat/utils/.chat-authed-fetch.md

@@ -0,0 +1,25 @@
+<!-- source-hash: b57cf7dd5609e4a80ebf96f0658340cc -->
+Re-exports `embedAuthedFetch` under the legacy `chatAuthedFetch` alias to maintain backwards compatibility for existing chat-namespace callers.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `chatAuthedFetch` | Re-export (alias) | Legacy alias for `embedAuthedFetch` from `utils/embed-authed-fetch` |
+
+## Usage Example
+
+**New code** should import directly from the canonical source:
+
+```typescript
+import { embedAuthedFetch } from '@flamingo-stack/openframe-frontend-core/utils'
+```
+
+**Legacy callers** (still compiling via this shim):
+
+```typescript
+import { chatAuthedFetch } from './chat-authed-fetch'
+// chatAuthedFetch === embedAuthedFetch — same function, legacy name
+```
+
+> **⚠️ Deprecated:** This file is a compatibility shim only. All new code — whether in the chat or ticket center namespace — should import `embedAuthedFetch` from `@flamingo-stack/openframe-frontend-core/utils` directly. Wire headers (`X-Chat-Act-As`, etc.) are unchanged by the rename.

package/src/components/chat/utils/.chat-nav-resolution.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 1b020dd80f0099498e2af194cf845b64 -->
+Handles embed-mode URL resolution and external navigation for chat panel link interactions, ensuring relative paths are correctly absolutized against the embedder-supplied content origin and opened safely in new tabs.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `NEW_TAB_FEATURES` | `const` | Window features string (`noopener,noreferrer`) for reverse-tabnabbing prevention |
+| `isModifierClick` | `function` | Detects cmd/ctrl/shift/alt or non-primary button clicks |
+| `stripSameOriginToPath` | `function` | Strips origin from same-origin absolute URLs, returning a router-friendly relative path |
+| `resolveHrefForRuntime` | `function` | Pre-resolves hrefs against `defaultContentOrigin` in embed mode; no-op in host mode |
+| `resolveExternalNavigation` | `function` | Full resolution pipeline — absolutizes href, handles protocol-relative guards, returns an inline-callable `open()` |
+| `ExternalNavResolution` | `interface` | Return type: resolved `href` + synchronous `open()` invoker |
+
+## Usage Example
+
+```typescript
+import {
+  resolveExternalNavigation,
+  resolveHrefForRuntime,
+  isModifierClick,
+} from './chat-nav-resolution'
+
+// Pre-render: absolutize href so modifier-click / status bar shows correct URL
+const resolvedHref = resolveHrefForRuntime('/knowledge-base/article.md', runtime)
+// embed mode + defaultContentOrigin="https://hub.example.com"
+// → "https://hub.example.com/knowledge-base/article.md"
+
+// onClick handler
+function handleChipClick(e: React.MouseEvent, href: string) {
+  if (isModifierClick(e)) return // let browser handle natively (already absolute)
+
+  const { open } = resolveExternalNavigation({
+    href,
+    targetPlatform: 'hub',
+    runtime,
+  })
+  open() // must be called synchronously inside user gesture
+}
+```
+
+## Notes
+
+- `resolveExternalNavigation` uses an explicit `if/else` (not `??`) when invoking `openExternal` to avoid a double-open bug where a `void` return would fall through to `window.open`.
+- Protocol-relative URLs (`//evil.com/path`) are normalized to `https://` before processing to prevent open-redirect vulnerabilities.
+- In embed mode, relative hrefs without a `defaultContentOrigin` emit a `console.warn` in non-production environments.

package/src/components/chat/utils/.chat-proxy-auth-storage.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 951b153c177b85c14bc55650838662fe -->
+Thin compatibility shim that re-exports the canonical embed proxy authentication utilities under legacy `chat-`-prefixed names, preserving backward compatibility for existing chat-namespace callers.
+
+## Key Components
+
+| Export | Original Name | Description |
+|--------|--------------|-------------|
+| `ChatProxyAuth` | `EmbedProxyAuth` | Type alias for the proxy auth object |
+| `getChatProxyAuth` | `getEmbedProxyAuth` | Retrieves current proxy auth from storage |
+| `setChatProxyAuth` | `setEmbedProxyAuth` | Persists proxy auth to storage |
+| `clearChatProxyAuth` | `clearEmbedProxyAuth` | Clears proxy auth from storage |
+| `getPersistedProxyEmail` | *(unchanged)* | Reads the persisted proxy email |
+| `applyProxyAuth` | *(unchanged)* | Applies proxy auth headers to requests |
+
+> **Deprecated:** All exports here are forwarded from `@flamingo-stack/openframe-frontend-core/utils/embed-proxy-auth-storage`. New code should import from that module directly. Wire headers (`X-Chat-Act-As`, etc.) and the storage key (`chat.proxy-auth.v1`) remain unchanged.
+
+## Usage Example
+
+**Legacy callers (still valid, but deprecated):**
+
+```typescript
+import { getChatProxyAuth, setChatProxyAuth, clearChatProxyAuth } from './chat-proxy-auth-storage'
+
+const auth = getChatProxyAuth()
+setChatProxyAuth({ token: 'abc123', email: 'tech@msp.com' })
+clearChatProxyAuth()
+```
+
+**New code should import from the canonical path:**
+
+```typescript
+import {
+  getEmbedProxyAuth,
+  setEmbedProxyAuth,
+  clearEmbedProxyAuth,
+  applyProxyAuth,
+} from '@flamingo-stack/openframe-frontend-core/utils'
+```

package/src/components/chat/utils/.chip-action-class.md

@@ -0,0 +1,34 @@
+<!-- source-hash: cef5cf927873caff6558f4d9a0c3a3ed -->
+Defines and exports a single shared Tailwind CSS class string for chip-density action buttons used across the device density UI components.
+
+## Key Components
+
+- **`CHIP_ACTION_BUTTON_CLASS`** — A constant string of Tailwind utility classes providing consistent styling for compact action buttons (e.g., Recent, Search, Find, Display, Submit, Cancel) rendered inside chip card tertiary action rows and the `<DisplayChipAction>` popover.
+
+## Usage Example
+
+```typescript
+import { CHIP_ACTION_BUTTON_CLASS } from './chip-action-class'
+
+// Apply to a button element
+<button className={CHIP_ACTION_BUTTON_CLASS}>
+  Recent
+</button>
+
+// Extend with additional classes when needed
+<button className={`${CHIP_ACTION_BUTTON_CLASS} my-extra-class`}>
+  Search
+</button>
+```
+
+## Design Notes
+
+| Property | Value | Intent |
+|----------|-------|--------|
+| Font size | `text-[11px]` | Sub-UI-Kit density, fits chip action rows |
+| Padding | `px-2 py-1` | Tight, below standard `Button size="small"` |
+| Colors | `ods-text-secondary` / hover `ods-text-primary` | ODS token-based theming |
+| Background | `bg-transparent` / hover `ods-card-hover` | Subtle interactive feedback |
+| Focus ring | `focus-visible:ring-ods-focus` | Accessible keyboard navigation |
+
+Centralizing this constant prevents Tailwind class chain drift across the empty-state chip and `<DisplayChipAction>` popover, ensuring byte-equivalent styling at both call sites.

package/src/components/chat/utils/.chip-styles.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 53f316e6709d2c8161bb544234df2d3a -->
+Centralises Tailwind/ODS className generation for the chat-adjacent UI chip family, ensuring consistent styling across citation chips, inline entity-card pills, and search-result dropdown rows.
+
+## Key Components
+
+### `ChipClassOptions` (interface)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tone` | `'primary' \| 'secondary'` | Controls resting text color — `primary` matches body text; `secondary` is muted for metadata |
+| `density` | `'chip' \| 'list-row' \| 'card-row'` | Controls size/padding variant. Defaults to `'chip'` |
+| `extra` | `string` | Optional additional classes appended verbatim (e.g. `cursor-pointer`) |
+
+### `chatChipClass(options)` (function)
+
+Accepts a `ChipClassOptions` object and returns a composed Tailwind class string. All three density variants share the same border, hover transition, and accent treatment so they read as one UI family regardless of size.
+
+| Density | Sizing | Frame |
+|---------|--------|-------|
+| `chip` | `px-2 py-0.5 text-[11px]` | bordered card bg |
+| `list-row` | `px-3 py-2 text-sm` | bordered card bg |
+| `card-row` | `px-2 py-1 text-[11px]` | no border/bg |
+
+## Usage Example
+
+```typescript
+import { chatChipClass } from './chip-styles'
+
+// Citation chip (default density)
+const citationClass = chatChipClass({ tone: 'secondary' })
+
+// Search dropdown row
+const dropdownRowClass = chatChipClass({
+  tone: 'primary',
+  density: 'list-row',
+  extra: 'cursor-pointer w-full',
+})
+
+// Tracking strip under a card frame
+const cardRowClass = chatChipClass({
+  tone: 'secondary',
+  density: 'card-row',
+})
+```
+
+> **Design note:** A single ODS token change here propagates to all three surfaces simultaneously — citation chips, inline entity markers, and search results will always render as the same visual family.

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

@@ -1,41 +1,51 @@
-<!-- source-hash: 7638e9ed81b8f00f7e8ab732efcd6c0b -->
-Utilities for parsing NATS message chunks into structured actions for AI tool execution workflows. This module provides functions to transform raw chunk data into typed action objects and utilities for identifying different chunk types.
+<!-- source-hash: 637d22f77dbdb02b04013632095ddfdb -->
+Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the AI message pipeline.
 
 ## Key Components
 
-- **`parseChunkToAction`** - Main parser function that converts raw NATS chunks into structured `ParsedChunkAction` objects
-- **`isControlChunk`** - Identifies message start/end control chunks
-- **`isErrorChunk`** - Detects error message chunks
-- **`isMetadataChunk`** - Identifies AI model metadata chunks
-- **`extractTextFromChunk`** - Extracts text content from text-type chunks
+### `parseChunkToAction(chunk)`
+Core export that maps a raw `ChunkData` object to a `ParsedChunkAction` union type. Uses a `switch` on `MESSAGE_TYPE` to handle all supported message variants:
+
+| Action | Description |
+|---|---|
+| `message_start` / `message_end` | Lifecycle control signals |
+| `metadata` | AI model/provider info |
+| `text` / `thinking` / `system` | Content streaming |
+| `tool_execution` | Tool start/completion events |
+| `approval_request` / `approval_batch` | Single or multi-tool approval flows |
+| `approval_result` | Approval outcome |
+| `token_usage` | Token consumption stats |
+| `context_compaction_start/end` | Context window management |
+| `direct_message` | Owner-attributed messages |
+| `dialog_closed` | Session termination |
+
+Returns `null` for unknown or malformed chunks.
+
+### `normalizeToolCalls(raw)` *(internal)*
+Coerces an unknown array into `PendingToolCallData[]`, safely defaulting missing fields and enforcing correct types.
+
+### Guard Helpers
+Lightweight boolean checks for common chunk classifications:
+
+- `isControlChunk(chunk)` — start/end signals
+- `isErrorChunk(chunk)` — error type
+- `isMetadataChunk(chunk)` — AI metadata
+- `extractTextFromChunk(chunk)` — returns text content or `null`
 
 ## Usage Example
 
 ```typescript
-import { parseChunkToAction, isControlChunk, extractTextFromChunk } from './chunk-parser'
+import { parseChunkToAction, isErrorChunk } from './chunk-parser'
 
-// Parse different chunk types
-const textChunk = { type: 'TEXT', text: 'Hello world' }
-const action = parseChunkToAction(textChunk)
-// Returns: { action: 'text', text: 'Hello world' }
+// Incoming NATS message payload
+const raw = { type: 'TEXT', text: 'Hello from Mingo AI' }
 
-// Check for control messages
-const startChunk = { type: 'MESSAGE_START' }
-if (isControlChunk(startChunk)) {
-  console.log('Processing message start')
+if (isErrorChunk(raw)) {
+  console.error('Stream error received')
 }
 
-// Extract text content
-const text = extractTextFromChunk(textChunk)
-// Returns: 'Hello world'
-
-// Handle tool execution
-const toolChunk = {
-  type: 'EXECUTING_TOOL',
-  integratedToolType: 'filesystem',
-  toolFunction: 'readFile',
-  parameters: { path: '/tmp/file.txt' }
+const action = parseChunkToAction(raw)
+if (action?.action === 'text') {
+  renderText(action.text) // "Hello from Mingo AI"
 }
-const toolAction = parseChunkToAction(toolChunk)
-// Returns structured tool execution action
 ```