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

package/src/utils/.cn.md

@@ -1,44 +1,55 @@
-<!-- source-hash: c1693a304ddf9b29bde0ca02b6f6b8ea -->
-Utility module providing class name merging with extended Tailwind support, and platform URL resolution helpers for multi-tenant Flamingo/OpenFrame deployments.
+<!-- source-hash: 700d6c65ebfb65630e665b437acf4e83 -->
+Utility module providing two core helpers: a Tailwind-aware class name merger (`cn`) that correctly handles custom ODS typography utilities, and an environment-aware base URL resolver (`getBaseUrl`) that delegates platform canonical URLs to the SSOT in `platform-domains.ts`.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `cn` | Function | Merges class names using `clsx` + `tailwind-merge`, extended with custom ODS typography classes (`text-h1`–`text-h6`) |
-| `getPlatformProductionUrl` | Function | Returns the production URL for a named platform, with `NEXT_PUBLIC_*` env var override support |
-| `getAllPlatformBaseDomains` | Function | Extracts all unique base domains across platforms; handles localhost, Vercel preview, and production cases (useful for cross-domain cookie scope) |
-| `getBaseUrl` | Function | Resolves the current app's base URL using a priority chain: env override → platform URL → Vercel domain → production fallback → `localhost:3000` |
+| `cn` | `function` | Combines class names using `clsx` + a custom `tailwind-merge` instance |
+| `getBaseUrl` | `function` | Returns the application base URL for the current environment |
+| `twMerge` | internal | Extended `tailwind-merge` instance with the `ods-typography` class group |
+
+### `ods-typography` Class Group
+
+Custom Tailwind text-size utilities registered to prevent silent conflicts with `text-color` utilities:
+
+```text
+text-h1 · text-h2 · text-h3 · text-h4 · text-h5 · text-h6 · text-code · text-badge
+```
+
+Without this registration, `cn('text-badge', 'text-ods-text-on-accent')` would drop `text-badge` — only the colour survives.
 
 ## Usage Example
 
 ```typescript
-import { cn, getBaseUrl, getPlatformProductionUrl, getAllPlatformBaseDomains } from '@/lib/cn'
-
-// Merge Tailwind classes (including custom ODS typography)
-const className = cn('text-h1 font-bold', isActive && 'text-yellow-400')
+import { cn, getBaseUrl } from '@/lib/cn'
 
-// Resolve current app base URL
-const apiBase = getBaseUrl()                      // http://localhost:3000 (dev)
-                                                  // https://www.openmsp.ai (prod fallback)
+// Merge conditional classes safely — typography and colour both survive
+const className = cn(
+  'text-badge',
+  'text-ods-text-on-accent',
+  isActive && 'bg-accent',
+)
 
-// Resolve a specific platform URL (respects NEXT_PUBLIC_* overrides)
-const flamingoUrl = getBaseUrl('flamingo')        // https://www.flamingo.run
-const openframeUrl = getPlatformProductionUrl('openframe') // https://openframe.ai
+// Current deployment URL (dev → localhost, prod → Vercel/canonical domain)
+const currentUrl = getBaseUrl()
 
-// Get all cookie-scoped base domains (e.g. for document.cookie domain=)
-const domains = getAllPlatformBaseDomains()
-// Production: ['.flamingo.run', 'flamingo.run', '.openmsp.ai', 'openmsp.ai', ...]
-// Vercel preview: ['.vercel.app', 'vercel.app']
-// Localhost: []
+// Specific platform URL (respects env override, falls back to canonical)
+const flamingoUrl = getBaseUrl('flamingo')  // https://www.flamingo.run
+const openMspUrl  = getBaseUrl('openmsp')   // https://www.openmsp.ai
 ```
 
-## Environment Variables
+## `getBaseUrl` Resolution Order
+
+```mermaid
+graph TD
+    A[getBaseUrl called] --> B{NODE_ENV !== production?}
+    B -->|Yes| C[NEXT_PUBLIC_DEV_URL or localhost:3000]
+    B -->|No| D{platform arg provided?}
+    D -->|Yes| E[getPlatformProductionUrl from SSOT]
+    D -->|No| F{VERCEL_PROJECT_PRODUCTION_URL set?}
+    F -->|Yes| G[https://vercel-domain]
+    F -->|No| H[getPlatformProductionUrl via NEXT_PUBLIC_APP_TYPE]
+```
 
-| Variable | Platform | Default |
-|----------|----------|---------|
-| `NEXT_PUBLIC_FLAMINGO_URL` | `flamingo`, `universal` | `https://www.flamingo.run` |
-| `NEXT_PUBLIC_OPENMSP_URL` | `openmsp` | `https://www.openmsp.ai` |
-| `NEXT_PUBLIC_OPENFRAME_URL` | `openframe` | `https://openframe.ai` |
-| `NEXT_PUBLIC_MARKETING_HUB_URL` | `marketing-hub` | `https://marketing-hub.flamingo.so` |
-| `NEXT_PUBLIC_DEV_URL` | all (dev only) | `http://localhost:3000` |
+> Platform canonical URLs and their `NEXT_PUBLIC_*_URL` environment overrides are defined exclusively in [`src/platform-domains.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/platform-domains.ts).

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.