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

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

@@ -1,16 +1,14 @@
-<!-- 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.
+<!-- source-hash: 7b39d1e6bf453026c3f2a4c5ea757aff -->
+Wire-shape type definitions for the chat onboarding-guide card and `/api/onboarding-guides` API responses, including entity structure, filter parameters, and list/section summary response shapes.
 
 ## 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 |
+| Export | Kind | Description |
+|---|---|---|
+| `OnboardingGuide` | `interface` | Full entity row shape with content, video pipeline, SEO, workflow, and audit fields |
+| `OnboardingGuideFilters` | `interface` | Query filter parameters for listing/searching guides |
+| `OnboardingGuideListResponse` | `interface` | Paginated list response wrapping `OnboardingGuide[]` with a total count |
+| `OnboardingGuideSectionSummary` | `interface` | Aggregated section metadata — section name, order, and guide count |
 
 ## Usage Example
 
@@ -19,32 +17,35 @@ import type {
   OnboardingGuide,
   OnboardingGuideFilters,
   OnboardingGuideListResponse,
+  OnboardingGuideSectionSummary,
 } 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;
-}
+// Fetch guides with filters
+const filters: OnboardingGuideFilters = {
+  status: 'published',
+  section: 'getting-started',
+  platform: 'openframe',
+  limit: 10,
+  offset: 0,
+};
+
+const response: OnboardingGuideListResponse = await fetch(
+  `/api/onboarding-guides?${new URLSearchParams(filters as Record<string, string>)}`
+).then((r) => r.json());
+
+// Access guide fields
+const guide: OnboardingGuide = response.data[0];
+const videoUrl = guide.main_video_url ?? guide.youtube_url;
+const platforms = guide.onboarding_guide_platforms?.filter((p) => p.is_featured);
+
+// Section summary
+const summary: OnboardingGuideSectionSummary = {
+  section: guide.section,
+  section_order: guide.section_order,
+  count: response.count,
+};
 ```
 
-## Notes
+> **Note:** Server-side DAL methods (`createOnboardingGuide`, `updateOnboardingGuide`, `resolvePublicPlatformScope`) remain hub-side. Only the row type and filter/response shapes are exported from this module.
 
-- **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.
+**Source:** [`onboarding-guide.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-guide.ts)

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

@@ -1,57 +1,69 @@
-<!-- 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.
+<!-- source-hash: 10cd7a28cb940588c11a2ef95de5ce12 -->
+Defines the core TypeScript types and interfaces for the Unified Program System, which provides a single generic abstraction layer for handling events, podcasts, and webinars across public and admin surfaces.
 
 ## 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` |
+### Host & Author Types
+- **`ProgramHost`** — Host/speaker info (name, avatar, role) sourced from provider sync (Luma, Podbean, Livestorm)
+- **`ProgramAuthorRef`** — Client-safe author subset from `profiles` FK join; excludes email for public payloads
+- **`programItemToStripProfile()`** — Resolves a `VideoBiteStripProfile` from an item's author or first host; routes through `toStripProfile` as SSoT
+
+### Database Row Types
+- **`LumaEventRow`** — Raw row from `luma_events`
+- **`PodcastEpisodeRow`** — Raw row from `podcast_episodes` (includes video/audio override fields)
+- **`WebinarRow`** — Raw row from `webinars` (includes Livestorm recording and override fields)
+
+### Program Item Interfaces
+- **`BaseProgramItem`** — Common shape all program items implement (`id`, `title`, `cover_url`, `date`, `hosts`, etc.)
+- **`EventItem`** — Extends base with location, geo, and Luma-specific fields
+- **`PodcastItem`** — Extends base with audio/video URLs, AI processing, and SEO fields
+- **`WebinarItem`** — Extends base with Livestorm recording, AI processing, and SEO fields
+
+### Configuration Types
+- **`ProgramType`** — `'event' | 'podcast' | 'webinar'`
+- **`ProgramLabels`** — Display strings (singular, plural, section headers, empty states)
+- **`ProgramConfig<T>`** — Core configuration object driving generic component behavior (table name, API endpoint, routing, icons, sort order)
+
+### Response Types
+- **`ProgramListResponse<T>`** — Paginated list result
+- **`ProgramItemResponse<T>`** — Single item with optional media
+- **`ProgramMedia`** — Associated media records (image/video/audio)
 
 ## Usage Example
 
 ```typescript
 import type {
   ProgramConfig,
-  EventItem,
+  PodcastItem,
   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',
-  },
+import { MicIcon } from 'lucide-react';
+
+const podcastLabels: ProgramLabels = {
+  singular: 'Episode',
+  plural: 'Episodes',
+  upcoming: 'Latest Episode',
+  upcomingSection: 'Latest Episodes',
+  archive: 'All Episodes',
+  empty: 'No episodes yet',
 };
 
-// Transform a raw DB row into a typed EventItem
-const row = await db.from('luma_events').select('*').single();
-const eventItem: EventItem = transformEventToProgram(row);
-```
+const podcastConfig: ProgramConfig<PodcastItem> = {
+  type: 'podcast',
+  labels: podcastLabels,
+  dateField: 'published_at',
+  table: 'podcast_episodes',
+  apiEndpoint: '/api/podcasts',
+  icon: <MicIcon />,
+  externalLinkLabel: 'Listen on Podbean',
+  detailRoute: '/podcasts',
+  sortOrder: 'desc',
+};
 
-> `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.
+// Resolve a strip profile for video-bites overlay
+const profile = programItemToStripProfile({
+  author: { full_name: 'Jane Doe', avatar_url: '/jane.png' },
+  hosts: [{ name: 'Fallback Host', role: 'team_member' }],
+});
+// → resolves from author first; falls back to first host
+```

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

@@ -1,34 +1,32 @@
-<!-- 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.
+<!-- source-hash: c8729430311476480b1576febdfc94b2 -->
+Defines and exports a single shared Tailwind CSS class string for chip-density action buttons used across the empty-state chip's action row and the `<DisplayChipAction>` popover.
 
 ## 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.
+- **`CHIP_ACTION_BUTTON_CLASS`** — A frozen CSS utility string combining text, background, border, spacing, and focus-ring styles for sub-`small` density action buttons (Recent / Search / Find / Display / Submit / Cancel).
 
 ## 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>
+// Apply to a native button element
+<button class={CHIP_ACTION_BUTTON_CLASS}>Recent</button>
 
-// Extend with additional classes when needed
-<button className={`${CHIP_ACTION_BUTTON_CLASS} my-extra-class`}>
-  Search
-</button>
+// Or spread into a component's class prop
+<ActionButton class={CHIP_ACTION_BUTTON_CLASS}>Search</ActionButton>
 ```
 
 ## Design Notes
 
-| Property | Value | Intent |
-|----------|-------|--------|
-| Font size | `text-h6` | 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 |
+| Property | Value / Intent |
+|---|---|
+| Font size | `text-h6` (~11px) — below UI-Kit `Button size="small"` |
+| Padding | `px-2 py-1` — chip-density, not standard button sizing |
+| Colors | ODS semantic tokens (`ods-text-*`, `ods-card-hover`, `ods-border`) |
+| Focus ring | `focus-visible:ring-2` with `ods-focus` token — keyboard accessible |
+| Background | `bg-transparent` base, `ods-card-hover` on hover |
 
-Centralizing this constant prevents Tailwind class chain drift across the empty-state chip and `<DisplayChipAction>` popover, ensuring byte-equivalent styling at both call sites.
+The constant prevents Tailwind class strings from drifting independently across the two call sites. Any styling change is made once here and propagates uniformly.
+
+**Source:** [`chip-action-class.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chip-action-class.ts)

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

@@ -1,46 +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.
+<!-- source-hash: d45a902b18f3712e1b2aeac789ac6496 -->
+Shared className generator for the chat-adjacent UI family, producing consistent Tailwind/ODS class strings for source 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`) |
+|---|---|---|
+| `tone` | `'primary' \| 'secondary'` | Resting text color — `primary` reads as content, `secondary` as metadata |
+| `density` | `'chip' \| 'list-row' \| 'card-row'` | Size/padding variant. Defaults to `'chip'` |
+| `extra` | `string` | Extra classes appended verbatim (e.g. `cursor-pointer`) |
 
-### `chatChipClass(options)` (function)
+### `chatChipClass(options: ChipClassOptions): string`
 
-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.
+Returns a composed Tailwind class string. All three density variants share border, hover transition, and accent treatment so they read as the same ODS family — only the size and frame differ.
 
-| Density | Sizing | Frame |
-|---------|--------|-------|
-| `chip` | `px-2 py-0.5 text-h6` | bordered card bg |
-| `list-row` | `px-3 py-2 text-sm` | bordered card bg |
-| `card-row` | `px-2 py-1 text-h6` | no border/bg |
+| `density` | Sizing | Frame |
+|---|---|---|
+| `'chip'` | `px-2 py-0.5 text-h6` | Border + card bg + rounded |
+| `'list-row'` | `px-3 py-2 text-sm` | Border + card bg + rounded |
+| `'card-row'` | `px-2 py-1 text-h6` | No border, no bg (sits under a card frame) |
 
 ## Usage Example
 
 ```typescript
 import { chatChipClass } from './chip-styles'
 
-// Citation chip (default density)
+// Citation chip below an assistant turn
 const citationClass = chatChipClass({ tone: 'secondary' })
 
-// Search dropdown row
-const dropdownRowClass = chatChipClass({
+// Search-bar dropdown row with click affordance
+const searchRowClass = chatChipClass({
   tone: 'primary',
   density: 'list-row',
   extra: 'cursor-pointer w-full',
 })
 
-// Tracking strip under a card frame
+// Tracking strip inside a card frame (no border/bg)
 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.
+**Source:** [`chip-styles.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chip-styles.ts)

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

@@ -1,51 +1,62 @@
-<!-- source-hash: 637d22f77dbdb02b04013632095ddfdb -->
-Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the AI message pipeline.
+<!-- source-hash: c8c1cef3b3966f8791e7003c4f74429f -->
+Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the OpenFrame chat pipeline.
 
 ## Key Components
 
-### `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:
+### `parseChunkToAction(chunk: unknown): ParsedChunkAction | null`
+The primary export. Accepts an untyped NATS chunk, inspects its `type` field against `MESSAGE_TYPE` constants, and returns a discriminated `ParsedChunkAction` union or `null` for unrecognized types. Handles the full message lifecycle including:
 
-| Action | Description |
+- **Lifecycle signals:** `message_start`, `message_end`, `dialog_closed`
+- **Content:** `text`, `thinking`, `system`, `direct_message`
+- **Tool execution:** `tool_execution` (both `EXECUTING_TOOL` and `EXECUTED_TOOL` states)
+- **Approval flow:** `approval_request`, `approval_batch`, `approval_result`
+- **Metadata & telemetry:** `metadata`, `token_usage`, `context_compaction_start/end`
+- **Error handling:** `error`
+
+### `normalizeToolCalls(raw: unknown): PendingToolCallData[]` *(internal)*
+Safely coerces an untyped array into `PendingToolCallData[]`, filtering non-objects and providing safe defaults for all fields.
+
+### Predicate helpers
+Lightweight type guards for fast chunk classification without full parsing:
+
+| Function | Returns `true` when |
 |---|---|
-| `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`
+| `isControlChunk` | `MESSAGE_START` or `MESSAGE_END` |
+| `isErrorChunk` | `ERROR` type |
+| `isMetadataChunk` | `AI_METADATA` type |
+| `extractTextFromChunk` | `TEXT` type — returns the string or `null` |
 
 ## Usage Example
 
 ```typescript
-import { parseChunkToAction, isErrorChunk } from './chunk-parser'
+import {
+  parseChunkToAction,
+  isControlChunk,
+  isErrorChunk,
+} from './chunk-parser'
 
-// Incoming NATS message payload
-const raw = { type: 'TEXT', text: 'Hello from Mingo AI' }
+// Parse an incoming NATS chunk
+const action = parseChunkToAction(rawChunk)
 
-if (isErrorChunk(raw)) {
-  console.error('Stream error received')
+if (action?.action === 'text') {
+  appendToTranscript(action.text)
+} else if (action?.action === 'approval_batch') {
+  promptUserApproval(action.toolCalls)
 }
 
-const action = parseChunkToAction(raw)
-if (action?.action === 'text') {
-  renderText(action.text) // "Hello from Mingo AI"
+// Fast-path guards before full parse
+if (isErrorChunk(rawChunk)) {
+  handleError()
 }
-```
+if (isControlChunk(rawChunk)) {
+  resetStreamState()
+}
+```
+
+## Notes
+
+- All field access is defensive — missing or wrong-typed properties fall back to safe defaults rather than throwing.
+- `approval_result` accepts both `resolvedByName` and `displayName` so realtime NATS chunks and GraphQL history replays produce identical output shapes.
+- `contextItems` on `message_request` back-fills `label` from `id` to satisfy the required `ChatContextItem` contract when no label is present on the wire.
+
+**Source:** [`https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chunk-parser.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chunk-parser.ts)

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

@@ -1,30 +1,41 @@
-<!-- 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.
+<!-- source-hash: ad42c4031c2afe62a64d7457c6018d7e -->
+Single source of truth for compact card Tailwind class constants and URL safety validation used across chat-inline `size='sm'` card frames.
 
 ## Key Components
 
-### Class Constants
+### 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_OUTER` | Interactive anchor frame with hover/transition styles |
+| `COMPACT_CARD_OUTER_STATIC` | Non-interactive span frame (`cursor-default`, no hover) |
+| `COMPACT_CARD_SKELETON_OUTER` | Skeleton frame with `animate-pulse` |
 | `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_SKELETON_IMAGE_SLOT` | 56×56 placeholder for skeleton state |
+| `COMPACT_CARD_ICON_SLOT` | 56×56 icon container (cards without a cover image) |
+| `COMPACT_CARD_TEXT_COL` | Flex column wrapper for title/subtitle/meta rows |
+| `COMPACT_CARD_TITLE_ROW` | Fixed 20px title row container |
+| `COMPACT_CARD_META_ROW_BOX` | Fixed 16px subtitle/summary row container |
+| `COMPACT_CARD_TITLE` | Bold 14px/20px leading title text |
+| `COMPACT_CARD_SUBTITLE` | 11px secondary text |
+| `COMPACT_CARD_SUMMARY` | 11px 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 |
+| `COMPACT_CARD_ROW_FILLER` | Non-breaking space to preserve 16px 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`.
+**`safeHref(url)`** — Validates a URL before use in an `<a href>`. Returns the original string only if it passes all safety checks, otherwise `null`.
+
+Allowed:
+- `http:`, `https:`, `mailto:` schemes
+- Same-origin paths starting with `/` (not `//`)
+- Hash fragments starting with `#`
+
+Rejected:
+- Control/zero-width/line-separator characters
+- Unknown schemes (`javascript:`, `data:`, etc.)
+- Bare scheme-only strings
+- `http`/`https` URLs with no hostname
 
 ## Usage Example
 
@@ -40,23 +51,10 @@ import {
 
 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>
-)
+// Renders an interactive anchor if href is safe, otherwise a static span
+const outerClass = href ? COMPACT_CARD_OUTER : COMPACT_CARD_OUTER_STATIC
+const Wrapper = href ? 'a' : 'span'
+const wrapperProps = href ? { href } : {}
 ```
 
-> 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.
+> **Card-specific variation** (play overlays, pill badges, status indicators) lives inside each individual card component. These constants govern only the shared outer frame — uniform across all compact card types.

package/src/components/chat/utils/.execute-navigation.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 2635bcbc16b7313a29642d0f68f41942 -->
+Unified navigation execution primitive that centralizes all navigation actions — new-tab vs. same-tab, internal vs. external, embed vs. host, and runtime/router/window fallback chain — into a single module consumed by every interactive surface in the library.
+
+## Key Components
+
+### Interfaces
+
+- **`NavClickEvent`** — Minimal structural mouse-event interface (subset of `React.MouseEvent`) so chip buttons and tiles can call the handler without casting.
+- **`ExecuteNavigationClickArgs`** — Arguments for the click-handler form: event, runtime, `href`, optional `path`, `targetPlatform`, and `fallbackNavigate`.
+- **`ExecuteNavigationImperativeArgs`** — Arguments for the imperative form: same as above minus the event.
+
+### Functions
+
+- **`runNavigation`** *(internal)* — Core decision engine. Computes new-tab vs. same-tab, routes same-page hash anchors through `navigateSamePageHash`, delegates to `runtime.navigation.navigate`, and falls back to `fallbackNavigate` or `window.location.assign`.
+- **`executeNavigation`** — Click-handler form. Skips modifier/non-primary clicks (returning `false` so the browser handles them natively), calls `preventDefault`, then delegates to `runNavigation`. Returns `true` when it took action.
+- **`executeNavigationImperative`** — Imperative form for buttons, list rows, and post-action redirects. Same decision tree, no event/modifier logic.
+
+## Usage Example
+
+```typescript
+// Click-handler form (anchor / chip)
+import { executeNavigation } from './execute-navigation'
+
+function ChatCard({ href, runtime }) {
+  return (
+    <a
+      href={href}
+      onClick={(event) =>
+        executeNavigation({ event, runtime, href, targetPlatform: 'web' })
+      }
+    >
+      Open
+    </a>
+  )
+}
+
+// Imperative form (button / post-submit redirect)
+import { executeNavigationImperative } from './execute-navigation'
+
+function handleFormSuccess(runtime, href) {
+  executeNavigationImperative({
+    runtime,
+    href,
+    fallbackNavigate: router.push, // useRouter().push
+  })
+}
+```
+
+> **No runtime?** Pass `null` — the module skips the new-tab/embed decision and falls back to `window.location.assign` (or your `fallbackNavigate`). Safe for surfaces like announcement bars that have no `ChatRuntimeContext`.

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

@@ -1,15 +1,16 @@
-<!-- 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.
+<!-- source-hash: d829899f7bd3695292f7399c706c0b38 -->
+Extracts incomplete message state from the last historical assistant message, enabling the realtime chunk processor to resume building messages across reconnected sessions.
 
 ## Key Components
 
 ### `extractIncompleteMessageState(lastMessage)`
 
-**Parameters:** `lastMessage: ProcessedMessage | undefined`
+Inspects a `ProcessedMessage` and returns resumable state if any in-progress segments are found.
 
-**Returns:** `{ existingSegments?, pendingApprovals?, executingTools? } | undefined`
+**Parameters:**
+- `lastMessage` — A `ProcessedMessage` or `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.
+**Returns:** An object with optional `existingSegments`, `pendingApprovals`, and `executingTools`, or `undefined` if the message is complete or ineligible.
 
 **Incomplete state detection by segment type:**
 
@@ -17,7 +18,7 @@ Returns `undefined` if the message is complete or not an assistant message with
 |---|---|
 | `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 |
+| `approval_batch` | Not `rejected` and not all tool calls have `done` executions |
 | `context_compaction` | Status is `started` |
 
 ## Usage Example
@@ -29,7 +30,7 @@ const lastMessage = conversationHistory.at(-1)
 const incompleteState = extractIncompleteMessageState(lastMessage)
 
 if (incompleteState) {
-  realtimeProcessor.initialize({
+  initializeRealtimeChunkProcessor({
     existingSegments: incompleteState.existingSegments,
     pendingApprovals: incompleteState.pendingApprovals,
     executingTools: incompleteState.executingTools,
@@ -37,8 +38,4 @@ if (incompleteState) {
 }
 ```
 
-## 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`
+**Source:** [`extract-incomplete-message-state.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/extract-incomplete-message-state.ts)