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

package/src/utils/.embed-url-converters.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 2e5892bd515faa4d91f2c3e44db6baa3 -->
+Shared utilities for converting external service URLs (Google Sheets, Figma) into embeddable iframe-compatible formats. Used by embed components in the lib and the admin document editor in the hub.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `toGoogleSheetsEmbedUrl` | Converts a Google Sheets URL to the `htmlembed` format, preserving the `gid` (sheet tab) parameter |
+| `toGoogleSheetsOriginalUrl` | Normalizes a Sheets URL back to the standard `/edit#gid=` format |
+| `toFigmaEmbedUrl` | Converts any Figma URL (design, proto, slides/deck, board) to `embed.figma.com`, injecting `embed-host` and optional `client-id` params |
+| `isFigmaSlidesUrl` | Returns `true` if the URL points to a Figma Slides or Deck resource |
+| `toFigmaOriginalUrl` | Strips embed-specific domain and query string to recover the original Figma URL |
+
+## Usage Example
+
+```typescript
+import {
+  toGoogleSheetsEmbedUrl,
+  toFigmaEmbedUrl,
+  isFigmaSlidesUrl,
+} from './embed-url-converters'
+
+// Google Sheets — converts to htmlembed with tab preserved
+const sheetsEmbed = toGoogleSheetsEmbedUrl(
+  'https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit#gid=0'
+)
+// → https://docs.google.com/spreadsheets/d/1Bxi.../htmlembed?widget=true&chrome=false&headers=false&gid=0
+
+// Figma design
+const figmaEmbed = toFigmaEmbedUrl(
+  'https://www.figma.com/design/ABC123/My-Component'
+)
+// → https://embed.figma.com/design/ABC123/My-Component?embed-host=flamingo
+
+// Figma slides — browse mode
+const slidesEmbed = toFigmaEmbedUrl(
+  'https://www.figma.com/slides/ABC123/Deck',
+  { slidesView: 'browse' }
+)
+// → https://embed.figma.com/slides/ABC123/Deck?embed-host=flamingo
+
+// Type guard
+isFigmaSlidesUrl('https://www.figma.com/deck/ABC123/Q3-Review') // → true
+```
+
+## Notes
+
+- `toFigmaEmbedUrl` reads `NEXT_PUBLIC_FIGMA_CLIENT_ID` from the environment and injects it as a `client-id` query param when present.
+- Already-embedded URLs (containing `embed.figma.com` or `/htmlembed`) are returned unchanged — all converters are idempotent.
+- Figma `slides` and `deck` URL types both map to the `deck` embed view by default; pass `{ slidesView: 'browse' }` to switch to the `slides` browse view.
+
+**Source:** [`embed-url-converters.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embed-url-converters.ts)

package/src/utils/.extract-items.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 5e010896207fab5f7b8fcce5af44e754 -->
+Normalizes list-API response shapes into a consistent `unknown[]` array and extracts stable item identifiers across varying endpoint payload structures. Pure utility functions with no runtime dependencies — safe for server and client use.
+
+## Key Components
+
+| Export | Signature | Description |
+|---|---|---|
+| `extractItems` | `(data: unknown) => unknown[]` | Normalizes heterogeneous response shapes into a flat array |
+| `extractItemId` | `(type: string, item: unknown) => string \| null` | Extracts a stable primary key from an item, handling `id` vs `external_id` variance |
+
+### `extractItems` — Supported Response Shapes
+
+| Property | Source |
+|---|---|
+| `{ items }` | General list endpoints |
+| `{ posts }` | Post/blog endpoints |
+| `{ campaigns }` | Campaign endpoints |
+| `{ completed, inProgress }` | Delivery endpoints (flattened) |
+| `{ data }` | Generic data wrapper |
+| Raw `Array` | Direct array responses |
+
+### `extractItemId` — Key Resolution Strategy
+
+For `roadmap_item`, `delivery_item`, and `internal_task` types, `external_id` is checked first (ClickUp-backed IDs). Falls back to `obj.id` as string or coerced number for all other types.
+
+## Usage Example
+
+```typescript
+import { extractItems, extractItemId } from './extract-items'
+
+// Normalize any list endpoint response
+const rawResponse = await fetchCampaigns()
+const items = extractItems(rawResponse) // always returns Item[]
+
+// Resolve a stable ID regardless of item type
+for (const item of items) {
+  const id = extractItemId('roadmap_item', item)
+  if (id) console.log('Matched item:', id)
+}
+
+// Delivery endpoint — flattens completed + inProgress automatically
+const deliveryItems = extractItems({ completed: [...], inProgress: [...] })
+```
+
+## Notes
+
+- **No external dependencies** — no `@tanstack/react-query` import, intentionally hoisted to keep this out of the chat hooks chunk
+- **Re-exported** from `lib/utils/entity-list-api.ts` in the hub repo as the single normalization implementation across both repositories
+- Source: [`src/lib/utils/extract-items.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/lib/utils/extract-items.ts)

package/src/utils/.faq-anchor.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 86e3de31861d76eca010d803a819a536 -->
+Single source of truth for FAQ deep-link anchor formatting and parsing on the `/faqs` page, covering both category-level and item-level hash targets.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `faqSectionSlug` | `function` | Generates a `faq-<slug>` anchor id for a category section |
+| `faqItemAnchor` | `function` | Generates a `faq-item-<id>` anchor id for an individual FAQ row |
+| `FaqHashTarget` | `type` | Discriminated union representing a parsed hash result (`item` or `section`) |
+| `parseFaqHash` | `function` | Parses a `/faqs#…` hash string into a typed `FaqHashTarget` or `null` |
+
+## Hash Format Contract
+
+```text
+/faqs#faq-pricing      → section anchor  (jump-nav, scroll-spy)
+/faqs#faq-item-42      → item anchor     (chat citation, auto-expand + scroll)
+/faqs#anything-else    → null            (unrecognised, callers early-out)
+```
+
+## Usage Example
+
+```typescript
+import { faqSectionSlug, faqItemAnchor, parseFaqHash } from './faq-anchor'
+
+// Rendering anchors
+const sectionId = faqSectionSlug('Pricing & Plans')  // → 'faq-pricing-plans'
+const itemId    = faqItemAnchor(42)                   // → 'faq-item-42'
+
+// Parsing on mount (e.g. FaqSection auto-open logic)
+const target = parseFaqHash(window.location.hash)
+
+if (target?.kind === 'item') {
+  const row = items.find(i => String(i.id) === target.rawId)
+  row?.expand()
+} else if (target?.kind === 'section') {
+  document.getElementById(target.slug)?.scrollIntoView()
+}
+// target === null → no hash or unrecognised prefix, no-op
+```
+
+## Notes
+
+- **Collision safety:** The `faq-item-<digits>` namespace is reserved exclusively for item anchors; `parseFaqHash` uses a digits-only regex so word-suffixed slugs like `faq-item-whatever` are correctly classified as sections.
+- **`rawId` is a string** — coercion to compare against `item.id` is intentionally deferred to the call site.
+- Centralising format helpers and the parser in one file prevents format drift across the page component, chat RAG mapper, and any future consumers.
+
+**Source:** [`faq-anchor.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/faq-anchor.ts)

package/src/utils/.format.md

@@ -1,31 +1,25 @@
-<!-- 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.
+<!-- source-hash: 801f56963096c8525cf1e145bb056b0f -->
+Utility functions for consistent formatting of dates, times, numbers, file sizes, durations, and name initials across server and client environments, with UTC-pinned rendering to prevent React hydration mismatches.
 
 ## Key Components
 
-| Function | Description |
+| Export | 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'` |
+| `formatDate` | Formats a `Date` or ISO string to a localized date string; UTC-pinned by default to prevent SSR/client hydration drift |
+| `formatDateUTC` | UTC-anchored date formatter for RAG mappers and audit consumers; handles epoch numbers, ISO strings, and numeric string timestamps with a configurable fallback |
+| `formatNumber` | Formats a number with locale-aware thousands separators |
+| `formatPrice` | Formats a number as a currency string using `Intl.NumberFormat` (defaults to USD) |
+| `formatBytes` | Converts bytes to human-readable size with configurable decimal places (`Bytes` → `YB`) |
+| `formatBytesShort` | Compact byte formatter using single-letter `B` unit (2 decimal places, caps at `TB`) for space-constrained UIs |
+| `formatFileSize` | File-size formatter using 1 decimal place and `B` unit, capping at `GB`; canonical formatter for upload UIs and publication cards |
+| `formatLargeNumber` | Abbreviates large numbers to `K`, `M`, `B` with no decimal places |
+| `formatAbbreviatedNumber` | Similar abbreviation but preserves one decimal place when the value is not a whole number |
+| `getFirstLastInitials` | Extracts two-letter initials from the first and last word of a name (e.g., `"John Michael Doe"` → `"JD"`) |
+| `nameInitials` | Extracts up to two-letter initials from the first and second word; single source of truth for avatar fallbacks |
+| `formatDurationMMSS` | Formats seconds as `MM:SS` or `HH:MM:SS` for media players |
+| `formatDurationCompact` | Formats seconds as `Xh Xm` or `X min` for cards and headers |
+| `formatDurationFromRange` | Calculates and formats duration between two timestamps as `1h 30m` or `45m` |
+| `formatTimeWithTimezone` | Formats an event's wall-clock time in its own IANA timezone; falls back to UTC on invalid zone labels |
 
 ## Usage Example
 
@@ -33,55 +27,79 @@ Utility functions for formatting data across dates, numbers, currencies, bytes,
 import {
   formatDate,
   formatDateUTC,
+  formatPrice,
   formatBytes,
   formatBytesShort,
+  formatFileSize,
   formatLargeNumber,
   formatAbbreviatedNumber,
-  formatPrice,
-  formatCurrency,
-  formatPercent,
+  nameInitials,
+  getFirstLastInitials,
   formatDurationMMSS,
   formatDurationCompact,
   formatDurationFromRange,
   formatTimeWithTimezone,
-  nameInitials,
-  getFirstLastInitials,
 } from './format'
 
-// Dates
+// Dates — UTC-pinned to prevent SSR/client mismatch
 formatDate('2024-08-15')
 // → "August 15, 2024"
 
-formatDateUTC('2024-08-15')
-// → "Aug 15, 2024" (UTC-anchored, no timezone drift)
+formatDateUTC('2024-08-15', { fallback: 'N/A' })
+// → "Aug 15, 2024"
+
+formatDateUTC(null)
+// → "N/A"
+
+// Numbers and currency
+formatPrice(4999.99, 'EUR')
+// → "€4,999.99"
 
-formatDateUTC(null, { fallback: 'Unknown' })
-// → "Unknown"
+formatLargeNumber(1_450_000)
+// → "1M"
 
-// Bytes
-formatBytes(1536)           // → "1.5 KB"
-formatBytesShort(1536)      // → "1.5 KB"  (tight UI variant)
+formatAbbreviatedNumber(1_200)
+// → "1.2K"
 
-// Numbers
-formatLargeNumber(1_500_000)       // → "1M"   (floor, no decimals)
-formatAbbreviatedNumber(1_200)     // → "1.2K" (one decimal when needed)
+// File sizes
+formatBytes(1536)
+// → "1.50 KB"
 
-// Currency
-formatPrice(49.99)                 // → "$49.99"
-formatCurrency(1234567)            // → "$1,234,567"
-formatPercent(12.5)                // → "12.50%"
+formatBytesShort(1536)
+// → "1.5 KB"  (compact UI variant)
 
-// Duration
-formatDurationMMSS(3725)           // → "1:02:05"
-formatDurationCompact(3725)        // → "1h 2m"
-formatDurationFromRange('2024-01-01T10:00:00Z', '2024-01-01T11:30:00Z')
+formatFileSize(1500)
+// → "1.5 KB"  (1 decimal, caps at GB)
+
+// Avatar initials
+nameInitials('John Doe')
+// → "JD"
+
+getFirstLastInitials('John Michael Doe')
+// → "JD"  (first + last word)
+
+nameInitials(null, 'U')
+// → "U"
+
+// Durations
+formatDurationMMSS(3725)
+// → "1:02:05"
+
+formatDurationCompact(3725)
+// → "1h 2m"
+
+formatDurationFromRange('2024-08-15T14:00:00Z', '2024-08-15T15:30:00Z')
 // → "1h 30m"
 
-formatTimeWithTimezone(new Date(), 'EST')
-// → "10:30 AM EST"
+// Event time in its own timezone (prevents React #418 hydration mismatch)
+formatTimeWithTimezone('2024-08-15T20:00:00Z', 'America/New_York')
+// → "4:00 PM"
+```
+
+## Notes
+
+- **Hydration safety**: `formatDate` and `formatTimeWithTimezone` pin to UTC by default so Vercel (UTC runtime) and browser clients always render identical strings, avoiding React hydration error #418.
+- **Avatar fallback hierarchy**: Prefer `nameInitials` over `getFirstLastInitials` for new components — it is the designated single source of truth and accepts a configurable `fallback` character.
+- **File size variants**: Three formatters exist for historical reasons. Use `formatFileSize` for publication cards and upload UIs, `formatBytesShort` for space-constrained progress indicators, and `formatBytes` for general-purpose display.
 
-// Initials
-nameInitials('John Michael Doe')   // → "JM"
-getFirstLastInitials('John Michael Doe') // → "JD"
-nameInitials(null)                 // → "E"  (default fallback)
-```
+**Source:** [`format.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/format.ts)

package/src/utils/.humanity-signals.md

@@ -0,0 +1,59 @@
+<!-- source-hash: e5bd0dff73673a1dcedb4a72a3a18491 -->
+Invisible bot-protection primitives for shared use between public forms (client) and the hub's per-route `verifyHuman` gate (server). Designed as a pure, React-free server entry so the hub can import it without triggering a client-reference boundary.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `HONEYPOT_FIELD` | `const string` | Hidden field name bots may fill; real users never interact with it |
+| `ELAPSED_MS_FIELD` | `const string` | Field name carrying client-measured ms from form mount to submit |
+| `DEFAULT_MIN_FILL_MS` | `const number` | Minimum acceptable fill time (`700` ms); faster submits are treated as bots |
+| `HumanitySignals` | `type` | Wire object spread into the POST body by `useHumanitySignals().getSignals()` |
+| `HumanityVerdict` | `type` | Union result — `{ ok: true }` or `{ ok: false; reason: 'honeypot' \| 'too_fast' }` |
+| `extractHumanitySignals` | `function` | Tolerant reader that parses raw POST body; never throws, returns `null` for missing/garbage timing |
+| `evaluateHumanitySignals` | `function` | Single source of truth for the block/allow decision — honeypot fill or sub-threshold timing → reject |
+| `splitCsvEnv` | `function` | Utility to parse comma-separated env strings into trimmed, non-empty arrays |
+
+## Usage Example
+
+```typescript
+import {
+  evaluateHumanitySignals,
+  DEFAULT_MIN_FILL_MS,
+} from 'openframe-oss-lib/humanity-signals'
+
+// Server-side route handler (hub's verifyHuman gate)
+export async function POST(req: Request) {
+  const body = await req.json()
+
+  const verdict = evaluateHumanitySignals(body, {
+    minFillMs: DEFAULT_MIN_FILL_MS,
+  })
+
+  if (!verdict.ok) {
+    // 'honeypot' — hidden field was filled
+    // 'too_fast'  — submission arrived before a human could type
+    return new Response(`Blocked: ${verdict.reason}`, { status: 400 })
+  }
+
+  // Proceed with legitimate submission...
+}
+```
+
+```typescript
+// Client-side form — spread signals into the POST body
+import { HONEYPOT_FIELD, ELAPSED_MS_FIELD } from 'openframe-oss-lib/humanity-signals'
+
+const payload = {
+  email: formData.email,
+  message: formData.message,
+  [HONEYPOT_FIELD]: '',          // always empty for real users
+  [ELAPSED_MS_FIELD]: elapsedMs, // measured since form mount
+}
+```
+
+> **Note:** Missing timing values (`elapsedMs: null`) are always allowed — only a present sub-threshold value triggers a `too_fast` block, preventing false positives from clients that omit the field.
+
+## Source
+
+[`humanity-signals.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/humanity-signals.ts)

package/src/utils/.index.md

@@ -1,49 +1,91 @@
-<!-- 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.
+<!-- source-hash: d40f5b4bdeaf9f6f4c4960fabf86ab54 -->
+Central barrel export for the `utils` package, aggregating and re-exporting all utility functions, constants, and types from across the library to provide a single stable import surface for consumers.
 
 ## Key Components
 
-| 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) |
+### Formatting Utilities
+- **`formatDate`, `formatNumber`, `formatPrice`, `formatBytes`** — Core number/currency/byte/date formatters (`./format`)
+- **`formatLargeNumber`, `formatCurrency`, `formatPercent`, `formatDurationMMSS`**, and many more — Extended formatter suite covering metrics, trends, durations, and text
+- **`formatRelativeTime`, `formatAbsoluteDate`, `formatDateTime`** — Date/time helpers from `./date-utils`
+
+### Color & Styling
+- **`getPlatformAccentColor`, `getCurrentPlatform`** — Platform-aware accent color resolution
+- **`getReadableTextColor`, `hexToRgb`, `deriveHoverColor`, `deriveActiveColor`** — Design-system color math utilities
+- **`cn`** — Class name utility (client-side only)
+
+### Platform & Domain
+- **`getPlatformProductionUrl`, `getAllPlatformBaseDomains`** — Platform domain SSOT re-exported from `../platform-domains`
+- **`getPlatformLogo`** — Platform icon component resolver
+
+### Navigation & Scroll
+- **`scrollElementIntoView`** — Smooth scroll with sticky-chrome offset compensation
+- **`navigateSamePageHash`, `normalizeHashFragment`** — Same-page hash navigation with `pushState` and synthetic `hashchange`
+
+### Embed Auth
+- **`embedAuthedFetch`, `setEmbedAuthAdapter`** — Generic embed surface authentication
+- **`getEmbedProxyAuth`, `setEmbedProxyAuth`, `applyProxyAuth`** — Proxy auth storage (cookie SSOT)
+
+### Chat Utilities (Server-Safe Re-exports)
+- **`escapeMarkdownInline`, `buildChatAttachmentViewUrl`** — Chat attachment markdown helpers
+- **`getSourceIconName`, `getSourceLabel`** — Source icons/labels, safe for server-side hub callers
+- **`readLeadingDecisionFrame`** — SSE leading-frame reader for `confirm-tool` route
+
+### Icon & Media
+- **`getDynamicIcon`, `ICON_REGISTRY`, `getIconComponent`** — Dynamic icon registry
+- **`PLAY_ICON_PATH`** — SVG path constant (server-safe)
+
+### SEO & Content
+- **`SEO_TITLE_MAX_LENGTH`, `SEO_DESCRIPTION_MAX_LENGTH`** — Character budget constants
+- **`buildListUrl`, `canonicalContentRefType`** — List-API URL builder
+- **`faqSectionSlug`, `faqItemAnchor`, `parseFaqHash`** — FAQ anchor SSOTs
+
+### Miscellaneous
+- **`delay`, `generateRandomString`, `truncateString`, `deepClone`** — Common utilities
+- **`getProxiedImageUrl`, `shouldProxyImage`, `generateImageSizes`** — Image proxy builder
+- **`DEV_SECTION_PARAM_KEYS`, `devSectionAnchorId`** — Dev-center URL param keys
+- **`fetchPriorityProp`** — React 18/19 compatible `fetchpriority` prop builder
 
 ## Usage Example
 
 ```typescript
-// Import any utility directly from the utils barrel
+// Import from the unified utils barrel
 import {
   cn,
+  formatDate,
   formatCurrency,
-  formatRelativeTime,
-  getDynamicIcon,
-  getEmbedProxyAuth,
+  getPlatformAccentColor,
   scrollElementIntoView,
-  getCurrentPlatform,
-} from '@flamingo-stack/openframe-frontend-core/utils'
+  embedAuthedFetch,
+  SEO_TITLE_MAX_LENGTH,
+  buildListUrl,
+} from '@flamingo-stack/openframe-oss-lib/utils'
+
+// Formatting
+const price = formatCurrency(1999, 'USD')       // "$19.99"
+const date  = formatDate(new Date(), 'short')
 
-// CSS class merging
-const className = cn('base-class', isActive && 'active')
+// Color utilities
+const accent = getPlatformAccentColor('flamingo')
 
-// Format a currency value
-const price = formatCurrency(4999, 'USD') // "$49.99"
+// Scroll
+scrollElementIntoView(document.getElementById('section'), { offset: 64 })
 
-// Relative time display
-const label = formatRelativeTime(new Date('2024-01-01')) // "6 months ago"
+// Embed auth
+const response = await embedAuthedFetch('/api/data')
 
-// Retrieve embed proxy auth for non-chat surfaces
-const auth = getEmbedProxyAuth()
+// SEO guard
+if (title.length > SEO_TITLE_MAX_LENGTH) {
+  console.warn('Title exceeds SEO budget')
+}
 
-// Scroll an element into view respecting sticky chrome
-scrollElementIntoView(targetElement, { offsetPx: 64 })
+// List URL builder
+const url = buildListUrl('ticket', ['id-1', 'id-2'], '/content')
 ```
 
-> **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.
+## Notes
+
+- **Server-safe vs. client-only**: `cn` and canvas-based utilities (e.g., `color-analysis`) are client-only. Most other exports are isomorphic/server-safe.
+- **SSOT pattern**: Several exports are re-exports from canonical locations (e.g., `../platform-domains`, `./format`) to preserve backward compatibility without duplicating logic.
+- **Deprecated aliases**: Chat-prefixed auth symbols (`chat-authed-fetch`, `chat-proxy-auth-storage`) are kept as `@deprecated` re-exports in their original locations; use the `embed*` equivalents from this barrel going forward.
+
+**Source:** [`src/utils/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/index.ts)

package/src/utils/.list-url.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 4926a63272f9475827aa4c96aaa551da -->
+Builds and returns list-API endpoint URLs for chat entity-card fetches, mapping canonical `contentRefType` strings to their type-specific query shapes. Returns `null` for types without a list endpoint, preventing spurious fetches.
+
+## Key Components
+
+### `canonicalContentRefType(contentRefType)`
+Resolves legacy `ContentRef` type aliases to their canonical `documentType`. Exported so consumers share this alias map rather than redeclaring it (e.g., `blog_post_existing` → `blog_post`).
+
+### `buildListUrl(contentRefType, ids, base?)`
+Main export. Constructs a type-specific list-API URL for the given IDs, or returns `null` if the type has no list endpoint. The optional `base` prefix supports reverse-proxy deployments (default: `''` → hub-relative `/api/...`; `'/content'` → `/content/api/...`).
+
+### `BUILDERS` (internal)
+Per-type URL factory map keyed by canonical `documentType`. Covers 13 fetch-mode types with their exact parameter shapes (`task_ids=` for ClickUp-backed types, `pageSize=` for blog, `limit=&filter=all` for programs, etc.). Absent keys return `null` by design — non-list types (`github_*`, `slack_message`, financials) are intentionally excluded.
+
+### `ALIASES` (internal)
+Maps legacy `ContentRef` rail-vocab types to canonical `documentType` values before BUILDERS lookup.
+
+## Usage Example
+
+```typescript
+import { buildListUrl, canonicalContentRefType } from '@flamingo-stack/openframe-frontend-core/utils'
+
+// Hub-relative (default)
+buildListUrl('roadmap_item', ['abc', 'def'])
+// → '/api/roadmap?task_ids=abc,def'
+
+// With reverse-proxy prefix
+buildListUrl('blog_post_existing', ['x', 'y'], '/content')
+// → '/content/api/blog/posts?ids=x,y&pageSize=2'  (alias resolved)
+
+// Type with no list endpoint → null (fetch skipped)
+buildListUrl('github_pr', ['z'])
+// → null
+
+// Wire into embedder endpoints once:
+endpoints.buildListUrl = (type, ids) => buildListUrl(type, ids, '/content')
+
+// Resolve alias for external comparison
+canonicalContentRefType('blog_post_existing') // → 'blog_post'
+canonicalContentRefType('webinar')            // → 'webinar'
+```
+
+> **Security note:** `marketing_campaign` is handled as a literal static branch (not a `BUILDERS` entry) so CodeQL can prove no user-controlled dynamic dispatch reaches `/api/admin`. Prototype-poisoning keys (`__proto__`, `constructor`) are blocked via an explicit `hasOwnProperty` guard before dispatching into `BUILDERS`.

package/src/utils/.markdown-section-extractor.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 7c9c0c76751534f9471aac4fddb8f3e7 -->
+Parses markdown content line-by-line to extract heading sections for navigation, returning structured metadata including IDs, titles, and heading levels.
+
+## Key Components
+
+### Interfaces
+
+- **`MarkdownSection`** — Output shape with `id` (URL-safe slug), `title` (cleaned text), and `level` (heading depth 1–6)
+- **`ExtractSectionsOptions`** — Configuration for extraction behavior (see defaults below)
+
+### Function
+
+- **`extractSections(markdown, options?)`** — Main export. Iterates over lines, skips fenced code blocks and YAML frontmatter, matches heading patterns up to `maxLevel`, and returns a `MarkdownSection[]`
+
+### Default Options
+
+| Option | Default | Description |
+|---|---|---|
+| `maxLevel` | `2` | Include H1–H2 only |
+| `removeEmojis` | `true` | Strip emoji from generated IDs |
+| `handleDuplicateIds` | `true` | Append `-2`, `-3`, etc. for duplicate slugs |
+| `stripFormattingMarkers` | `true` | Remove bold/italic/code markers from titles |
+| `skipCodeAndYamlBlocks` | `true` | Ignore headings inside code fences or frontmatter |
+
+## Usage Example
+
+```typescript
+import { extractSections } from './markdown-section-extractor'
+
+const markdown = `
+---
+title: Guide
+---
+
+# Introduction
+
+## **Getting Started**
+
+## Getting Started
+
+\`\`\`bash
+# This heading is skipped
+\`\`\`
+
+### Deep Section
+`
+
+const sections = extractSections(markdown, { maxLevel: 3 })
+// [
+//   { id: 'introduction',      title: 'Introduction',     level: 1 },
+//   { id: 'getting-started',   title: 'Getting Started',  level: 2 },
+//   { id: 'getting-started-2', title: 'Getting Started',  level: 2 },
+//   { id: 'deep-section',      title: 'Deep Section',     level: 3 },
+// ]
+```
+
+> **Note:** ID generation lowercases text, strips non-word characters, and replaces spaces with hyphens. Empty IDs fall back to `section-N`. Depends on [`stripInlineMarkdown`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/markdown-to-plain.ts) for title cleanup.