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

package/src/utils/.markdown-to-plain.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 565bab727ed764f8f2e7853cc222b4d8 -->
+Converts Markdown source to plain text with two output modes: structured article text (preserving paragraph breaks) and collapsed single-line preview text.
+
+## Key Components
+
+### `MarkdownToPlainOptions`
+Configuration interface with two optional properties:
+- `mode`: `'article'` (default) preserves `\n\n` paragraph structure; `'preview'` collapses all whitespace to a single line
+- `maxChars`: Optional character cap — truncates without ellipsis (caller decides truncation presentation)
+
+### `stripInlineMarkdown(s: string): string`
+Shared utility that strips inline Markdown markers from a string:
+- `[text](url)` → `text`
+- `**bold**` → `bold`
+- `*italic*` → `italic`
+- `` `inline code` `` → `inline code`
+
+All patterns use negated character classes to avoid catastrophic backtracking.
+
+### `markdownToPlainText(markdown, options): string`
+Main conversion function. Processing order matters — fenced code blocks and images are stripped first (before inline backtick stripping could interfere), then `stripInlineMarkdown` runs, followed by heading markers and list bullets. Final pass applies mode-specific whitespace normalization and optional character truncation.
+
+## Usage Example
+
+```typescript
+import { markdownToPlainText, stripInlineMarkdown } from './markdown-to-plain'
+
+// Article mode — preserves paragraph breaks (e.g. JSON-LD body echo)
+const articleText = markdownToPlainText(`
+# Getting Started
+Install with **npm** or \`yarn\`.
+
+- Clone the repo
+- Run \`npm install\`
+`)
+// → "Getting Started\nInstall with npm or yarn.\n\nClone the repo\nRun npm install"
+
+// Preview mode — single line for chat cards / OG snippets
+const preview = markdownToPlainText(markdownSource, {
+  mode: 'preview',
+  maxChars: 160,
+})
+
+// Standalone inline strip (e.g. inside extractSections)
+const clean = stripInlineMarkdown('**Bold** and [a link](https://example.com)')
+// → "Bold and a link"
+```
+
+## Source
+
+[`markdown-to-plain.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/markdown-to-plain.ts)

package/src/utils/.media-carousel-utils-stub.md

@@ -1,38 +1,49 @@
-<!-- source-hash: 32a85dbde6926a50b796aea0a1880802 -->
-A utility module that defines the core data structure and helper functions for handling different types of media items in carousel components.
+<!-- source-hash: f4d365e1aafe7c4342c44a64be1e2e6e -->
+Defines the shared `MediaItem` data contract and lightweight accessor utilities used by media carousel components across the OpenFrame platform.
 
 ## Key Components
 
-- **`MediaItem` interface**: Comprehensive type definition for media objects supporting images, videos, and YouTube content with optional metadata like captions, dimensions, and duration
-- **`getMediaType()`**: Returns the media type ('image', 'video', or 'youtube') for a given media item
-- **`getMediaSrc()`**: Extracts the source URL from a media item
-- **`getMediaPoster()`**: Retrieves the poster/thumbnail URL for video content
+### `MediaItem` Interface
+
+Core data shape for a single carousel slide. Supports three media types:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string?` | Optional stable key (omitted by most vendor/profile/category converters) |
+| `type` | `'image' \| 'video' \| 'youtube'` | Media kind — drives rendering strategy |
+| `src` | `string` | Media source URL |
+| `alt` | `string?` | Accessibility alt text |
+| `title` | `string?` | Display title |
+| `caption` | `string?` | Slide caption |
+| `poster` | `string?` | Video poster/placeholder image |
+| `thumbnail` | `string?` | Thumbnail URL |
+| `width` / `height` | `number?` | Intrinsic dimensions |
+| `duration` | `number?` | Video duration in seconds |
+
+### Accessor Functions
+
+| Function | Returns | Description |
+|---|---|---|
+| `getMediaType(item)` | `'image' \| 'video' \| 'youtube'` | Extracts the media type from an item |
+| `getMediaSrc(item)` | `string` | Extracts the source URL |
+| `getMediaPoster(item)` | `string \| undefined` | Extracts the video poster image URL |
 
 ## Usage Example
 
 ```typescript
-import { MediaItem, getMediaType, getMediaSrc } from './media-carousel-utils-stub';
-
-const mediaItems: MediaItem[] = [
-  {
-    id: '1',
-    type: 'image',
-    src: '/images/photo.jpg',
-    alt: 'Sample photo',
-    width: 1920,
-    height: 1080
-  },
-  {
-    id: '2',
-    type: 'video',
-    src: '/videos/demo.mp4',
-    poster: '/thumbnails/demo.jpg',
-    duration: 120
-  }
-];
-
-// Get media type and source
-const firstItem = mediaItems[0];
-const type = getMediaType(firstItem); // 'image'
-const src = getMediaSrc(firstItem); // '/images/photo.jpg'
-```
+import { MediaItem, getMediaType, getMediaSrc, getMediaPoster } from './media-carousel-utils-stub';
+
+const slide: MediaItem = {
+  type: 'video',
+  src: 'https://cdn.example.com/clip.mp4',
+  poster: 'https://cdn.example.com/thumb.jpg',
+  title: 'Product Demo',
+  duration: 120,
+};
+
+const type = getMediaType(slide);   // 'video'
+const src = getMediaSrc(slide);     // 'https://cdn.example.com/clip.mp4'
+const poster = getMediaPoster(slide); // 'https://cdn.example.com/thumb.jpg'
+```
+
+> **Note:** The carousel keys slides by array index rather than `item.id`. Converters (hub vendor, profile, and category) conventionally omit the `id` field.

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

@@ -1,27 +1,48 @@
-<!-- source-hash: 8d0a4e249109b10a270ca0755176abc6 -->
-Runtime utility library for working with ODS (OpenFrame Design System) color tokens, providing platform-aware theming, token lookup, CSS generation, and React integration helpers.
+<!-- source-hash: 67651d104f2d85ae6efdf60affb29813 -->
+Runtime utilities for working with ODS (OpenFrame Design System) color tokens, providing platform-aware color resolution, CSS custom property management, and color math helpers for the `openmsp`, `openframe`, and `flamingo` platforms.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `Platform` | Type | Union of `'openmsp' \| 'openframe' \| 'flamingo'` |
-| `ColorCategory` | Type | Union of `'open' \| 'flamingo' \| 'system' \| 'attention'` |
-| `ColorVariant` | Type | Union of `'base' \| 'hover' \| 'active' \| 'focus' \| 'disabled'` |
-| `getODSToken` | Function | Looks up a raw token value by category, color name, and variant |
-| `getPlatformAccentColor` | Function | Returns the CSS variable for the current or specified platform's accent color |
-| `getCurrentPlatform` | Function | Resolves platform from DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var |
-| `switchPlatformTheme` | Function | Updates `data-app-type` on `<html>` and dispatches `platformThemeChanged` event |
-| `getSemanticColor` | Function | Reads a computed `--color-*` CSS property for a given platform |
-| `tokenToTailwindClass` | Function | Maps a semantic token key to its corresponding Tailwind utility class |
-| `getTokensByCategory` | Function | Returns all tokens matching a given `ColorCategory` prefix |
-| `isValidODSToken` | Function | Checks whether a token key exists in the ODS token map |
-| `getPlatformConfig` | Function | Returns a config object with accent color, theme type, and brand name |
-| `generatePlatformCSS` | Function | Builds a CSS block of custom property overrides for a platform |
-| `applyColorToken` | Function | Directly sets a CSS custom property on an `HTMLElement` |
-| `interpolateColors` | Function | Linearly interpolates between two hex ODS tokens by progress (0–1) |
-| `usePlatformColors` | Function | React-friendly helper returning platform config and token accessors |
-| `getReadableTextColor` | Function | Returns `#212121` or `#fafafa` based on Rec. 601 luminance of a hex color |
+### Types
+
+| Type | Values |
+|---|---|
+| `Platform` | `'openmsp'` \| `'openframe'` \| `'flamingo'` |
+| `ColorCategory` | `'open'` \| `'flamingo'` \| `'system'` \| `'attention'` |
+| `ColorVariant` | `'base'` \| `'hover'` \| `'active'` \| `'focus'` \| `'disabled'` |
+
+### Token Lookup
+
+- **`getODSToken(category, color, variant?)`** — Resolves a raw token value by composing the key as `{category}-{color}-{variant}`.
+- **`getTokensByCategory(category)`** — Returns all tokens matching a category prefix.
+- **`isValidODSToken(tokenKey)`** — Validates token existence in the ODS registry.
+
+### Platform & Theme
+
+- **`getCurrentPlatform()`** — Resolves the active platform from `data-app-type` DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var (SSR-safe).
+- **`getPlatformAccentColor(platform?)`** — Returns the CSS variable for the platform accent color.
+- **`getPlatformConfig(platform?)`** — Returns a config object with accent color, theme mode, and brand name.
+- **`switchPlatformTheme(platform)`** — Updates `data-app-type` on `<html>` and dispatches a `platformThemeChanged` custom event.
+- **`generatePlatformCSS(platform)`** — Generates a CSS block with platform-scoped custom property overrides.
+
+### Color Math
+
+- **`hexToRgb(hex)`** / **`rgbToHex(r, g, b)`** — Hex ↔ RGB conversion with clamping. `hexToRgb` returns `null` on invalid input.
+- **`rgbToHsl(r, g, b)`** / **`hslToRgb(h, s, l)`** — RGB ↔ HSL conversion.
+- **`deriveHoverColor(hex)`** — Darkens each channel by 10.
+- **`deriveActiveColor(hex)`** — Darkens each channel by 20.
+- **`interpolateColors(startToken, endToken, progress)`** — Linear hex interpolation between two token values.
+- **`getReadableTextColor(hex)`** — Returns `'#212121'` (dark) or `'#fafafa'` (light) based on WCAG luminance via `pickReadableTextColor`.
+
+### Tailwind & DOM Helpers
+
+- **`tokenToTailwindClass(tokenKey, type?)`** — Maps a semantic token name to a Tailwind class (e.g., `bg-ods-accent`).
+- **`applyColorToken(element, property, tokenKey)`** — Sets a CSS custom property directly on an element.
+- **`getSemanticColor(semanticName, platform?)`** — Reads a computed `--color-{name}` value from the live DOM.
+
+### React Hook
+
+- **`usePlatformColors(platform?)`** — Returns a platform config object plus convenience methods (`getToken`, `switchTheme`, `getSemanticColor`) suitable for use in React components.
 
 ## Usage Example
 
@@ -30,42 +51,62 @@ import {
   getCurrentPlatform,
   getPlatformConfig,
   getODSToken,
-  tokenToTailwindClass,
-  interpolateColors,
+  deriveHoverColor,
   getReadableTextColor,
-  usePlatformColors,
-  switchPlatformTheme
+  tokenToTailwindClass,
+  hexToRgb,
+  rgbToHex,
 } from './ods-color-utils';
 
-// Resolve the active platform (SSR + CSR safe)
+// Resolve active platform and config
 const platform = getCurrentPlatform(); // 'openframe'
-
-// Get full platform configuration
 const config = getPlatformConfig(platform);
-// { platform: 'openframe', accentColor: 'var(--ods-open-yellow-base)',
-//   isDarkTheme: true, isLightTheme: false, brandName: 'OpenFrame' }
+// {
+//   platform: 'openframe',
+//   accentColor: 'var(--ods-open-yellow-base)',
+//   isDarkTheme: true,
+//   isLightTheme: false,
+//   brandName: 'OpenFrame'
+// }
+
+// Look up a raw ODS token
+const yellowBase = getODSToken('open', 'yellow', 'base'); // '#f5c518'
 
-// Look up a raw design token
-const tokenValue = getODSToken('system', 'greys-background', 'base');
+// Derive interaction states from a custom hex color
+const customBg = '#3a7bd5';
+const hoverBg = deriveHoverColor(customBg);   // '#306bcb' (–10 per channel)
+const activeBg = deriveActiveColor(customBg); // '#275bb5' (–20 per channel)
 
-// Map a semantic token to a Tailwind class
-const twClass = tokenToTailwindClass('text-primary', 'text');
-// → 'text-ods-text-primary'
+// Pick accessible text color over a background
+const textColor = getReadableTextColor(customBg); // '#fafafa'
 
-// Interpolate between two hex tokens (e.g. for animations)
-const midColor = interpolateColors('open-yellow-base', 'flamingo-pink-base', 0.5);
+// Map a semantic token to a Tailwind utility class
+const bgClass = tokenToTailwindClass('accent-primary', 'bg'); // 'bg-ods-accent'
 
-// Ensure readable text on a dynamic background
-const textColor = getReadableTextColor('#FFC008'); // → '#212121'
+// Low-level color math
+const rgb = hexToRgb('#ff6600'); // { r: 255, g: 102, b: 0 }
+const hex = rgbToHex(255, 102, 0); // '#ff6600'
 
-// Switch platform at runtime (updates <html data-app-type> + fires event)
-switchPlatformTheme('flamingo');
+// Switch platform theme at runtime (client-side only)
+import { switchPlatformTheme } from './ods-color-utils';
+switchPlatformTheme('flamingo'); // sets data-app-type="flamingo", dispatches event
+
+// React usage
+import { usePlatformColors } from './ods-color-utils';
 
-// React component usage
 function MyComponent() {
   const { accentColor, isDarkTheme, getToken, switchTheme } = usePlatformColors();
   return <div style={{ color: accentColor }}>{isDarkTheme ? 'Dark' : 'Light'}</div>;
 }
 ```
 
-> **Note:** `getSemanticColor` and `applyColorToken` are browser-only — they return `undefined` or no-op on the server. `switchPlatformTheme` cannot persist `process.env` changes in production; use it for UI-layer toggling only.
+## Notes
+
+- **SSR-safe**: Functions that touch `window` or `document` guard with `typeof window === 'undefined'` checks.
+- **`HEX_PATTERN`** (`/^#[0-9a-fA-F]{6}$/`) is exported for external validation.
+- Hover/active darken steps (`10` / `20` per RGB channel) mirror the design system's preset interaction states, keeping custom colors consistent with system tokens.
+- `getSemanticColor` temporarily switches the platform theme to read computed styles — avoid calling it in hot paths.
+
+## Source
+
+[`ods-color-utils.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ods-color-utils.ts)

package/src/utils/.og-placeholder.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 89ad4456d6f452acc2ba185db7b6f3b5 -->
+Constructs branded fallback cover-image URLs for entity cards (onboarding guides, blog posts, releases, etc.) that have no image, centralizing all URL-building logic so consumers never concatenate og-placeholder URLs themselves.
+
+## Key Components
+
+### Interfaces
+
+- **`OgPlaceholderEndpoints`** — Slice of `ChatRuntime.endpoints` needed for base URL resolution; accepts `ogPlaceholderUrl` (explicit) or `imageProxyUrlPrefix` (derived fallback).
+- **`BuildOgPlaceholderOptions`** — Options for `site` label, `aspect` ratio (`'wide'` | `'square'`), and explicit `width`/`height` pixel overrides.
+
+### Functions
+
+- **`resolveOgPlaceholderBase(endpoints?)`** *(internal)* — Resolves the route base via three-tier priority: explicit `ogPlaceholderUrl` → derived from `imageProxyUrlPrefix` (swaps `/image-proxy` for `/og-placeholder`) → same-origin relative `/api/og-placeholder`.
+- **`buildOgPlaceholderUrl(endpoints, title, options?)`** — Primary entry point. Resolves the base URL, preserves any pre-existing query params, and appends `title`, `site`, and dimension params. SSR- and browser-safe; always returns a usable URL.
+
+## Usage Example
+
+```typescript
+import { buildOgPlaceholderUrl } from './og-placeholder'
+
+const endpoints = {
+  imageProxyUrlPrefix: 'https://api.example.com/image-proxy',
+}
+
+// Wide fallback (1200×630, route default)
+const wideUrl = buildOgPlaceholderUrl(endpoints, 'Getting Started Guide', {
+  site: 'Docs',
+  aspect: 'wide',
+})
+// → https://api.example.com/og-placeholder?title=Getting+Started+Guide&site=Docs
+
+// Square fallback for compact chat-inline slots (1024×1024)
+const squareUrl = buildOgPlaceholderUrl(endpoints, 'Release v2.0', {
+  aspect: 'square',
+})
+// → https://api.example.com/og-placeholder?title=Release+v2.0&w=1024&h=1024
+
+// Explicit dimensions win over aspect
+const customUrl = buildOgPlaceholderUrl(endpoints, 'Case Study', {
+  width: 800,
+  height: 400,
+})
+```
+
+**Base resolution priority:** `ogPlaceholderUrl` → derived from `imageProxyUrlPrefix` → `/api/og-placeholder` (same-origin fallback). Per-platform brand colors are resolved server-side — never baked into the URL.

package/src/utils/.page-header-constants.md

@@ -0,0 +1,26 @@
+<!-- source-hash: 9edb965a12c9dd5942bb4987087d4fed -->
+Exports a single Tailwind class string used to standardize icon styling across all section-hero and page-header components in the library. Intentionally placed in `utils/` as a plain server-safe module (no `'use client'` directive) to prevent Next.js client-reference proxy issues when the constant is consumed by server components.
+
+## Key Components
+
+- **`SECTION_HERO_ICON_CLASS`** — Tailwind class string (`'h-10 w-10 text-ods-accent'`) applied uniformly to every section-hero icon (Roadmap, Releases, Knowledge Hub, Data Room, etc.)
+
+## Usage Example
+
+```typescript
+import { SECTION_HERO_ICON_CLASS } from './page-header-constants'
+import { BookOpen } from 'lucide-react'
+
+// Server component — safe to import directly
+export function KnowledgeHubHero() {
+  return <BookOpen className={SECTION_HERO_ICON_CLASS} />
+}
+```
+
+## Why Not `'use client'`?
+
+Importing this constant from a `'use client'` module causes Next.js to wrap it in a **client-reference proxy** when consumed in a server context. Lucide's internal `mergeClasses` then calls `.trim()` on that proxy object instead of a plain string, resulting in a runtime crash. Keeping this file in `utils/` with no client directive ensures it always resolves to a raw string in all rendering contexts.
+
+## Source
+
+[`page-header-constants.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/page-header-constants.ts)

package/src/utils/.platform-config.md

@@ -1,57 +1,57 @@
-<!-- source-hash: 744818572300c7f98b30a728467179eb -->
-Centralized configuration module for all platform branding assets and metadata across the Flamingo/OpenFrame ecosystem, providing icons, colors, display names, descriptions, and utility functions for consistent platform presentation.
+<!-- source-hash: 760045cd91c218f69a16fe3966013d41 -->
+Centralized configuration module for all platform branding assets — icons, colors, display names, descriptions, and slogans — across the OpenFrame OSS library's supported platforms.
 
 ## Key Components
 
-### Lookup Maps (exported constants)
+### Static Lookup Maps
 
-| Export | Purpose |
-|--------|---------|
-| `platformIcons` | React icon components keyed by platform name |
+| Export | Description |
+|---|---|
+| `platformIcons` | React icon nodes (5×5) per platform |
 | `platformColors` | Tailwind `bg-*` class strings per platform |
-| `platformDisplayNames` | Human-readable names (e.g., `"Flamingo Marketing Hub"`) |
+| `platformDisplayNames` | Human-readable names (e.g. `"OpenFrame"`) |
 | `platformDescriptions` | Full marketing copy per platform |
-| `platformSlogans` | Short taglines for branding use |
-| `platformHexColors` | Raw hex values for non-Tailwind contexts |
-| `platformIconNames` | String icon identifiers for config serialization |
+| `platformSlogans` | Short taglines per platform |
+| `platformHexColors` | Raw hex strings for dynamic styling |
+| `platformIconNames` | String icon identifiers for config payloads |
 
-Supported platform keys: `openframe`, `openmsp`, `flamingo`, `flamingo-teaser`, `marketing-hub`, `product-hub`, `revenue-hub`, `people-hub`, `company-hub`, `tmcg`, `universal`
+**Supported platforms:** `openframe`, `openmsp`, `flamingo`, `flamingo-teaser`, `marketing-hub`, `product-hub`, `revenue-hub`, `people-hub`, `company-hub`, `tmcg`, `universal`
 
 ### Utility Functions
 
 | Function | Returns | Notes |
-|----------|---------|-------|
-| `getPlatformIcon(name)` | `React.ReactNode` | Falls back to `universal` Globe icon |
+|---|---|---|
+| `getPlatformIcon(name)` | `React.ReactNode` | 5×5 icon, falls back to `universal` |
+| `getSmallPlatformIcon(name)` | `React.ReactNode` | 4×4 icon for filter buttons, white-optimized |
+| `getPlatformIconComponent(name, className?)` | `React.ReactNode` | 6×6 default, customizable via `className` |
 | `getPlatformColor(name)` | `string` | Tailwind `bg-*` class |
-| `getPlatformDisplayName(name)` | `string` | Falls back to raw name |
-| `getPlatformDescription(name)` | `string` | Falls back to raw name |
-| `getPlatformSlogan(name)` | `string` | Falls back to raw name |
-| `getDefaultColorForPlatform(name)` | `string` | Hex value, falls back to `universal` |
-| `getDefaultIconForPlatform(name)` | `string` | Icon name string, falls back to `universal` |
-| `getSmallPlatformIcon(name)` | `React.ReactNode` | 4×4 (`h-4 w-4`), uses CSS variables for hub variants |
-| `getPlatformIconComponent(name, className?)` | `React.ReactNode` | 6×6 default, accepts custom `className` |
-| `transformPlatformConfigsToOptions(configs)` | `SelectableOption[]` | Maps `PlatformConfig[]` to UI-selectable options with icon and color |
+| `getPlatformDisplayName(name)` | `string` | Falls back to raw `name` |
+| `getPlatformDescription(name)` | `string` | Falls back to raw `name` |
+| `getPlatformSlogan(name)` | `string` | Falls back to raw `name` |
+| `getDefaultColorForPlatform(name)` | `string` | Hex color, defaults to `universal` |
+| `getDefaultIconForPlatform(name)` | `string` | Icon name string, defaults to `universal` |
+| `transformPlatformConfigsToOptions(configs)` | `SelectableOption[]` | Maps `PlatformConfig[]` from DB to UI-ready options |
 
 ## Usage Example
 
 ```typescript
 import {
+  getPlatformIcon,
   getPlatformDisplayName,
   getPlatformColor,
   getSmallPlatformIcon,
-  transformPlatformConfigsToOptions
-} from './platform-config';
+  transformPlatformConfigsToOptions,
+} from './config/platform-config';
 
 // Render a platform badge
-const PlatformBadge = ({ name }: { name: string }) => (
-  <span className={`px-2 py-1 rounded ${getPlatformColor(name)}`}>
-    {getSmallPlatformIcon(name)}
-    {getPlatformDisplayName(name)}
-  </span>
-);
-
-// Populate a platform selector dropdown
-const options = transformPlatformConfigsToOptions(platformConfigs);
-```
+const icon = getPlatformIcon('openframe');         // OpenFrame SVG node
+const label = getPlatformDisplayName('openframe'); // "OpenFrame"
+const bg = getPlatformColor('openframe');          // "bg-[#8B5CF6]"
+
+// Small icon for filter chips
+const smallIcon = getSmallPlatformIcon('flamingo'); // 4×4 pink flamingo
 
-> All lookup functions fall back gracefully to the `universal` platform or the raw input string, so unknown platform keys never produce `undefined` in UI renders.
+// Transform DB records into dropdown options
+const options = transformPlatformConfigsToOptions(platformConfigs);
+// [{ id, name, displayName, description, icon, color }, ...]
+```

package/src/utils/.release-badge.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 47a64824b89a260db77220062bb3aaf7 -->
+Maps product release types to their corresponding `StatusBadge` color schemes for use in `ProductReleaseCard` (lg variant) metadata rendering.
+
+## Key Components
+
+### Types
+
+- **`ReleaseType`** — Union type: `'major' | 'minor' | 'patch' | 'beta' | 'alpha'`
+- **`ReleaseTypeBadgeColor`** — Union type: `'error' | 'cyan' | 'success' | 'warning'`
+
+### Functions
+
+- **`releaseTypeToBadgeColor(t)`** — Converts a release type string to its badge color. Accepts `ReleaseType | string | null | undefined` to handle legacy API values gracefully. Returns `undefined` for unknown inputs (badge hidden, no crash).
+
+### Color Mapping
+
+| Release Type | Color | Semantic |
+|---|---|---|
+| `major` | `error` (red) | Breaking change |
+| `minor` | `cyan` | New feature |
+| `patch` | `success` (green) | Safe bump |
+| `beta` / `alpha` | `warning` (yellow) | Preview |
+
+## Usage Example
+
+```typescript
+import { releaseTypeToBadgeColor } from './release-badge'
+
+// Standard usage in ProductReleaseCard
+const badgeColor = releaseTypeToBadgeColor(release.release_type)
+
+// badgeColor is passed alongside releaseType — both are required for the
+// card to render a colored badge; undefined falls back to '—' placeholder
+<ProductReleaseCard
+  size="lg"
+  releaseType={release.release_type}
+  releaseTypeBadgeColor={badgeColor}
+/>
+
+// Handles unknown/legacy values safely
+releaseTypeToBadgeColor('rc')       // → undefined (badge hidden)
+releaseTypeToBadgeColor(null)       // → undefined (badge hidden)
+releaseTypeToBadgeColor('patch')    // → 'success'
+releaseTypeToBadgeColor('major')    // → 'error'
+```
+
+> **Note:** The color vocabulary here is specific to `StatusBadge` / `ProductReleaseCard`. The admin form's `releaseTypeOptions.color` array uses a separate vocabulary — these two mappings are intentionally kept distinct.

package/src/utils/.release-cover.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 90922d1a0fba270fdb0d92bc58406d0e -->
+Resolves the cover image for a `ProductReleaseCard` using a deterministic priority chain, serving as the single source of truth for all surfaces that render release covers.
+
+## Key Components
+
+### `ReleaseCoverSource`
+Input interface describing the available image candidates on a release entity:
+
+| Field | Description |
+|---|---|
+| `featured_image` | Editor-curated cover — highest priority |
+| `highlight_video_thumbnail` | AI-generated highlight reel thumbnail |
+| `main_video_thumbnail` | Full-release video thumbnail |
+| `og_image_url` | SEO/OG fallback image |
+
+### `ReleaseCoverResult`
+Output interface returned by the resolver:
+
+| Field | Description |
+|---|---|
+| `cover` | Resolved image URL, or `null` if none available |
+| `hasVideoCover` | `true` only when the active cover is a video thumbnail (priorities 2–3) |
+
+### `resolveReleaseCover(r: ReleaseCoverSource): ReleaseCoverResult`
+Applies the priority chain using `||` (not `??`) so empty strings fall through rather than rendering a broken `<Image src="">`. `hasVideoCover` is suppressed when `featured_image` is set, preventing a misleading Play overlay on still images.
+
+## Usage Example
+
+```typescript
+import { resolveReleaseCover } from './release-cover'
+
+const { cover, hasVideoCover } = resolveReleaseCover({
+  featured_image: null,
+  highlight_video_thumbnail: 'https://cdn.example.com/highlight.jpg',
+  main_video_thumbnail: 'https://cdn.example.com/main.jpg',
+  og_image_url: 'https://cdn.example.com/og.jpg',
+})
+
+// cover        → 'https://cdn.example.com/highlight.jpg'
+// hasVideoCover → true
+```
+
+> **Adding a new fallback source?** Edit only `ReleaseCoverSource`, `ReleaseCoverResult`, and the chain in `resolveReleaseCover` — all rendering surfaces pick up the change automatically.
+
+**Source:** [`release-cover.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/release-cover.ts)

package/src/utils/.same-page-hash-nav.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 67a0df770f7417b847b731191fc01a80 -->
+Handles same-page hash navigation by combining `history.pushState`, synthetic `hashchange` events, and smooth scrolling — working around Next.js limitations that suppress smooth scroll during navigation and treat same-URL `router.push` as a no-op.
+
+## Key Components
+
+### Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `STICKY_HEADER_OFFSET_PX` | `96` | Offset for pages with both a section-nav strip and the global hub header |
+| `HUB_HEADER_OFFSET_PX` | `80` | Offset for pages with only the global hub header (docs, blog, vendor detail) |
+
+### Functions & Interfaces
+
+- **`normalizeHashFragment(hash)`** — Strips any extra `#` segments from a fragment string (e.g., `'#a#b'` → `'#a'`), keeping the URL bar and `getElementById` in sync.
+- **`NavigateSamePageHashOptions`** — Interface with optional `headerOffset` (pixels to subtract for sticky chrome) and `history` mode (`'push'` or `'replace'`).
+- **`navigateSamePageHash(target, options)`** — Core primitive that validates the target is same-origin/pathname/search, normalizes malformed fragments, updates history, fires a synthetic `hashchange` event, and smooth-scrolls to the anchor. Returns `true` if the navigation was claimed, `false` for cross-page targets.
+
+## Usage Example
+
+```typescript
+import {
+  navigateSamePageHash,
+  HUB_HEADER_OFFSET_PX,
+  STICKY_HEADER_OFFSET_PX,
+} from './same-page-hash-nav'
+
+// In a TOC link click handler (replaces history entry instead of pushing)
+function handleTocClick(href: string) {
+  const claimed = navigateSamePageHash(href, {
+    headerOffset: HUB_HEADER_OFFSET_PX,
+    history: 'replace',
+  })
+  if (!claimed) {
+    router.push(href) // fall through for cross-page targets
+  }
+}
+
+// Bare-hash shorthand — no need to reconstruct pathname + search
+navigateSamePageHash('#features', {
+  headerOffset: STICKY_HEADER_OFFSET_PX,
+})
+```
+
+> **Dev-mode warnings:** In development, `navigateSamePageHash` logs to the console when it detects a malformed multi-fragment hash or a missing anchor element, pointing to the upstream composer as the source.