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

package/src/types/.waitlist.md

@@ -1,46 +1,50 @@
-<!-- source-hash: 08e89e89864ea45d66eb024c149b3933 -->
-A TypeScript interface definition for waitlist entry management with HubSpot integration and cohort tracking capabilities. Defines the data structures for collecting user signups with comprehensive metadata tracking and CRM synchronization.
+<!-- source-hash: f7e2eb6ca28207daca5b3bc5bf7ad178 -->
+Defines TypeScript interfaces for managing waitlist entries in the Flamingo/OpenFrame platform, covering creation, retrieval, and API response shapes.
 
 ## Key Components
 
-- **`WaitlistEntry`** - Complete waitlist entry interface with all fields including HubSpot integration metadata, platform relationships, and cohort membership data
-- **`CreateWaitlistEntry`** - Input interface for creating new waitlist entries with required and optional user data plus tracking fields
-- **`WaitlistResponse`** - API response wrapper interface with success/error handling and optional data payload
+| Interface | Description |
+|-----------|-------------|
+| `WaitlistEntry` | Full waitlist record as returned from the database, including tracking, HubSpot integration metadata, enriched data, and cohort membership |
+| `CreateWaitlistEntry` | Payload shape for submitting a new waitlist entry (subset of `WaitlistEntry`, no server-generated fields) |
+| `WaitlistResponse` | Standard API response wrapper with `success` flag, optional `data`, and optional `error` |
 
 ## Usage Example
 
 ```typescript
-// Creating a new waitlist entry
-const newEntry: CreateWaitlistEntry = {
-  email: "user@example.com",
-  name: "John Doe",
-  company: "Acme Corp",
-  platform_id: "platform-123",
-  referral_source: "google",
-  utm_source: "newsletter",
-  utm_campaign: "launch2024",
-  ip_address: "192.168.1.1",
-  user_agent: "Mozilla/5.0..."
+import type {
+  WaitlistEntry,
+  CreateWaitlistEntry,
+  WaitlistResponse,
+} from './waitlist';
+
+// Submitting a new waitlist signup
+const payload: CreateWaitlistEntry = {
+  email: 'dev@example.com',
+  name: 'Jane Dev',
+  company: 'Acme MSP',
+  platform_id: 'openframe',
+  referral_source: 'organic',
+  utm_source: 'google',
+  utm_medium: 'cpc',
+  utm_campaign: 'launch-2025',
 };
 
-// API response structure
-const response: WaitlistResponse = {
-  success: true,
-  data: {
-    id: "entry-456",
-    email: "user@example.com",
-    platform_id: "platform-123",
-    created_at: "2024-01-15T10:00:00Z",
-    updated_at: "2024-01-15T10:00:00Z",
-    hubspot_sync_status: "success",
-    cohort: {
-      cohort_id: "cohort-789",
-      cohort_name: "Beta Launch",
-      access_code: "BETA2024",
-      access_code_used: false,
-      membership_status: "active",
-      // ...other cohort fields
-    }
+// Handling the API response
+const response: WaitlistResponse = await submitWaitlist(payload);
+
+if (response.success && response.data) {
+  const entry: WaitlistEntry = response.data;
+
+  // Access HubSpot sync status
+  console.log(entry.hubspot_sync_status); // 'success' | 'error' | 'missing' | null
+
+  // Access enriched cohort info (server-side populated)
+  if (entry.cohort) {
+    console.log(entry.cohort.cohort_name);
+    console.log(entry.cohort.access_code_used);
   }
-};
-```
+}
+```
+
+> **Note:** `WaitlistEntry.cohort_memberships` may contain multiple records from the join, but business rules enforce a maximum of one active cohort per entry. Use the server-populated `cohort` shorthand field for clean access.

package/src/utils/.access-code-client.md

@@ -1,45 +1,46 @@
-<!-- source-hash: 94c99ad03b1be8fa4d35c9872f47a823 -->
-Client-side utilities for integrating access code validation and consumption into registration forms, providing both standalone functions and a React hook for seamless user registration workflows.
+<!-- source-hash: 1d5aefc0169fc550dd115556a5cdbf7e -->
+Pure standalone utility functions for validating and consuming access codes via HTTP, designed to be React-free and SSR-safe by requiring explicit endpoint URLs rather than reading from context.
 
 ## Key Components
 
-- **validateAccessCode** - Validates an access code against a user's email
-- **consumeAccessCode** - Marks an access code as used after successful registration
-- **validateAndConsumeAccessCode** - Convenience function combining validation and consumption
-- **useAccessCodeIntegration** - React hook with loading states for form integration
+### `AccessCodeEndpoints` (interface)
+Defines the two endpoint URLs required by all client functions:
+- `validateUrl` — POST endpoint for code validation
+- `consumeUrl` — POST endpoint for code consumption
+
+### `validateAccessCode(email, code, endpoints)`
+POSTs credentials to `validateUrl` and returns an `AccessCodeValidationResponse`. On HTTP or network errors, returns `{ valid: false, message }` rather than throwing.
+
+### `consumeAccessCode(email, code, endpoints)`
+POSTs credentials to `consumeUrl` to mark a code as used. Should only be called **after** successful registration. On failure returns `{ success: false, consumed: false, message }`.
+
+### `validateAndConsumeAccessCode(email, code, endpoints)`
+Convenience wrapper that sequentially calls validate → consume. Short-circuits and returns the validation failure immediately if the code is invalid. Returns a merged `AccessCodeValidationResponse & { consumed? }`.
 
 ## Usage Example
 
 ```typescript
-import { validateAccessCode, consumeAccessCode, useAccessCodeIntegration } from './access-code-client';
-
-// Standalone validation
-const validation = await validateAccessCode('user@example.com', 'ABC123XY');
-if (validation.valid) {
-  console.log(`Welcome to ${validation.cohort_name}!`);
-  
-  // After successful registration, consume the code
-  await consumeAccessCode('user@example.com', 'ABC123XY');
-}
+import {
+  validateAndConsumeAccessCode,
+  AccessCodeEndpoints
+} from './access-code-client';
 
-// React component integration
-function RegistrationForm() {
-  const { validate, consume, isValidating } = useAccessCodeIntegration();
-  
-  const handleSubmit = async (formData) => {
-    const result = await validate(formData.email, formData.accessCode);
-    if (result.valid) {
-      // Process registration, then consume code
-      await registerUser(formData);
-      await consume(formData.email, formData.accessCode);
-    }
-  };
-  
-  return (
-    <form onSubmit={handleSubmit}>
-      {/* form fields */}
-      <button disabled={isValidating}>Register</button>
-    </form>
-  );
+const endpoints: AccessCodeEndpoints = {
+  validateUrl: '/api/access-codes/validate',
+  consumeUrl: '/api/access-codes/consume',
+};
+
+const result = await validateAndConsumeAccessCode(
+  'user@example.com',
+  'ABC123XY',
+  endpoints,
+);
+
+if (result.valid && result.consumed) {
+  console.log(`Welcome to ${result.cohort_name}!`);
+} else {
+  console.error(result.message);
 }
-```
+```
+
+> **Note:** Endpoint binding from `EndpointsRuntimeContext` is handled by the React-side hook `hooks/use-access-code-integration.ts` (`useAccessCodeIntegration`). Keeping this file React-free allows it to be safely bundled in the server-side `utils/index` tsup build without crashing SSR.

package/src/utils/.cn.md

@@ -1,36 +1,44 @@
-<!-- source-hash: 567d16aaedd1c7358dff3eda50893349 -->
-A utility module providing class name merging, formatting functions, and platform URL management for the Flamingo/OpenMSP ecosystem.
+<!-- source-hash: c1693a304ddf9b29bde0ca02b6f6b8ea -->
+Utility module providing class name merging with extended Tailwind support, and platform URL resolution helpers for multi-tenant Flamingo/OpenFrame deployments.
 
 ## Key Components
 
-- **`cn(...inputs)`** - Combines and merges Tailwind CSS class names using clsx and tailwind-merge
-- **`formatDate(date, options)`** - Formats dates to human-readable strings with validation
-- **`formatNumber(num)`** - Adds thousands separators to numbers
-- **`formatPrice(price, currency)`** - Formats prices with currency symbols
-- **`formatBytes(bytes, decimals)`** - Converts bytes to human-readable sizes (KB, MB, GB, etc.)
-- **`getBaseUrl(platform?)`** - Gets application base URLs with environment-specific logic
-- **`getAllPlatformBaseDomains()`** - Extracts all unique base domains for cross-platform cookie sharing
-- **`getPlatformProductionUrl(platform)`** - Maps platform identifiers to their production URLs
+| Export | Type | Description |
+|--------|------|-------------|
+| `cn` | Function | Merges class names using `clsx` + `tailwind-merge`, extended with custom ODS typography classes (`text-h1`–`text-h6`) |
+| `getPlatformProductionUrl` | Function | Returns the production URL for a named platform, with `NEXT_PUBLIC_*` env var override support |
+| `getAllPlatformBaseDomains` | Function | Extracts all unique base domains across platforms; handles localhost, Vercel preview, and production cases (useful for cross-domain cookie scope) |
+| `getBaseUrl` | Function | Resolves the current app's base URL using a priority chain: env override → platform URL → Vercel domain → production fallback → `localhost:3000` |
 
 ## Usage Example
 
 ```typescript
-import { cn, formatDate, formatBytes, getBaseUrl } from './cn'
+import { cn, getBaseUrl, getPlatformProductionUrl, getAllPlatformBaseDomains } from '@/lib/cn'
 
-// Merge CSS classes with Tailwind conflict resolution
-const buttonClass = cn('px-4 py-2', 'px-6', 'bg-blue-500', { 'bg-red-500': isError })
+// Merge Tailwind classes (including custom ODS typography)
+const className = cn('text-h1 font-bold', isActive && 'text-yellow-400')
 
-// Format various data types
-const displayDate = formatDate(new Date(), { month: 'short', day: 'numeric' })
-const fileSize = formatBytes(1024000) // "1000 KB"
-const price = formatPrice(99.99, 'USD') // "$99.99"
+// Resolve current app base URL
+const apiBase = getBaseUrl()                      // http://localhost:3000 (dev)
+                                                  // https://www.openmsp.ai (prod fallback)
 
-// Get platform URLs
-const flamingoUrl = getBaseUrl('flamingo') // https://flamingo.run (prod) or localhost (dev)
-const currentUrl = getBaseUrl() // Current app's base URL
+// Resolve a specific platform URL (respects NEXT_PUBLIC_* overrides)
+const flamingoUrl = getBaseUrl('flamingo')        // https://www.flamingo.run
+const openframeUrl = getPlatformProductionUrl('openframe') // https://openframe.ai
 
-// Get all domains for cookie configuration
-const domains = getAllPlatformBaseDomains() // ['.flamingo.so', 'flamingo.so', ...]
+// Get all cookie-scoped base domains (e.g. for document.cookie domain=)
+const domains = getAllPlatformBaseDomains()
+// Production: ['.flamingo.run', 'flamingo.run', '.openmsp.ai', 'openmsp.ai', ...]
+// Vercel preview: ['.vercel.app', 'vercel.app']
+// Localhost: []
 ```
 
-The module handles environment detection, supports Vercel deployments, and provides consistent URL resolution across the Flamingo platform ecosystem including OpenMSP, Flamingo, TMCG, and OpenFrame applications.
+## Environment Variables
+
+| Variable | Platform | Default |
+|----------|----------|---------|
+| `NEXT_PUBLIC_FLAMINGO_URL` | `flamingo`, `universal` | `https://www.flamingo.run` |
+| `NEXT_PUBLIC_OPENMSP_URL` | `openmsp` | `https://www.openmsp.ai` |
+| `NEXT_PUBLIC_OPENFRAME_URL` | `openframe` | `https://openframe.ai` |
+| `NEXT_PUBLIC_MARKETING_HUB_URL` | `marketing-hub` | `https://marketing-hub.flamingo.so` |
+| `NEXT_PUBLIC_DEV_URL` | all (dev only) | `http://localhost:3000` |

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

@@ -0,0 +1,35 @@
+<!-- source-hash: 320c7ab088203622f31bd929824e3767 -->
+Provides color analysis utilities for extracting dominant colors from images and selecting accessible contrast colors from the Flamingo design palette, primarily used for dynamic badge and card styling.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ColorPalette` | Interface | Color descriptor with `name`, `hex`, and `rgb` tuple |
+| `DESIGN_PALETTE` | Constant | Three-color palette: yellow `#FFC008`, black `#161616`, gray `#888888` |
+| `hexToRgb` | Function | Converts a hex string to an RGB tuple |
+| `getContrastRatio` | Function | Returns WCAG contrast ratio between two RGB colors |
+| `extractDominantColor` | Function | Samples a canvas to find the most frequent bucketed color |
+| `getBestContrastColor` | Function | Picks the palette color with highest contrast (≥ 3:1 minimum) |
+| `analyzeImageColor` | Function | Loads an image URL, extracts dominant color, returns best palette match |
+| `extractImageEdgeColorAsync` | Function | Samples edge pixels of an image and returns the dominant hex color for background fills |
+
+## Usage Example
+
+```typescript
+import { analyzeImageColor, extractImageEdgeColorAsync, getContrastRatio, hexToRgb } from './color-analysis';
+
+// Get the best badge text color for a logo image
+const badgeColor = await analyzeImageColor('https://example.com/logo.png');
+console.log(badgeColor.hex); // '#161616'
+
+// Extract edge color for email/card background fill
+const bgColor = await extractImageEdgeColorAsync('https://example.com/hero.jpg');
+console.log(bgColor); // '#1a2b3c'
+
+// Manual contrast check between two hex colors
+const ratio = getContrastRatio(hexToRgb('#FFC008'), hexToRgb('#161616'));
+console.log(ratio); // ~11.5 (passes WCAG AA and AAA)
+```
+
+> **Note:** `extractDominantColor` and `analyzeImageColor` are client-side only and require `document`/`canvas` APIs. `extractImageEdgeColorAsync` also guards against SSR with a `typeof window` check, resolving to `#000000` on the server.

package/src/utils/.country-phone-utils.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 2a8a74c3b98ef6150c8b43768d8c2035 -->
+Utility module for working with international phone numbers and country data, combining `libphonenumber-js` metadata with the `Intl.DisplayNames` API to provide country selection, validation, and formatting helpers.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `CountryPhoneData` | Interface | Shape of a country entry: ISO code, display name, dial code, and flag emoji |
+| `getCountryPhoneData()` | Function | Returns all countries split into `priority` (US, CA, GB, AU) and `others` (alphabetically sorted), lazily cached |
+| `getCountryByCode(code)` | Function | Looks up a single `CountryPhoneData` entry by ISO 3166-1 alpha-2 code |
+| `validatePhoneNumber(phone, code)` | Function | Returns `true` if the number is valid for the given country (empty strings pass as optional) |
+| `formatPhoneE164(phone, code)` | Function | Formats a number to E.164 (e.g., `+14155552671`), falling back to digit-only concatenation on parse failure |
+
+## Usage Example
+
+```typescript
+import {
+  getCountryPhoneData,
+  getCountryByCode,
+  validatePhoneNumber,
+  formatPhoneE164,
+} from './country-phone-utils'
+
+// Populate a country selector
+const { priority, others } = getCountryPhoneData()
+// priority → [{ code: 'US', name: 'United States', dialCode: '+1', flag: '🇺🇸' }, ...]
+
+// Look up a specific country
+const canada = getCountryByCode('CA')
+// → { code: 'CA', name: 'Canada', dialCode: '+1', flag: '🇨🇦' }
+
+// Validate user input
+const isValid = validatePhoneNumber('(415) 555-2671', 'US') // true
+
+// Normalize to E.164 before storing/sending
+const e164 = formatPhoneE164('(415) 555-2671', 'US') // '+14155552671'
+```
+
+> **Note:** `getCountryPhoneData()` builds and caches the full country list on first call. Priority countries (US, CA, GB, AU) are always surfaced at the top of the list, making them convenient as default options in phone-number input components.

package/src/utils/.date-formatters.md

@@ -1,27 +1,28 @@
-<!-- source-hash: 4bb8e085097eb8f5246e47f5b9a36698 -->
-Provides centralized date formatting utilities to ensure consistent date display across the application while avoiding timezone-related issues.
+<!-- source-hash: bdbe45fc465896066574c96cffcccb6f -->
+Timezone-safe date formatting utilities providing a single source of truth for consistent date display across the application. All functions parse ISO date strings via string splitting to avoid `new Date()` UTC-to-local timezone shifts.
 
 ## Key Components
 
-- **`formatReleaseDate(dateString: string)`** - Formats ISO date strings into human-readable release dates without timezone shifts
+| Export | Output Example | Use Case |
+|--------|---------------|----------|
+| `formatReleaseDate` | `"November 11, 2025"` | Release dates, long-form display |
+| `formatDateShort` | `"Jan 5, 2025"` | Admin cards (waitlist, publication, media, investor, campaign) |
+| `formatDateSlashUTC` | `"11/11/2025"` | Product release & customer interview cards |
+
+**Internal helper:** `splitYmd(dateString)` — splits ISO date/datetime strings into `[year, month, day]` without constructing a `Date` object, preventing the off-by-one day bug west of UTC.
 
 ## Usage Example
 
 ```typescript
-import { formatReleaseDate } from './date-formatters';
-
-// Format a release date from API response
-const releaseDate = "2025-11-11T00:00:00Z";
-const formatted = formatReleaseDate(releaseDate);
-console.log(formatted); // "November 11, 2025"
-
-// Use in product release components
-const ProductRelease = ({ release }) => (
-  <div>
-    <h3>{release.name}</h3>
-    <p>Released: {formatReleaseDate(release.date)}</p>
-  </div>
-);
+import { formatReleaseDate, formatDateShort, formatDateSlashUTC } from './date-formatters'
+
+// ISO date-only string
+formatReleaseDate('2025-11-11')      // → "November 11, 2025"
+formatDateShort('2025-01-05')        // → "Jan 5, 2025"
+formatDateSlashUTC('2025-11-11')     // → "11/11/2025"
+
+// ISO datetime strings also work (time component is ignored)
+formatDateShort('2025-06-20T14:30:00Z')  // → "Jun 20, 2025"
 ```
 
-The utility manually parses date components to avoid JavaScript's automatic timezone conversions, ensuring release dates display consistently regardless of user location. Perfect for product release lists and detail pages where date accuracy is critical.
+> **Why not `new Date()`?** Passing `"2025-11-11"` to `new Date()` creates a UTC midnight timestamp. In timezones west of UTC, `.getMonth()` / `.getDate()` resolve to the *previous* day. String splitting eliminates this class of bug entirely.

package/src/utils/.embed-authed-fetch.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 585108e1683f75548fc4f177781fa0c8 -->
+A client-side `fetch` wrapper for embedded surfaces (chat, ticket center, widgets) that automatically attaches bearer-act-as proxy authentication headers from `sessionStorage` while enforcing same-origin security.
+
+## Key Components
+
+### `embedAuthedFetch(url, init?)`
+Drop-in replacement for `fetch()` that:
+- Normalizes `RequestInit.headers` (handles `Headers` instance, tuple arrays, or plain objects) into `Record<string, string>`
+- Delegates to `applyProxyAuth` to merge `Authorization` and `X-Chat-Act-As` headers — **proxy credentials always win** over caller-supplied headers
+- Defaults `Content-Type: application/json` when no headers are provided
+- Forces `credentials: 'same-origin'` to ensure Supabase auth cookies are included alongside bearer tokens
+
+### `assertSameOrigin(url)` *(internal)*
+Defense-in-depth guard that:
+- Resolves all URL forms (relative, absolute, protocol-relative, whitespace-prefixed) against `window.location.href` via the WHATWG `URL` constructor — bypasses regex shortcuts vulnerable to `\t`/`\n` prefix tricks
+- Blocks non-`http(s):` schemes explicitly (`javascript:`, `data:`, `blob:`, etc.)
+- Throws on cross-origin destinations before any bearer token leaves the page
+- Skips silently during SSR (`typeof window === 'undefined'`)
+
+## Usage Example
+
+```typescript
+// JSON POST to chat API — proxy headers attached automatically
+const res = await embedAuthedFetch('/api/chat/messages', {
+  method: 'POST',
+  body: JSON.stringify({ message: 'Hello' }),
+})
+
+// GET with explicit empty headers — skips Content-Type default
+const upload = await embedAuthedFetch('/api/storage/generate-upload-url', {
+  method: 'GET',
+  headers: {},
+})
+
+// Vanilla fetch — use for routes that don't need bearer-act-as
+const profile = await fetch('/api/profile/me', { credentials: 'same-origin' })
+```
+
+> Routes outside the `/api/chat/*`, `/api/docs/chat/*`, or `/api/storage/generate-upload-url` surfaces should use vanilla `fetch` — this wrapper is scoped to embedded auth contexts only.

package/src/utils/.embed-proxy-auth-storage.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 4f6996d4ad0ba284b64e13807891eb62 -->
+Manages client-side persistence of embed-surface proxy credentials (`CHAT_PROXY_SECRET` + impersonation email) in `localStorage`, enabling embedded surfaces (chat widget, ticket center, etc.) to authenticate as a proxied customer across sessions.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `EmbedProxyAuth` | Interface | Shape of persisted credentials: `secret`, `email`, and optional identity fields (`firstName`, `lastName`, `avatarUrl`) |
+| `getEmbedProxyAuth()` | Function | Returns full normalized credentials or `null` (falls back to cookie auth) |
+| `getPersistedProxyEmail()` | Function | Returns only the last saved email, used to pre-fill the creds bar on mount |
+| `setEmbedProxyAuth()` | Function | Persists credentials with normalization; trims/lowercases email, strips whitespace-only optional fields |
+| `clearEmbedProxyAuth()` | Function | Removes credentials from `localStorage` |
+| `applyProxyAuth()` | Function | Attaches `Authorization: Bearer` + `X-Chat-Act-As` (and optional identity headers) to any fetch call |
+
+Storage key `<appType>.chat.proxy-auth.v1` is intentionally frozen — renaming it would silently log out all existing admin sessions.
+
+## Usage Example
+
+```typescript
+import { setEmbedProxyAuth, applyProxyAuth, clearEmbedProxyAuth } from './embed-proxy-auth-storage'
+
+// Save credentials (e.g. from the /debug creds bar)
+setEmbedProxyAuth({
+  secret: 'my-proxy-secret',
+  email: 'customer@example.com',
+  firstName: 'Jane',
+  lastName: 'Doe',
+})
+
+// Apply to a fetch call — no-op when no creds are stored
+const { url, headers } = applyProxyAuth('/api/chat/stream')
+const response = await fetch(url, { method: 'POST', headers })
+
+// Admin logout / "Clear" button
+clearEmbedProxyAuth()
+```
+
+> **Security note:** Credentials persist in `localStorage` (survives tab close and browser restart). This is intentional — re-pasting on every tab was rejected as a dev-experience tradeoff. The `/debug` entry point is admin-gated, and all headers are server-validated against `CHAT_PROXY_SECRET`.

package/src/utils/.fetch-priority.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 786a6c83f7b7be019293590b300def02 -->
+Provides a React-version-aware helper that returns the correct prop shape for the HTML `fetchpriority` attribute, avoiding console warnings across React 18 and React 19+.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `FetchPriorityValue` | `type` | Union of valid HTML fetch-priority strings: `'high' \| 'low' \| 'auto'` |
+| `fetchPriorityProp()` | `function` | Returns `{ fetchpriority: value }` (React 18) or `{ fetchPriority: value }` (React 19+) |
+| `REACT_MAJOR` | internal `const` | Major version parsed from `React.version` at module load |
+| `USE_CAMEL_CASE_FETCH_PRIORITY` | internal `const` | `true` when React major ≥ 19 |
+
+## Behavior
+
+- **`undefined`** → resolves to `'auto'` (DOM default), safe to spread without null-checking at each callsite
+- **`true`** → `'high'` (intended for LCP candidates)
+- **`false`** → `'low'`
+- **`'high' | 'low' | 'auto'`** → passed through as-is
+
+## Usage Example
+
+```typescript
+import { fetchPriorityProp } from './fetch-priority';
+
+// Boolean shorthand — LCP hero image
+<img
+  src="/hero.jpg"
+  alt="Hero"
+  {...fetchPriorityProp(true)}   // React 18: { fetchpriority: "high" }
+                                 // React 19: { fetchPriority: "high" }
+/>
+
+// Explicit value
+<iframe
+  src="/embed"
+  {...fetchPriorityProp('low')}
+/>
+
+// Optional prop — undefined safely becomes 'auto'
+<img src={src} {...fetchPriorityProp(maybeHigh)} />
+```

package/src/utils/.format.md

@@ -1,38 +1,87 @@
-<!-- source-hash: b4d93cdfa7c612b1623c539002378201 -->
-This module provides a comprehensive set of utility functions for formatting various types of data into human-readable strings, including dates, numbers, currency, file sizes, and abbreviated large numbers.
+<!-- source-hash: dbfaad05e48db5fac78d6f613b9afd1e -->
+Utility functions for formatting data across dates, numbers, currencies, bytes, durations, and display strings. Serves as the single source of truth for all presentation-layer formatting in the Flamingo/OpenFrame stack.
 
 ## Key Components
 
-- **`formatDate`** - Converts Date objects or ISO strings to localized date strings with customizable options
-- **`formatNumber`** - Adds thousands separators to numbers using locale-specific formatting
-- **`formatPrice`** - Formats numbers as currency with proper symbols and localization
-- **`formatBytes`** - Converts byte values to human-readable file sizes (KB, MB, GB, etc.)
-- **`formatLargeNumber`** - Abbreviates large numbers to compact form (K, M, B) without decimals
-- **`formatAbbreviatedNumber`** - Similar to `formatLargeNumber` but includes decimal precision for better readability
+| Function | Description |
+|---|---|
+| `formatDate` | Locale-aware date formatting with `Intl.DateTimeFormatOptions` support |
+| `formatDateUTC` | UTC-anchored date formatter with fallback; handles ISO strings, epoch ms, and numeric strings |
+| `formatLegalDate` | Fixed `MM/DD/YYYY` format for legal documents |
+| `formatNumber` | Thousands-separator number formatting |
+| `formatPrice` | Currency-symbol formatting via `Intl.NumberFormat` |
+| `formatCurrency` | USD whole-dollar KPI formatter with `'N/A'` null guard |
+| `formatWholeDollars` | Configurable whole-dollar formatter (no cents) |
+| `formatPercent` | Fixed 2-decimal percent string with `'N/A'` null guard |
+| `formatBytes` | Human-readable byte sizes up to YB |
+| `formatBytesShort` | Compact byte formatter (`'B'` unit) for tight UI spaces |
+| `formatLargeNumber` | Abbreviated integers — `1K`, `2M`, `3B` (floor, no decimals) |
+| `formatAbbreviatedNumber` | Abbreviated numbers with one decimal when needed — `1.2K`, `2.5M` |
+| `getFirstLastInitials` | First + last word initials (e.g. `"John Michael Doe"` → `"JD"`) |
+| `nameInitials` | First + second word initials, max 2 chars, with configurable fallback |
+| `formatDurationMMSS` | Duration as `MM:SS` or `HH:MM:SS` |
+| `formatDurationCompact` | Duration as `"Xh Xm"` or `"X min"` |
+| `formatDurationFromRange` | Duration between two timestamps as compact string |
+| `formatTimeWithTimezone` | Time string with optional timezone label |
+| `formatCompactMetric` | Metric value with compact notation for KPI cards (partial) |
+| `MetricFormat` | Type: `'number' \| 'currency' \| 'percentage' \| 'months'` |
+| `TrendPolarity` | Type: `'positive' \| 'negative' \| 'neutral'` |
 
 ## Usage Example
 
 ```typescript
-import { 
-  formatDate, 
-  formatNumber, 
-  formatPrice, 
-  formatBytes, 
+import {
+  formatDate,
+  formatDateUTC,
+  formatBytes,
+  formatBytesShort,
   formatLargeNumber,
-  formatAbbreviatedNumber 
+  formatAbbreviatedNumber,
+  formatPrice,
+  formatCurrency,
+  formatPercent,
+  formatDurationMMSS,
+  formatDurationCompact,
+  formatDurationFromRange,
+  formatTimeWithTimezone,
+  nameInitials,
+  getFirstLastInitials,
 } from './format'
 
-// Date formatting
-const date = new Date('2024-01-15')
-console.log(formatDate(date)) // "January 15, 2024"
-console.log(formatDate(date, { month: 'short', day: 'numeric' })) // "Jan 15"
+// Dates
+formatDate('2024-08-15')
+// → "August 15, 2024"
 
-// Number formatting
-console.log(formatNumber(1234567)) // "1,234,567"
-console.log(formatPrice(29.99, 'USD')) // "$29.99"
-console.log(formatBytes(1024000)) // "1000 KB"
+formatDateUTC('2024-08-15')
+// → "Aug 15, 2024" (UTC-anchored, no timezone drift)
 
-// Large number abbreviation
-console.log(formatLargeNumber(1500)) // "1K"
-console.log(formatAbbreviatedNumber(1500)) // "1.5K"
+formatDateUTC(null, { fallback: 'Unknown' })
+// → "Unknown"
+
+// Bytes
+formatBytes(1536)           // → "1.5 KB"
+formatBytesShort(1536)      // → "1.5 KB"  (tight UI variant)
+
+// Numbers
+formatLargeNumber(1_500_000)       // → "1M"   (floor, no decimals)
+formatAbbreviatedNumber(1_200)     // → "1.2K" (one decimal when needed)
+
+// Currency
+formatPrice(49.99)                 // → "$49.99"
+formatCurrency(1234567)            // → "$1,234,567"
+formatPercent(12.5)                // → "12.50%"
+
+// Duration
+formatDurationMMSS(3725)           // → "1:02:05"
+formatDurationCompact(3725)        // → "1h 2m"
+formatDurationFromRange('2024-01-01T10:00:00Z', '2024-01-01T11:30:00Z')
+// → "1h 30m"
+
+formatTimeWithTimezone(new Date(), 'EST')
+// → "10:30 AM EST"
+
+// Initials
+nameInitials('John Michael Doe')   // → "JM"
+getFirstLastInitials('John Michael Doe') // → "JD"
+nameInitials(null)                 // → "E"  (default fallback)
 ```