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

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

@@ -1,35 +1,44 @@
-<!-- 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.
+<!-- source-hash: 49fcc1fc36872594f424bdbdc5b66d78 -->
+Client-side color analysis utilities for extracting dominant colors from images and selecting accessible badge/background colors based on WCAG contrast ratios.
 
 ## 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 |
+### Types & Constants
 
-## Usage Example
+- **`ColorPalette`** — Interface representing a named color with `hex` and `rgb` tuple fields.
+- **`DESIGN_PALETTE`** — Three-entry design system palette: `yellow`, `black`, and `gray`.
 
-```typescript
-import { analyzeImageColor, extractImageEdgeColorAsync, getContrastRatio, hexToRgb } from './color-analysis';
+### Functions
 
-// Get the best badge text color for a logo image
-const badgeColor = await analyzeImageColor('https://example.com/logo.png');
-console.log(badgeColor.hex); // '#161616'
+| Function | Description |
+|---|---|
+| `hexToRgb(hex)` | Converts a hex color string (with shorthand support) to an RGB tuple. |
+| `getContrastRatio(color1, color2)` | Returns the WCAG contrast ratio between two RGB colors. |
+| `pickReadableTextColor(bgHex)` | Returns `'dark'` or `'light'` based on which foreground has better contrast against the given background hex. |
+| `extractDominantColor(canvas)` | Samples ~1000 pixels in a grid pattern and bucket-quantizes (step 32) to find the most frequent color. |
+| `getBestContrastColor(imageColor)` | Picks the `DESIGN_PALETTE` entry with the highest contrast against a given RGB color; falls back to `black` if no entry meets 3:1. |
+| `analyzeImageColor(imageSrc)` | Loads an image via canvas (scaled to max 100px), extracts its dominant color, and resolves with the best-contrast palette entry. |
+| `extractImageEdgeColorAsync(imageUrl)` | Samples a 15% edge band of an image (scaled to max 50px) and returns the average dominant edge color as a hex string. Used for email/card background fills. |
 
-// Extract edge color for email/card background fill
-const bgColor = await extractImageEdgeColorAsync('https://example.com/hero.jpg');
-console.log(bgColor); // '#1a2b3c'
+## Usage Example
 
-// Manual contrast check between two hex colors
-const ratio = getContrastRatio(hexToRgb('#FFC008'), hexToRgb('#161616'));
-console.log(ratio); // ~11.5 (passes WCAG AA and AAA)
+```typescript
+import {
+  pickReadableTextColor,
+  analyzeImageColor,
+  extractImageEdgeColorAsync,
+} from './color-analysis';
+
+// Choose a text theme for a dynamic banner background
+const theme = pickReadableTextColor('#FFC008'); // → 'dark'
+
+// Resolve a badge color from a product image
+const paletteColor = await analyzeImageColor('https://cdn.example.com/product.png');
+console.log(paletteColor.name); // e.g. 'yellow'
+
+// Fill background color behind an image in an email template
+const edgeHex = await extractImageEdgeColorAsync('https://cdn.example.com/hero.jpg');
+console.log(edgeHex); // e.g. '#1a1a1a'
 ```
 
-> **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.
+> **Note:** `analyzeImageColor` and `extractImageEdgeColorAsync` are browser-only (they depend on `HTMLCanvasElement` and `document`). `extractImageEdgeColorAsync` returns `#000000` in SSR/Node environments.

package/src/utils/.common.md

@@ -1,36 +1,56 @@
-<!-- source-hash: e54e6fb6cb2d70638760dba85e7b09f8 -->
-Common utility functions for TypeScript/React applications, providing essential helpers for styling, async operations, string manipulation, and object cloning.
+<!-- source-hash: dd0dfcce5e3006e1d50e924c7a9379a7 -->
+General-purpose utility functions for class name merging, async delays, string manipulation, JSON-LD serialization, object cloning, and environment-based Slack URL resolution.
 
 ## Key Components
 
-- **`cn()`** - Merges and deduplicates Tailwind CSS class names using `clsx` and `tailwind-merge`
-- **`delay()`** - Creates a Promise-based delay for async operations
-- **`generateRandomString()`** - Generates cryptographically simple random strings for IDs or tokens
-- **`truncateString()`** - Safely truncates strings with customizable suffix
-- **`deepClone()`** - Performs deep cloning of objects using JSON serialization
-- **`getSlackCommunityJoinUrl()`** - Retrieves Slack community URL from environment variables with fallback
+| Export | Signature | Description |
+|---|---|---|
+| `cn` | `(...inputs: ClassValue[]) => string` | Merges Tailwind CSS class names using `clsx` + `tailwind-merge` |
+| `delay` | `(ms: number) => Promise<void>` | Async sleep helper |
+| `generateRandomString` | `(length?: number) => string` | Alphanumeric random string generator (default length: 8) |
+| `truncateString` | `(str, maxLength, suffix?) => string` | Truncates with configurable suffix (default: `"..."`) |
+| `serializeJsonLd` | `(schema: unknown) => string` | XSS-safe JSON-LD serializer — escapes `<` as `\u003c` |
+| `deepClone` | `<T>(obj: T) => T` | Structural clone via JSON round-trip |
+| `getSlackCommunityJoinUrl` | `() => string` | Reads `NEXT_PUBLIC_SLACK_COMMUNITY_JOIN_URL` with fallback to OpenMSP invite |
 
 ## Usage Example
 
 ```typescript
-import { cn, delay, generateRandomString, truncateString, deepClone, getSlackCommunityJoinUrl } from './common'
+import {
+  cn,
+  delay,
+  generateRandomString,
+  truncateString,
+  serializeJsonLd,
+  deepClone,
+  getSlackCommunityJoinUrl,
+} from "@/lib/utils/common"
 
-// Merge Tailwind classes (removes duplicates)
-const buttonClass = cn('px-4 py-2 bg-blue-500', isActive && 'bg-blue-700', 'hover:bg-blue-600')
+// Merge Tailwind classes (handles conflicts)
+const cls = cn("px-4 py-2", isActive && "bg-blue-500", "px-6") // "py-2 bg-blue-500 px-6"
 
-// Async delay
-await delay(1000) // Wait 1 second
+// Async delay in an async function
+await delay(1500) // waits 1.5 seconds
 
-// Generate random ID
-const sessionId = generateRandomString(12) // "aB3xY9mN4pQ1"
+// Random token generation
+const token = generateRandomString(16) // e.g. "aZ3kR8mQpL2nWx7T"
 
-// Truncate long text
-const preview = truncateString("This is a very long description...", 20) // "This is a very lo..."
+// Safe truncation
+truncateString("OpenFrame AI Platform", 14) // "OpenFrame AI..."
 
-// Deep clone object
-const originalData = { user: { name: "John", settings: { theme: "dark" } } }
-const clonedData = deepClone(originalData)
+// Safe JSON-LD for <script type="application/ld+json">
+const jsonLd = serializeJsonLd({ "@type": "WebSite", name: "</script>attack" })
+// → '{"@type":"WebSite","name":"\\u003c/script>attack"}'
 
-// Get Slack URL
-const slackUrl = getSlackCommunityJoinUrl() // Returns env var or fallback URL
-```
+// Deep clone without reference sharing
+const copy = deepClone({ nested: { value: 42 } })
+
+// Slack community URL (set via env or uses OpenMSP fallback)
+const slackUrl = getSlackCommunityJoinUrl()
+```
+
+> **Security note:** `serializeJsonLd` must be used for all `<script type="application/ld+json">` blocks. Raw `JSON.stringify` does not HTML-escape `<`, leaving stored XSS vectors open if user-entered data reaches the schema object.
+
+## Source
+
+[`common.ts` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/common.ts)

package/src/utils/.content-href.md

@@ -0,0 +1,64 @@
+<!-- source-hash: 235fea62f64e91dc73029934b22d60cc -->
+Unified content-href authority for all embeddable surfaces — resolves content links consistently across both page views and chat surfaces using a single configurable seam.
+
+## Key Components
+
+### Constants
+
+- **`DEFAULT_CONTENT_SUFFIXES`** — Maps content `documentType` strings (e.g. `'product_release'`, `'blog_post'`) to their URL path segments. Mirrors the hub's `PUBLIC_URL_PATHS`; kept in sync manually across the cross-repo boundary.
+
+### Types
+
+- **`ComposeContentUrlInput`** — Unified input for both page views (slug-based) and chat rows (ID + `externalUrl`-based).
+- **`ContentHrefOptions`** — Configuration for `makeComposeContentUrl`: hosted types set, hub origin fallback, optional suffix/override maps.
+- **`ComposeContentUrl`** — The seam function signature on `ChatRuntime`; always returns `{ href, targetPlatform }`, never null.
+
+### Functions
+
+- **`makeComposeContentUrl(opts)`** — Factory that builds the embedder's `composeContentUrl`. Resolution order: explicit `overrides` → hosted in-app route → verbatim `externalUrl` → hub-origin fallback.
+- **`buildDefaultHref(basePath, slug)`** — Fallback href when no `composeContentUrl` is wired (single-platform embedders).
+- **`resolveContentHref(composeContentUrl, args)`** — Ternary helper used by catalog/detail views: delegates to `composeContentUrl` when wired, otherwise calls `buildDefaultHref`.
+
+## Usage Example
+
+```typescript
+import {
+  makeComposeContentUrl,
+  resolveContentHref,
+} from './content-href'
+
+// Build the embedder's composer
+const composeContentUrl = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: 'https://openframe.app',
+  overrides: {
+    author: (id) => ({ href: `/team/${id}`, targetPlatform: null }),
+  },
+})
+
+// Page view — slug passed directly as identifier
+composeContentUrl({ type: 'product_release', identifier: 'my-release-v2' })
+// → { href: '/releases/my-release-v2', targetPlatform: null }
+
+// Chat row — id as identifier, slug recovered from externalUrl
+composeContentUrl({
+  type: 'product_release',
+  identifier: 'abc123',
+  externalUrl: 'https://openframe.app/releases/my-release-v2',
+})
+// → { href: '/releases/my-release-v2', targetPlatform: null }
+
+// Non-hosted type — opens out to hub
+composeContentUrl({ type: 'blog_post', identifier: 'my-post' })
+// → { href: 'https://openframe.app/blog/my-post', targetPlatform: null }
+
+// Catalog/detail view helper
+resolveContentHref(composeContentUrl, {
+  type: 'onboarding_guide',
+  slug: 'getting-started',
+  basePath: '/onboarding-guides',
+})
+// → { href: '/onboarding-guides/getting-started', targetPlatform: null }
+```
+
+**Source:** [`content-href.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/content-href.ts)

package/src/utils/.content-ref-groups.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 0fe0f3b3b32e9874a82e09c286bf0512 -->
+Single source of truth for grouping `content_ref` types with display metadata (label, render order, layout, and card size). Consumed by the `RelatedContentSection` component and the hub's investor email builder to ensure consistent rendering and ordering across surfaces.
+
+## Key Components
+
+### Types
+
+- **`ContentRefLayout`** — `'list' | 'grid'`; controls whether a group renders as full-width cards or a responsive column grid.
+- **`ContentRefGridSize`** — `'lg' | 'default' | 'sm'`; card size variant forwarded to the entity-card dispatch. Kept in lockstep with `EntityCardSize` to avoid a config→component import cycle.
+- **`ContentRefGroupConfig`** — shape of each entry: `label`, `order`, `layout`, `gridSize`.
+
+### Constants
+
+- **`CONTENT_REF_GROUPS`** — registry of all known `content_ref` types (`investor_update`, `product_release`, `podcast`, `webinar`, `case_study`, `event`, `blog_post_existing`, `customer_interview`, `onboarding_guide`, `what_i_shipped`). Adding one entry here auto-registers the type in `RelatedContentSection` and makes it a hub suggestion candidate (if resolvable via `TYPE_TO_ENTITY` → RAG config).
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `getContentRefLabel(type)` | Returns the registered label or `null` for unknown types. |
+| `getContentRefLabelOrTitleCase(type)` | Returns the registered label or a title-cased fallback (e.g. `"podcast_guest"` → `"Podcast Guest"`). |
+| `orderContentRefTypes(present)` | Sorts a set of present types into canonical `order` sequence; unregistered types are appended in insertion order. |
+
+## Usage Example
+
+```typescript
+import {
+  CONTENT_REF_GROUPS,
+  getContentRefLabelOrTitleCase,
+  orderContentRefTypes,
+} from '@openframe-oss-lib/utils/content-ref-groups'
+
+// Render groups in canonical order
+const types = ['blog_post_existing', 'podcast', 'custom_type']
+const sorted = orderContentRefTypes(types)
+// → ['podcast', 'blog_post_existing', 'custom_type']
+
+for (const type of sorted) {
+  const config = CONTENT_REF_GROUPS[type]
+  const label = getContentRefLabelOrTitleCase(type)
+  // config?.layout === 'list' | 'grid' | undefined for unregistered
+  console.log(label, config?.layout)
+}
+
+// Adding a new content type — one entry is all that's needed:
+// CONTENT_REF_GROUPS['press_release'] = {
+//   label: 'Press Releases', order: 11, layout: 'list', gridSize: 'lg'
+// }
+```
+
+> **Extending:** Add new content types directly to `CONTENT_REF_GROUPS`. Prefer `gridSize: 'lg'` for types whose card component has a large variant. No other file needs updating for `RelatedContentSection` to pick up the new group.

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

@@ -1,45 +1,56 @@
-<!-- source-hash: 7776194e73c7d80a24debaa33cab9591 -->
-Unified date formatting utilities that provide consistent timestamp handling and display formatting across the OpenMSP platform. This module serves as the single source of truth for all date and time operations.
+<!-- source-hash: c0ca2308274869b5506bb1e4854c772e -->
+Unified date formatting utilities for the OpenMSP platform, providing consistent timestamp display across all components with built-in SSR/hydration safety (React #418) via UTC-pinned date operations.
 
 ## Key Components
 
-- `formatRelativeTime()` - Primary relative time formatter (e.g., "2h ago", "3d ago")
-- `formatAbsoluteDate()` - Absolute date formatting with customizable options
-- `formatDateTime()` - Combined date and time formatting
-- `getDetailedTimeDifference()` - Verbose time difference descriptions
-- `isToday()` - Check if timestamp is within current day
-- `isWithinMinutes()` - Check if timestamp is within specified time window
-- `createUTCTimestamp()` - Generate UTC timestamp strings for database storage
+| Function | Description |
+|---|---|
+| `formatTicketRelativeTime(iso)` | Ticket-specific relative label: "Just now" / "X min ago" / "X hour(s) ago" / "MM/DD/YYYY" |
+| `formatTicketFullTimestamp(iso)` | Full tooltip timestamp in `MM/DD/YYYY, H:MM AM/PM` format |
+| `formatRelativeTime(timestamp)` | General-purpose relative time: "Just now" → "Xm/h/d/w ago" → localized date (source of truth) |
+| `formatAbsoluteDate(timestamp, options?)` | Localized absolute date via `Intl.DateTimeFormatOptions`, UTC-pinned |
+| `formatDateTime(timestamp, options?)` | Localized date + time via `Intl.DateTimeFormatOptions`, UTC-pinned |
+| `getDetailedTimeDifference(timestamp)` | Verbose elapsed time: "X seconds/minutes/hours/days/months/years ago" |
+| `isToday(timestamp)` | Returns `true` if the timestamp falls on today's local date |
+| `isWithinMinutes(timestamp, minutes)` | Returns `true` if the timestamp is within the last N minutes |
+| `createUTCTimestamp()` | Returns current UTC time as an ISO string for database insertion |
 
 ## Usage Example
 
 ```typescript
-import { 
-  formatRelativeTime, 
-  formatAbsoluteDate, 
+import {
+  formatRelativeTime,
+  formatAbsoluteDate,
   formatDateTime,
-  isWithinMinutes 
-} from './date-utils';
-
-// Relative time formatting (most common use case)
-const postTime = formatRelativeTime('2024-01-01T12:00:00Z');
-// Returns: "2h ago", "3d ago", or "Jan 1" for older dates
-
-// Absolute date formatting
-const eventDate = formatAbsoluteDate('2024-06-15T10:30:00Z');
-// Returns: "Jun 15, 2024"
-
-// Date with time
-const fullDateTime = formatDateTime('2024-06-15T10:30:00Z');
-// Returns: "Jun 15, 2024 at 10:30 AM"
-
-// Check recent activity
-const isRecent = isWithinMinutes('2024-01-01T12:00:00Z', 30);
-// Returns: true if within last 30 minutes
-
-// Generate database timestamp
-const dbTimestamp = createUTCTimestamp();
-// Returns: "2024-01-01T12:00:00.000Z"
+  formatTicketRelativeTime,
+  formatTicketFullTimestamp,
+  getDetailedTimeDifference,
+  isToday,
+  isWithinMinutes,
+  createUTCTimestamp,
+} from './date-utils'
+
+// Relative time (general use)
+formatRelativeTime('2024-01-01T12:00:00Z')  // 'Jan 1, 2024'
+formatRelativeTime(new Date())               // 'Just now'
+formatRelativeTime('2024-06-15T10:30:00Z')  // '3h ago'
+
+// Ticket timestamps (UI list / tooltip)
+formatTicketRelativeTime('2024-06-15T10:30:00Z')  // '3 hours ago' or '06/15/2024'
+formatTicketFullTimestamp('2024-06-15T10:30:00Z') // '06/15/2024, 10:30 AM'
+
+// Absolute and datetime formatting
+formatAbsoluteDate('2024-06-15T10:30:00Z')                       // 'Jun 15, 2024'
+formatAbsoluteDate('2024-06-15T10:30:00Z', { month: 'long' })   // 'June 15, 2024'
+formatDateTime('2024-06-15T10:30:00Z')                           // 'Jun 15, 2024, 10:30 AM'
+
+// Verbose elapsed time
+getDetailedTimeDifference('2024-06-14T08:00:00Z') // '2 days ago'
+
+// Guards and utilities
+isToday(new Date())                          // true
+isWithinMinutes('2024-06-15T10:29:00Z', 5)  // true (if within 5 min)
+createUTCTimestamp()                         // '2024-06-15T10:30:00.000Z'
 ```
 
-All functions handle invalid dates gracefully with console warnings and fallback values. The `formatRelativeTime()` function automatically switches to absolute dates for content older than 30 days to maintain readability.
+> **SSR Safety:** All functions use UTC getters or `timeZone: 'UTC'` to ensure server-rendered output matches client hydration and avoids React hydration mismatch [#418](https://github.com/flamingo-stack/openframe-oss-lib/issues/418).

package/src/utils/.doc-path-utils.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 522b22b251e1243bc131056859525baa -->
+Shared utility module providing path and slug operations for document source viewers (knowledge base, data room, etc.), serving as the single source of truth for path normalization across route handlers.
+
+## Key Components
+
+| Export | Signature | Purpose |
+|--------|-----------|---------|
+| `toDocSlug` | `(name: string) => string` | Converts a display name to a URL-safe slug |
+| `pathToNodeId` | `(path: string) => string` | Converts a file path to a DOM-safe node ID |
+| `normalizeDocPath` | `(segments: string[], folderIndexFile?: string) => string` | Normalizes URL path segments, stripping folder-index suffixes |
+
+## Usage Example
+
+```typescript
+import { toDocSlug, pathToNodeId, normalizeDocPath } from './doc-path-utils'
+
+// Convert document name to URL slug
+toDocSlug('Investor Thesis')       // → "investor-thesis"
+toDocSlug('  Cap Table  ')         // → "cap-table"
+
+// Convert file path to a DOM-safe tree node ID
+pathToNodeId('legal/cap-table/safe.md')  // → "legal-cap-table-safe.md"
+
+// Normalize route segments, stripping README.md index suffixes
+normalizeDocPath(['legal', 'cap-table'])           // → "legal/cap-table"
+normalizeDocPath(['legal', 'cap-table', 'README.md']) // → "legal/cap-table"
+normalizeDocPath(['README.md'])                    // → ""
+
+// Override the default folder-index filename
+normalizeDocPath(['docs', 'index.md'], 'index.md') // → "docs"
+```
+
+## Notes
+
+- `normalizeDocPath` lowercases **both** the input segments and the `folderIndexFile` constant before comparison, ensuring URLs like `readme.md` and `README.md` strip uniformly.
+- `DEFAULT_FOLDER_INDEX_FILE` is imported from `doc-tree-nav` and used as the default `folderIndexFile` argument.
+
+**Source:** [`doc-path-utils.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/doc-path-utils.ts)

package/src/utils/.doc-tree-nav.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 8886b4928afb072c5436308281384b36 -->
+Pure navigation helpers for traversing and resolving paths within a `DocNode` tree — shared between client-side hooks and server-side RSC rendering.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `DEFAULT_FOLDER_INDEX_FILE` | `const` | Canonical folder-index filename (`'README.md'`); single source of truth across navigation, SEO, and fetch logic |
+| `stripFolderIndexFromPath` | function | Normalizes a file path by removing the trailing folder-index filename, returning the logical folder path |
+| `findDocNodeByPath` | function | Recursively searches a `DocNode[]` tree for a node matching the given path |
+| `getDocAncestorNodeIds` | function | Converts a slash-delimited node path into DOM-style IDs for each ancestor segment (used to pre-open accordion sidebar) |
+| `resolveContentFetchPath` | function | Determines the actual storage path to fetch for a selected node, handling folder README resolution and no-content folders |
+| `getInitialExpandedNodeIds` | function | Derives the set of accordion node IDs that should be expanded on initial load for a given path |
+| `getDocSourceDefaultPath` | function | Finds the first root-level folder with a README when the tree root itself has no index file |
+
+## Usage Example
+
+```typescript
+import {
+  stripFolderIndexFromPath,
+  findDocNodeByPath,
+  resolveContentFetchPath,
+  getInitialExpandedNodeIds,
+  getDocSourceDefaultPath,
+} from './doc-tree-nav'
+
+// Normalize a path for display or URL routing
+stripFolderIndexFromPath('guides/README.md') // → 'guides'
+stripFolderIndexFromPath('README.md')        // → ''
+
+// Find a node in the tree
+const node = findDocNodeByPath('guides/quickstart', docStructure)
+
+// Resolve what to actually fetch from storage
+const fetchPath = resolveContentFetchPath('guides', docStructure)
+// → 'guides/README.md' if the folder has hasReadme: true
+
+// Expand ancestor accordions for a deep initial path
+const openIds = getInitialExpandedNodeIds('guides/setup/install.md')
+// → ['guides', 'guides-setup']
+
+// Jump to the first meaningful default when root has no README
+const defaultPath = getDocSourceDefaultPath(docStructure)
+// → 'guides' (first folder with hasReadme: true)
+```
+
+## Notes
+
+- All functions accept an optional `folderIndexFile` parameter (defaults to `DEFAULT_FOLDER_INDEX_FILE`) to support non-standard folder-index conventions.
+- `DEFAULT_FOLDER_INDEX` is exported as a deprecated alias — migrate consumers to `DEFAULT_FOLDER_INDEX_FILE`.
+- `resolveContentFetchPath` returns `null` for folders with no README, signaling the UI to suppress a fetch attempt.

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)