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

package/src/utils/.generic-domain-utils.md

@@ -0,0 +1,42 @@
+<!-- source-hash: d4d35ff06ab39090293de947a43da21c -->
+Utility module for detecting personal/consumer email providers, distinguishing them from business/corporate domains.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `GENERIC_EMAIL_DOMAINS` | `const` array | Readonly list of ~30 known generic email domains (Gmail, Yahoo, iCloud, ISPs, international providers) |
+| `GenericEmailDomain` | `type` | Union type inferred from `GENERIC_EMAIL_DOMAINS` entries |
+| `extractDomainFromEmail` | `function` | Parses the domain portion from an email address string |
+| `normalizeDomain` | `function` | Strips protocol, `www.`, and paths from a domain or URL string |
+| `isGenericDomain` | `function` | Returns `true` if a domain matches any entry in `GENERIC_EMAIL_DOMAINS` |
+| `hasGenericEmailDomain` | `function` | Checks whether an email address belongs to a generic provider |
+| `isGenericWebsiteDomain` | `function` | Checks whether a website URL resolves to a generic provider domain |
+
+## Usage Example
+
+```typescript
+import {
+  extractDomainFromEmail,
+  hasGenericEmailDomain,
+  isGenericDomain,
+  isGenericWebsiteDomain,
+} from './generic-domain-utils'
+
+// Extract domain from email
+extractDomainFromEmail('user@gmail.com')     // → 'gmail.com'
+extractDomainFromEmail('invalid-email')      // → null
+
+// Check if an email uses a generic provider
+hasGenericEmailDomain('user@gmail.com')      // → true
+hasGenericEmailDomain('user@acme.com')       // → false
+
+// Check a raw domain string
+isGenericDomain('yahoo.com')                 // → true
+
+// Check a website URL (strips protocol/www automatically)
+isGenericWebsiteDomain('https://www.gmail.com/inbox') // → true
+isGenericWebsiteDomain('https://acme.com')            // → false
+```
+
+> **Typical use case:** Gate B2B sign-up flows or lead enrichment pipelines by rejecting personal email addresses — ensuring only corporate domains are accepted for company-linked records.

package/src/utils/.image-proxy.md

@@ -1,32 +1,68 @@
-<!-- source-hash: a3e23fbda2c4277896e5630ca901a462 -->
-A utility module for handling image URL proxying and responsive image sizing in web applications.
+<!-- source-hash: 96c8aeb6b887afbf8566d95db7ee4847 -->
+Pure utility module for building image proxy URLs and related image-loading helpers, with no side effects or environment dependencies.
 
 ## Key Components
 
-- **`getProxiedImageUrl(url: string): string`** - Returns a proxied version of the image URL (currently a pass-through implementation)
-- **`generateImageSizes(url: string): string`** - Generates responsive image size attributes for optimal loading across different viewport widths
+| Export | Type | Description |
+|--------|------|-------------|
+| `GetProxiedImageUrlOptions` | Type | Configuration shape for proxy prefix, skip domains, and direct-HTTPS bypass |
+| `getProxiedImageUrl` | Function | Core URL resolver — routes an image URL through the proxy or returns it unchanged based on resolution rules |
+| `urlPathLooksLikeSvg` | Function | Heuristic check for `.svg` file extension in a URL path |
+| `shouldProxyImage` | Function | Boolean guard indicating whether a URL requires proxying |
+| `generateImageSizes` | Function | Returns a standard responsive `sizes` attribute string for `<img>` tags |
+
+## Resolution Order (`getProxiedImageUrl`)
+
+```mermaid
+graph TD
+    A["imageUrl input"] --> B{"Already contains proxyPrefix?"}
+    B -- Yes --> C["Return unchanged (self-skip)"]
+    B -- No --> D{"Relative / data: / blob:?"}
+    D -- Yes --> E["Return unchanged"]
+    D -- No --> F{"directHttps + starts with https://?"}
+    F -- Yes --> G["Return unchanged"]
+    F -- No --> H{"proxyPrefix unset?"}
+    H -- Yes --> I["Return unchanged"]
+    H -- No --> J{"Matches skipDomains?"}
+    J -- Yes --> K["Return unchanged"]
+    J -- No --> L["Return proxyPrefix?url=encoded"]
+```
 
 ## Usage Example
 
 ```typescript
-import { getProxiedImageUrl, generateImageSizes } from './image-proxy'
-
-// Get proxied image URL
-const originalUrl = 'https://example.com/image.jpg'
-const proxiedUrl = getProxiedImageUrl(originalUrl)
-
-// Generate responsive sizes for img element
-const sizes = generateImageSizes(originalUrl)
-
-// Use in HTML img element
-const imgElement = `
-  <img 
-    src="${proxiedUrl}" 
-    sizes="${sizes}"
-    alt="Responsive image"
-  />
-`
-// Result sizes: "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+import {
+  getProxiedImageUrl,
+  urlPathLooksLikeSvg,
+  shouldProxyImage,
+} from './image-proxy';
+
+const proxyPrefix = '/api/image-proxy';
+const skipDomains = ['cdn.mycompany.com'];
+
+// Standard proxy wrap
+getProxiedImageUrl('https://external.com/photo.jpg', { proxyPrefix, skipDomains });
+// → '/api/image-proxy?url=https%3A%2F%2Fexternal.com%2Fphoto.jpg'
+
+// Skip proxy for own CDN
+getProxiedImageUrl('https://cdn.mycompany.com/logo.png', { proxyPrefix, skipDomains });
+// → 'https://cdn.mycompany.com/logo.png'
+
+// Bypass proxy for SVGs only
+const url = 'https://external.com/icon.svg';
+getProxiedImageUrl(url, {
+  proxyPrefix,
+  directHttps: urlPathLooksLikeSvg(url), // true → bypass
+});
+// → 'https://external.com/icon.svg'
+
+// Guard before proxying
+shouldProxyImage('https://external.com/img.png', proxyPrefix); // → true
+shouldProxyImage('/relative/path.png', proxyPrefix);            // → false
 ```
 
-The `getProxiedImageUrl` function is designed as a placeholder for future image proxy implementation, while `generateImageSizes` provides a mobile-first responsive sizing strategy where images take full width on mobile devices, half width on tablets, and one-third width on desktop screens.
+## Notes
+
+- **Caller-owned config** — no env reads; proxy prefix and skip list are passed in at the call site, typically from `ChatRuntime.endpoints.imageProxyUrlPrefix`.
+- **HTTP stays proxied** even when `directHttps: true` to avoid mixed-content issues.
+- Relative URLs, `data:`, and `blob:` URIs always pass through unchanged.

package/src/utils/.index.md

@@ -1,56 +1,49 @@
-<!-- source-hash: b234713efcc25b611bb99fa454537cfb -->
-Central utility exports module providing client-side helper functions and type definitions for the Flamingo platform. This barrel export file aggregates commonly used utilities across different categories.
+<!-- source-hash: a199bfb2e9675c73161c9b56f81904f7 -->
+Barrel export index for the `utils` package, re-exporting all utility functions, types, and constants from their canonical source files to provide a single stable import path for consumers across the frontend library and hub.
 
 ## Key Components
 
-### **Core Utilities**
-- `cn` - Class name utility for conditional styling
-- `formatDate`, `formatNumber`, `formatPrice`, `formatBytes` - Data formatting functions
-- `getAllPlatformBaseDomains` - Platform domain configuration helper
-- `getBaseUrl` - Base URL resolution utility
-
-### **Platform & Color Management**
-- `getPlatformAccentColor`, `getCurrentPlatform` - Platform detection and theming
-- `ColorCategory` - TypeScript type for color categorization
-- Platform configuration exports from `./platform-config`
-- OS platform utilities from `./os-platforms`
-
-### **Helper Functions**
-- `delay` - Async delay utility
-- `generateRandomString`, `truncateString` - String manipulation
-- `deepClone` - Object cloning utility
-- `getSlackCommunityJoinUrl` - Community integration helper
-
-### **Specialized Modules**
-- Access code client utilities
-- Validation helpers
-- AI confidence scoring
-- Date/time formatting
-- Dynamic icon registry
-- Tool, shell, and OS type utilities
+| Export Group | Source | Description |
+|---|---|---|
+| `cn`, `getAllPlatformBaseDomains`, `getBaseUrl`, `getPlatformProductionUrl` | `./cn` | CSS class merging and platform URL helpers |
+| `formatDate`, `formatNumber`, `formatPrice`, `formatBytes`, `formatCurrency`, `formatPercent`, etc. | `./format` | Number, currency, byte, date, and metric formatters |
+| `getPlatformAccentColor`, `getCurrentPlatform` | `./ods-color-utils` | Platform theming and color utilities |
+| `getDynamicIcon`, `ICON_REGISTRY`, `getIconComponent` | `chat/utils/icon-registry` | Dynamic icon registry |
+| `embedAuthedFetch`, `getEmbedProxyAuth`, `setEmbedProxyAuth` | `./embed-*` | Embed-surface authentication helpers |
+| `formatRelativeTime`, `formatAbsoluteDate`, `isToday`, `createUTCTimestamp` | `./date-utils` | Date/time formatting and comparison |
+| `escapeMarkdownInline`, `buildChatAttachmentViewUrl` | `chat/utils/chat-attachment-markdown` | Chat attachment markdown helpers |
+| `scrollElementIntoView` | `./scroll-into-view` | Smooth scroll with sticky-chrome offset |
+| `readLeadingDecisionFrame` | `./sse-decision-frame` | SSE frame reader for confirm-tool route |
+| `isCrossOriginUrl` | `chat/utils/is-cross-origin-url` | Cross-origin URL detection (server-safe) |
 
 ## Usage Example
 
 ```typescript
-import { 
-  cn, 
-  formatPrice, 
-  getPlatformAccentColor, 
-  delay 
-} from '@/utils'
-
-// Conditional styling
-const buttonClass = cn('btn', {
-  'btn-primary': isPrimary,
-  'btn-disabled': isDisabled
-})
-
-// Format currency
-const price = formatPrice(29.99, 'USD')
-
-// Get platform theme color
-const accentColor = getPlatformAccentColor('flamingo')
-
-// Async delay
-await delay(1000)
-```
+// Import any utility directly from the utils barrel
+import {
+  cn,
+  formatCurrency,
+  formatRelativeTime,
+  getDynamicIcon,
+  getEmbedProxyAuth,
+  scrollElementIntoView,
+  getCurrentPlatform,
+} from '@flamingo-stack/openframe-frontend-core/utils'
+
+// CSS class merging
+const className = cn('base-class', isActive && 'active')
+
+// Format a currency value
+const price = formatCurrency(4999, 'USD') // "$49.99"
+
+// Relative time display
+const label = formatRelativeTime(new Date('2024-01-01')) // "6 months ago"
+
+// Retrieve embed proxy auth for non-chat surfaces
+const auth = getEmbedProxyAuth()
+
+// Scroll an element into view respecting sticky chrome
+scrollElementIntoView(targetElement, { offsetPx: 64 })
+```
+
+> **Note:** Several exports are intentionally re-routed through this barrel to keep server-safe utilities (e.g. `CUSTOM_ITEM_ID`, `getSourceLabel`, `isCrossOriginUrl`) accessible from SSR/server code without crossing `"use client"` boundaries.

package/src/utils/.local-storage-adapter.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 68d691e94558097753faed6dd1e6e15f -->
+A typed Web Storage adapter factory that centralizes SSR-guarding, JSON serialization, quota-failure handling, and optional namespace partitioning for both `localStorage` and `sessionStorage`.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `WebStorageBackend` | Type | `'local' \| 'session'` — selects the storage backend |
+| `LocalStorageAdapter<T>` | Interface | Runtime API: `load()`, `save()`, `clear()`, `resolveKey()` |
+| `LocalStorageAdapterOptions<T>` | Interface | Configuration including `key`, `namespace`, `validate`, `logTag`, `backend` |
+| `createLocalStorageAdapter<T>()` | Function | Factory that returns a typed adapter instance |
+
+**Backend guidance:**
+- `'local'` (default) — persists across sessions; use for UI state, chat history, feature flags
+- `'session'` — clears on tab close; use for **any auth-adjacent value** (tokens, proxy credentials) to minimize XSS exfiltration window
+
+## Usage Example
+
+```typescript
+import { createLocalStorageAdapter } from './local-storage-adapter'
+
+interface ChatPrefs {
+  theme: 'light' | 'dark'
+  fontSize: number
+}
+
+// Basic persistent adapter
+const prefsAdapter = createLocalStorageAdapter<ChatPrefs>({
+  key: 'chat-prefs',
+  validate: (v): v is ChatPrefs =>
+    typeof v === 'object' && v !== null && 'theme' in v,
+  logTag: '[chat-prefs]',
+})
+
+prefsAdapter.save({ theme: 'dark', fontSize: 14 })
+const prefs = prefsAdapter.load() // ChatPrefs | null
+
+// Auth-adjacent value with session backend + dynamic namespace
+const tokenAdapter = createLocalStorageAdapter<string>({
+  key: 'bearer-token',
+  backend: 'session',
+  namespace: () => currentUser?.orgId ?? null,
+})
+
+tokenAdapter.save('eyJ...')
+tokenAdapter.resolveKey() // → "org-123.bearer-token"
+tokenAdapter.clear()
+```
+
+> **SSR safe:** All storage access is guarded against `window === undefined` and sandboxed-context throws (e.g. Safari private mode), returning `null` silently instead of crashing.

package/src/utils/.ods-color-utils.md

@@ -1,54 +1,71 @@
-<!-- source-hash: b216de0ab6478666f2528bc940971eea -->
-Provides runtime utilities for working with ODS (Open Design System) color tokens across multiple platforms. This module handles platform detection, theme switching, and color token management for dynamic theming in web applications.
+<!-- source-hash: 8d0a4e249109b10a270ca0755176abc6 -->
+Runtime utility library for working with ODS (OpenFrame Design System) color tokens, providing platform-aware theming, token lookup, CSS generation, and React integration helpers.
 
 ## Key Components
 
-**Core Functions:**
-- `getODSToken()` - Retrieves raw ODS token values by category, color, and variant
-- `getPlatformAccentColor()` - Gets CSS custom property for platform-specific accent colors
-- `getCurrentPlatform()` - Detects current platform from environment or DOM attributes
-- `switchPlatformTheme()` - Dynamically changes platform theme via CSS custom properties
-
-**Utility Functions:**
-- `tokenToTailwindClass()` - Converts ODS tokens to Tailwind CSS classes
-- `getTokensByCategory()` - Retrieves all tokens for a specific color category
-- `generatePlatformCSS()` - Creates CSS custom property declarations for platforms
-- `interpolateColors()` - Blends between two ODS color tokens with progress value
-
-**React Integration:**
-- `usePlatformColors()` - Hook providing platform-aware color utilities and theme controls
+| Export | Type | Description |
+|--------|------|-------------|
+| `Platform` | Type | Union of `'openmsp' \| 'openframe' \| 'flamingo'` |
+| `ColorCategory` | Type | Union of `'open' \| 'flamingo' \| 'system' \| 'attention'` |
+| `ColorVariant` | Type | Union of `'base' \| 'hover' \| 'active' \| 'focus' \| 'disabled'` |
+| `getODSToken` | Function | Looks up a raw token value by category, color name, and variant |
+| `getPlatformAccentColor` | Function | Returns the CSS variable for the current or specified platform's accent color |
+| `getCurrentPlatform` | Function | Resolves platform from DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var |
+| `switchPlatformTheme` | Function | Updates `data-app-type` on `<html>` and dispatches `platformThemeChanged` event |
+| `getSemanticColor` | Function | Reads a computed `--color-*` CSS property for a given platform |
+| `tokenToTailwindClass` | Function | Maps a semantic token key to its corresponding Tailwind utility class |
+| `getTokensByCategory` | Function | Returns all tokens matching a given `ColorCategory` prefix |
+| `isValidODSToken` | Function | Checks whether a token key exists in the ODS token map |
+| `getPlatformConfig` | Function | Returns a config object with accent color, theme type, and brand name |
+| `generatePlatformCSS` | Function | Builds a CSS block of custom property overrides for a platform |
+| `applyColorToken` | Function | Directly sets a CSS custom property on an `HTMLElement` |
+| `interpolateColors` | Function | Linearly interpolates between two hex ODS tokens by progress (0–1) |
+| `usePlatformColors` | Function | React-friendly helper returning platform config and token accessors |
+| `getReadableTextColor` | Function | Returns `#212121` or `#fafafa` based on Rec. 601 luminance of a hex color |
 
 ## Usage Example
 
 ```typescript
-import { 
-  getCurrentPlatform, 
-  getPlatformAccentColor, 
+import {
+  getCurrentPlatform,
+  getPlatformConfig,
   getODSToken,
-  switchPlatformTheme,
-  usePlatformColors 
+  tokenToTailwindClass,
+  interpolateColors,
+  getReadableTextColor,
+  usePlatformColors,
+  switchPlatformTheme
 } from './ods-color-utils';
 
-// Get platform-specific accent color
-const platform = getCurrentPlatform(); // 'openmsp' | 'openframe' | 'flamingo'
-const accentColor = getPlatformAccentColor(platform); // 'var(--ods-open-yellow-base)'
+// Resolve the active platform (SSR + CSR safe)
+const platform = getCurrentPlatform(); // 'openframe'
+
+// Get full platform configuration
+const config = getPlatformConfig(platform);
+// { platform: 'openframe', accentColor: 'var(--ods-open-yellow-base)',
+//   isDarkTheme: true, isLightTheme: false, brandName: 'OpenFrame' }
+
+// Look up a raw design token
+const tokenValue = getODSToken('system', 'greys-background', 'base');
 
-// Get specific ODS token
-const primaryButton = getODSToken('open', 'blue', 'hover');
+// Map a semantic token to a Tailwind class
+const twClass = tokenToTailwindClass('text-primary', 'text');
+// → 'text-ods-text-primary'
 
-// Switch theme dynamically
+// Interpolate between two hex tokens (e.g. for animations)
+const midColor = interpolateColors('open-yellow-base', 'flamingo-pink-base', 0.5);
+
+// Ensure readable text on a dynamic background
+const textColor = getReadableTextColor('#FFC008'); // → '#212121'
+
+// Switch platform at runtime (updates <html data-app-type> + fires event)
 switchPlatformTheme('flamingo');
 
 // React component usage
-function ThemeAwareComponent() {
-  const { accentColor, isDarkTheme, switchTheme } = usePlatformColors();
-  
-  return (
-    <div style={{ backgroundColor: accentColor }}>
-      <button onClick={() => switchTheme('openframe')}>
-        Switch to OpenFrame Theme
-      </button>
-    </div>
-  );
+function MyComponent() {
+  const { accentColor, isDarkTheme, getToken, switchTheme } = usePlatformColors();
+  return <div style={{ color: accentColor }}>{isDarkTheme ? 'Dark' : 'Light'}</div>;
 }
-```
+```
+
+> **Note:** `getSemanticColor` and `applyColorToken` are browser-only — they return `undefined` or no-op on the server. `switchPlatformTheme` cannot persist `process.env` changes in production; use it for UI-layer toggling only.

package/src/utils/.platform-config.md

@@ -1,37 +1,57 @@
-<!-- source-hash: ade60c17f20dfc7ddc717f3b7a4e1e24 -->
-A centralized configuration module that provides unified branding assets (icons, colors, names, descriptions) for all platforms in the Flamingo ecosystem including OpenFrame, OpenMSP, and various specialized hubs.
+<!-- source-hash: 744818572300c7f98b30a728467179eb -->
+Centralized configuration module for all platform branding assets and metadata across the Flamingo/OpenFrame ecosystem, providing icons, colors, display names, descriptions, and utility functions for consistent platform presentation.
 
 ## Key Components
 
-- **Platform Asset Maps**: Exports for `platformIcons`, `platformColors`, `platformDisplayNames`, `platformDescriptions`, `platformSlogans`, `platformHexColors`, and `platformIconNames`
-- **Utility Functions**: Helper functions `getDefaultColorForPlatform`, `getDefaultIconForPlatform`, `getPlatformIcon`, `getPlatformColor`, etc.
-- **Icon Components**: Specialized icon getters `getSmallPlatformIcon` (4x4) and `getPlatformIconComponent` (6x6) with platform-specific styling
-- **Data Transformation**: `transformPlatformConfigsToOptions` converts platform configs to selectable options
+### Lookup Maps (exported constants)
+
+| Export | Purpose |
+|--------|---------|
+| `platformIcons` | React icon components keyed by platform name |
+| `platformColors` | Tailwind `bg-*` class strings per platform |
+| `platformDisplayNames` | Human-readable names (e.g., `"Flamingo Marketing Hub"`) |
+| `platformDescriptions` | Full marketing copy per platform |
+| `platformSlogans` | Short taglines for branding use |
+| `platformHexColors` | Raw hex values for non-Tailwind contexts |
+| `platformIconNames` | String icon identifiers for config serialization |
+
+Supported platform keys: `openframe`, `openmsp`, `flamingo`, `flamingo-teaser`, `marketing-hub`, `product-hub`, `revenue-hub`, `people-hub`, `company-hub`, `tmcg`, `universal`
+
+### Utility Functions
+
+| Function | Returns | Notes |
+|----------|---------|-------|
+| `getPlatformIcon(name)` | `React.ReactNode` | Falls back to `universal` Globe icon |
+| `getPlatformColor(name)` | `string` | Tailwind `bg-*` class |
+| `getPlatformDisplayName(name)` | `string` | Falls back to raw name |
+| `getPlatformDescription(name)` | `string` | Falls back to raw name |
+| `getPlatformSlogan(name)` | `string` | Falls back to raw name |
+| `getDefaultColorForPlatform(name)` | `string` | Hex value, falls back to `universal` |
+| `getDefaultIconForPlatform(name)` | `string` | Icon name string, falls back to `universal` |
+| `getSmallPlatformIcon(name)` | `React.ReactNode` | 4×4 (`h-4 w-4`), uses CSS variables for hub variants |
+| `getPlatformIconComponent(name, className?)` | `React.ReactNode` | 6×6 default, accepts custom `className` |
+| `transformPlatformConfigsToOptions(configs)` | `SelectableOption[]` | Maps `PlatformConfig[]` to UI-selectable options with icon and color |
 
 ## Usage Example
 
 ```typescript
-import { 
-  getPlatformIcon, 
-  getPlatformColor, 
+import {
   getPlatformDisplayName,
-  getSmallPlatformIcon 
+  getPlatformColor,
+  getSmallPlatformIcon,
+  transformPlatformConfigsToOptions
 } from './platform-config';
 
-// Get platform assets
-const flamingoIcon = getPlatformIcon('flamingo');
-const openFrameColor = getPlatformColor('openframe'); // 'bg-[#8B5CF6]'
-const displayName = getPlatformDisplayName('openmsp'); // 'OpenMSP'
-
-// Use in components
-function PlatformSelector({ platformName }: { platformName: string }) {
-  return (
-    <div className={getPlatformColor(platformName)}>
-      {getSmallPlatformIcon(platformName)}
-      <span>{getPlatformDisplayName(platformName)}</span>
-    </div>
-  );
-}
+// Render a platform badge
+const PlatformBadge = ({ name }: { name: string }) => (
+  <span className={`px-2 py-1 rounded ${getPlatformColor(name)}`}>
+    {getSmallPlatformIcon(name)}
+    {getPlatformDisplayName(name)}
+  </span>
+);
+
+// Populate a platform selector dropdown
+const options = transformPlatformConfigsToOptions(platformConfigs);
 ```
 
-The module ensures consistent branding across the entire platform by centralizing all visual and textual representations of each service in the Flamingo stack.
+> All lookup functions fall back gracefully to the `universal` platform or the raw input string, so unknown platform keys never produce `undefined` in UI renders.

package/src/utils/.scroll-into-view.md

@@ -0,0 +1,40 @@
+<!-- source-hash: ec93c3a6544d7f572c8219bc65ceaf67 -->
+Smooth-scroll utility that positions an element at the top of the viewport with support for sticky header offsets and pre-computed layout-shift adjustments.
+
+## Key Components
+
+### `ScrollElementIntoViewOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `headerOffset` | `number` | `0` | Pixels to subtract for sticky chrome (e.g., `96` for `scroll-mt-24`) |
+| `behavior` | `ScrollBehavior` | `'smooth'` | `'smooth'` for animated scrolls, `'instant'` for deep-link jumps |
+| `adjustTargetY` | `(raw: number) => number` | — | Callback to correct the pixel target before animation starts |
+
+### `scrollElementIntoView(target, options?)`
+
+Computes a fixed pixel target via `getBoundingClientRect().top + scrollY - headerOffset`, then calls `window.scrollTo()` directly. This avoids the jitter caused by `element.scrollIntoView()`, which re-targets continuously during layout shifts. Handles `null`/`undefined` refs as a no-op and short-circuits in SSR environments.
+
+## Usage Example
+
+```typescript
+import { scrollElementIntoView } from './scroll-into-view'
+
+// Basic — scroll a ref to top, accounting for a 96px sticky header
+scrollElementIntoView(cardRef.current, { headerOffset: 96 })
+
+// Instant jump on deep-link land
+scrollElementIntoView(anchorRef.current, {
+  headerOffset: 96,
+  behavior: 'instant',
+})
+
+// Pre-computed layout-shift adjustment (e.g. HelpCenterCard accordion)
+// Row A (above target) collapses simultaneously — shift target up by A's height
+scrollElementIntoView(rowBRef.current, {
+  headerOffset: 96,
+  adjustTargetY: (raw) => raw - getAboveDrawerHeight(),
+})
+```
+
+> **Why not `element.scrollIntoView()`?** That API re-targets continuously as the page reflows during the animation, causing visible jitter when sibling content is also moving. Pre-computing a fixed pixel value lets the browser commit to a clean, uninterrupted animation.

package/src/utils/.source-icons.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 4129d05ad3798983504dba26d6153a8c -->
+Maps RAG table IDs to their display icons, human-readable labels, and document type lookups for the OpenFrame chat source chip system. Server-safe with no client-only imports.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `SOURCE_ICON_NAMES` | `Record<string, string>` | Maps `RagTableConfig.id` → icon name string (resolved to React components via `icon-registry.ts`) |
+| `SOURCE_LABELS_BY_TABLE` | `Record<string, string>` | Maps `RagTableConfig.id` → human-readable display label used in chat source chips |
+| `DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID` | `Record<string, string>` | Reverse maps LLM-emitted `documentType` strings → `RagTableConfig.id` |
+| `getSourceIconName()` | Function | Safe lookup returning `undefined` for unknown table IDs |
+| `getSourceLabel()` | Function | Lookup with fallback to raw table slug when no label is registered |
+| `defaultTableIdForDocumentType()` | Function | Default resolver for `useEmbeddedChat` when no custom callback is provided; returns `null` for unknown types |
+
+## Usage Example
+
+```typescript
+import {
+  getSourceIconName,
+  getSourceLabel,
+  defaultTableIdForDocumentType,
+} from '@/utils/source-icons'
+
+// Resolve icon name for a known RAG table
+const iconName = getSourceIconName('github-commits')
+// → 'github'
+
+// Get display label for a chip strip
+const label = getSourceLabel('hubspot-tickets-anon')
+// → 'Known Issues'
+
+// Map a documentType emitted by the LLM to its table ID
+const tableId = defaultTableIdForDocumentType('slack_message')
+// → 'slack-messages'
+
+// Graceful handling of unknown types
+const unknown = defaultTableIdForDocumentType('custom_type')
+// → null
+```
+
+## Supported Source Categories
+
+| Category | Tables Covered |
+|----------|---------------|
+| **Docs** | `openframe-docs`, `data-room-docs` |
+| **CMS / Programs** | Blog posts, releases, case studies, webinars, events, podcasts, interviews |
+| **Financials** | KPIs, cap table, P&L, balance sheet, cash flow, investor updates |
+| **ClickUp** | Roadmap, delivery, internal tasks |
+| **GitHub** | Commits, PRs, PR reviews (public + internal variants) |
+| **HubSpot** | Tickets (full, anon, self) |
+| **Communications** | Slack messages |
+
+> **Design note:** Icon names are intentionally decoupled from React components — the resolver (`icon-registry.ts`) stays client-only while this file remains server-safe, allowing hub-side RAG mappers and chat route handlers to call these utilities directly.

package/src/utils/.sse-decision-frame.md

@@ -0,0 +1,46 @@
+<!-- source-hash: ca8aad98b81a1dbccc525ac143c34ff1 -->
+Shared decoder for the `decision_resolved` leading frame emitted by the `confirm-tool` SSE route. Parses the first NUL-delimited JSON chunk from the stream, drains remaining bytes to avoid half-closed socket hangs, and returns a typed `DecisionResolvedFrame`.
+
+## Key Components
+
+### `DecisionResolvedFrame` (interface)
+Typed shape of the leading SSE frame returned by `confirm-tool/route.ts`. Key fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | `'decision_resolved'` | Frame discriminator |
+| `ok` | `boolean` | Whether the operation succeeded |
+| `action` | `'approved' \| 'rejected'` | Tool confirmation outcome |
+| `willAutoContinue` | `boolean?` | Auto-continue flag post-approval |
+| `result` | `object?` | Approve-path envelope; `mirror_synced: false` means HubSpot succeeded but local mirror lagged — callers should optimistic-render and schedule a delayed refetch |
+| `card` | `object?` | UI card metadata |
+| `receiptText` | `string?` | Human-readable receipt |
+
+### `readLeadingDecisionFrame(response)` (async function)
+Reads and decodes the first `decision_resolved` frame from a `confirm-tool` SSE `Response`. Drains the full stream before resolving. Throws if the body is empty, the first frame is not `decision_resolved`, or the leading JSON is malformed.
+
+### `normalizeDecisionFrame(obj)` (internal)
+Safely casts a raw parsed object into a `DecisionResolvedFrame`, applying defaults and conditional spreads for optional fields.
+
+## Usage Example
+
+```typescript
+const response = await fetch('/api/confirm-tool', {
+  method: 'POST',
+  body: JSON.stringify({ proposalId: 'prop_123' }),
+})
+
+const frame = await readLeadingDecisionFrame(response)
+
+if (!frame.ok || frame.action === 'rejected') {
+  console.warn('Tool rejected:', frame.receiptText)
+  return
+}
+
+if (frame.result?.mirror_synced === false) {
+  // HubSpot succeeded but mirror lagged — optimistic render + refetch
+  scheduleDelayedRefetch(frame.result.ticket_id)
+}
+```
+
+> **Protocol note:** The tickets-UI path sends `messages: []`, making the stream a single `decision_resolved` frame followed by EOF. The `\x1E` record-separator sentinel (phase-2 text body) is structurally unreachable in this path — its presence before `\0` is treated as a protocol violation and throws.