@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260726003127

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

@@ -1,46 +1,62 @@
-<!-- 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.
+<!-- source-hash: 136c109b7bdd3302447f1c154892d2e4 -->
+Shared `fetch` wrapper for embedded surfaces (chat, ticket center, widgets) that attaches bearer-act-as identity headers (`Authorization` + `X-Chat-Act-As`) from proxy auth storage, with support for host-supplied auth adapters, cross-origin defense, and 401 self-healing.
 
 ## 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
-- **Self-heals on `401`** when a host registered an `EmbedAuthAdapter` with a `refresh` callback: calls `refresh()` once, and on success retries the same request a single time with freshly-recomputed headers (so a rotated bearer is picked up). Concurrent 401s share ONE refresh. With no adapter / no `refresh`, the 401 passes through unchanged.
-
-### `setEmbedAuthAdapter(adapter | null)` + `EmbedAuthAdapter`
-Optional host-owned auth override registered at module level (one chat panel per app). The adapter can supply:
-- `getHeaders()` — headers merged onto every call AFTER proxy-auth (adapter wins), re-read per request so token rotation is seen
-- `credentials` — overrides the default `'same-origin'` (e.g. `'include'` for cross-origin cookie auth)
-- `refresh()` — `Promise<boolean>` 401 self-heal hook (see above). This lifts the openframe `apiClient`'s refresh-then-retry behaviour into the lib so embedded surfaces no longer need a host-side `window.fetch` monkey-patch to survive an expired token mid-session.
-
-### `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'`)
+### Interfaces
+
+- **`EmbedAuthAdapter`** — Interface for host-supplied auth overrides. Supports `getHeaders()`, `credentials`, `refresh` (401 self-heal), and `allowedOrigins` (native-shell hatch for cross-origin allowlisting).
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `setEmbedAuthAdapter(adapter)` | Registers (or clears) a host-owned auth adapter at the `globalThis` slot `__embedAuthedFetchAdapter__`. Warns on overwrite in non-production. |
+| `hasEmbedAuthAdapter()` | Returns `true` when an adapter is currently registered; used by sibling helpers to route through `embedAuthedFetch` only when embedded auth is active. |
+| `needsBearerAssetFetch(url)` | Returns `true` when the URL's origin is in the adapter's `allowedOrigins` AND the adapter is supplying an `Authorization` header — signals that native asset loads (`<img src>`) must use fetch + blob object-URL instead. |
+| `embedAuthedFetch(url, init?)` | Drop-in `fetch` replacement. Merges proxy auth headers, enforces same-origin (or `allowedOrigins`) guard synchronously, and performs a single 401 refresh + retry when `adapter.refresh` is registered. |
 
 ## Usage Example
 
 ```typescript
-// JSON POST to chat API — proxy headers attached automatically
-const res = await embedAuthedFetch('/api/chat/messages', {
+import {
+  setEmbedAuthAdapter,
+  embedAuthedFetch,
+  needsBearerAssetFetch,
+} from './embed-authed-fetch'
+
+// Register a host adapter on provider mount
+setEmbedAuthAdapter({
+  getHeaders: () => ({
+    Authorization: token ? `Bearer ${token}` : undefined,
+  }),
+  credentials: 'include',
+  refresh: async () => {
+    const refreshed = await refreshAccessToken()
+    return refreshed
+  },
+  allowedOrigins: ['https://gateway.example.com'],
+})
+
+// Use as a drop-in fetch replacement for /api/chat/* routes
+const response = 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: {},
-})
+// Route asset loads through fetch when bearer is required
+if (needsBearerAssetFetch(imageUrl)) {
+  const res = await embedAuthedFetch(imageUrl)
+  const blob = await res.blob()
+  imgElement.src = URL.createObjectURL(blob)
+}
 
-// Vanilla fetch — use for routes that don't need bearer-act-as
-const profile = await fetch('/api/profile/me', { credentials: 'same-origin' })
+// Clear adapter on provider unmount
+setEmbedAuthAdapter(null)
 ```
 
-> 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.
+> **Note:** The adapter is stored on `globalThis` (key `__embedAuthedFetchAdapter__`) rather than module scope to survive bundler code-splitting across multiple entry points. Routes that do not need bearer-act-as (e.g. `/api/profile/me`) should continue using vanilla `fetch`.
+
+## Source
+
+[`embed-authed-fetch.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embed-authed-fetch.ts)

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

@@ -0,0 +1,36 @@
+<!-- source-hash: 62e7c52af0777cb746a6d452c7225669 -->
+Thin routing shim that directs content-surface HTTP requests through the embed auth adapter when one is registered, or falls back to a plain `fetch` otherwise.
+
+## Key Components
+
+### `contentFetch`
+
+A `typeof fetch`-compatible function used by all self-fetching content surfaces (roadmap, delivery, product releases, onboarding guides, legal docs, release-detail injected sections). Routes requests based on adapter presence:
+
+- **Adapter registered** → delegates to `embedAuthedFetch`, which attaches bearer tokens/cookies and handles 401 refresh — the same auth path used by the embedded chat.
+- **No adapter** → returns a plain, unmodified `fetch` call.
+
+Internally coerces the full `RequestInfo | URL` input shape down to a plain string URL, since `embedAuthedFetch` accepts only strings. Handles all three input variants (`string`, `URL`, `Request`) defensively, even though content surfaces always pass strings in practice.
+
+## Usage Example
+
+```typescript
+// After wiring the embed auth adapter once for the chat surface,
+// all content fetches automatically inherit the same auth:
+
+import { contentFetch } from './embed-content-fetch'
+
+// Used internally by content surfaces — no configuration needed
+const response = await contentFetch('/api/roadmap/items', {
+  method: 'GET',
+  headers: { 'Content-Type': 'application/json' },
+})
+
+const data = await response.json()
+```
+
+> Hosts register auth **once** via `EmbedAuthAdapter` for the chat surface; `contentFetch` inherits it automatically with no additional setup required.
+
+## Source
+
+[`embed-content-fetch.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embed-content-fetch.ts)

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)