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

package/src/components/features/.highlight-video-preview.md

@@ -1,5 +1,5 @@
-<!-- source-hash: 9c2fe27cb025dab5e630418cc7b208a0 -->
-Reusable React component for displaying and managing highlight video previews with support for manual upload, AI-generated badges, and duration display.
+<!-- source-hash: 9b2a25dc6109c28a9059e614c7b4ad28 -->
+Reusable React component for displaying and managing highlight video previews with support for manual file upload, AI-generated badges, and customizable video rendering.
 
 ## Key Components
 
@@ -7,16 +7,18 @@ Reusable React component for displaying and managing highlight video previews wi
 | Prop | Type | Description |
 |------|------|-------------|
 | `highlightVideoUrl` | `string \| null` | URL of the highlight video |
-| `highlightVideoThumbnail` | `string \| null` | Thumbnail image URL |
+| `highlightVideoThumbnail` | `string \| null` | Video thumbnail URL |
 | `highlightVideoDurationMs` | `number \| null` | Duration in milliseconds |
-| `highlightVideoSource` | `'manual' \| 'ai_generated' \| null` | Video origin, shows AI badge if `ai_generated` |
-| `onUpload` | `(file: File) => Promise<string>` | File upload handler |
+| `highlightVideoSource` | `'manual' \| 'ai_generated' \| null` | Origin of the video |
+| `onUpload` | `(file: File) => Promise<string>` | Upload handler returning new URL |
 | `onDelete` | `() => Promise<void>` | Delete handler |
 | `renderVideoPreview` | `(props) => ReactNode` | Render prop for custom video player |
 | `uploadProgressComponent` | `ReactNode` | Optional upload progress UI |
 
 ### `HighlightVideoPreview`
-Main exported component rendering the label row, badges, upload button, and delegating video display to the `renderVideoPreview` render prop.
+The primary exported component. Renders a label row with optional `AIGeneratedBadge` and duration badge, an upload button, optional progress indicator, and either the video preview (via render prop) or an empty state message.
+
+**Internal helper:** `formatDuration(ms)` converts milliseconds to `M:SS` display format.
 
 ## Usage Example
 
@@ -24,16 +26,16 @@ Main exported component rendering the label row, badges, upload button, and dele
 import { HighlightVideoPreview } from './highlight-video-preview';
 
 <HighlightVideoPreview
-  highlightVideoUrl="https://cdn.example.com/video.mp4"
-  highlightVideoThumbnail="https://cdn.example.com/thumb.jpg"
-  highlightVideoDurationMs={125000}
+  highlightVideoUrl={interview.highlightVideoUrl}
+  highlightVideoThumbnail={interview.thumbnailUrl}
+  highlightVideoDurationMs={interview.durationMs}
   highlightVideoSource="ai_generated"
   onUpload={async (file) => {
     const url = await uploadToStorage(file);
     return url;
   }}
   onDelete={async () => {
-    await deleteVideo();
+    await deleteHighlightVideo(interview.id);
   }}
   renderVideoPreview={({ videoUrl, thumbnailUrl, onDelete }) => (
     <VideoPlayer src={videoUrl} poster={thumbnailUrl} onDelete={onDelete} />
@@ -41,4 +43,4 @@ import { HighlightVideoPreview } from './highlight-video-preview';
 />
 ```
 
-> **Note:** This component is designed for both `CustomerInterview` and `ProductRelease` entities, providing a consistent highlight video UI across the platform. The `renderVideoPreview` render prop keeps the video player implementation decoupled.
+> **Note:** The `renderVideoPreview` render prop pattern keeps this component entity-agnostic, making it reusable across `CustomerInterview` and `ProductRelease` entities without coupling to a specific player implementation.

package/src/components/features/.highlight-video-section.md

@@ -1,25 +1,27 @@
-<!-- source-hash: 4bfda13fcb66ea09d23c0f65e2a0d2f7 -->
-Unified React component for managing highlight video generation and upload, supporting both AI-generated and manually uploaded highlight videos for `CustomerInterview` and `ProductRelease` entities.
+<!-- source-hash: 3352f684fadb713012ab77b57ce2cf6a -->
+Unified React component for managing highlight video generation and playback, combining AI-powered generation controls, manual upload, and video preview into a single configurable UI.
 
 ## Key Components
 
-### `HighlightVideoSection`
-Main exported component that renders three logical sections:
+### `HighlightVideoSection` (default export)
 
-- **Configuration Panel** — Target duration selector (1–5 min) and subtitle-burning toggle
-- **AI Generation Section** — Wraps `AIEnrichSection` with Claude AI + Shotstack integration, including progress feedback, cancellation, and status messages
-- **Video Preview + Manual Upload** — Shows current highlight with metadata badges, handles file input for manual uploads, and renders either a custom `VideoPreviewComponent` or a built-in `<video>` player with delete support
+The primary component rendering three distinct sections:
+
+- **Configuration panel** — Target duration selector (1–5 minutes) and subtitle-burning toggle
+- **AI generation panel** — Wraps `AIEnrichSection` with Claude AI + Shotstack integration, progress reporting, and optional cancel support
+- **Preview/upload panel** — Displays the current highlight video (via a custom `VideoPreviewComponent` or the built-in `Video` component), upload trigger, AI-generated badge, duration badge, and delete control
 
 ### `HighlightVideoSectionProps`
-Full TypeScript interface exposing all configuration and callback props. Notable props:
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `targetDurationSeconds` | `number` | AI generation target duration |
-| `canGenerateHighlight` | `boolean` | Gates the generate button |
-| `requiredFields` | `AIRequiredField[]` | Validation hints shown before generation |
-| `VideoPreviewComponent` | `React.ComponentType` | Optional custom video player |
-| `generationStatus` | `'idle' \| 'loading' \| 'success' \| 'error'` | Controls `AIEnrichSection` state |
+Full TypeScript interface controlling all behavior. Key prop groups:
+
+| Group | Props |
+|---|---|
+| Current video state | `highlightVideoUrl`, `highlightVideoThumbnail`, `highlightVideoDurationMs`, `highlightVideoSource` |
+| AI generation | `onGenerateHighlight`, `isGenerating`, `generationProgress`, `generationStatus`, `generationStatusMessage` |
+| Upload | `onUploadHighlight`, `isUploading` |
+| Cancellation | `onCancelGeneration`, `isCancelling` |
+| Extensibility | `VideoPreviewComponent`, `disabled`, `className` |
 
 ## Usage Example
 
@@ -28,20 +30,22 @@ import { HighlightVideoSection } from './highlight-video-section';
 
 <HighlightVideoSection
   highlightVideoUrl={interview.highlightUrl}
+  highlightVideoThumbnail={interview.highlightThumbnail}
   highlightVideoSource="ai_generated"
-  highlightVideoDurationMs={180000}
   targetDurationSeconds={180}
   onTargetDurationChange={(secs) => setTargetDuration(secs)}
   skipSubtitleBurning={false}
-  onSkipSubtitleBurningChange={(skip) => setSkipSubs(skip)}
-  onGenerateHighlight={handleGenerate}
+  onSkipSubtitleBurningChange={(skip) => setSkipSubtitles(skip)}
+  onGenerateHighlight={handleGenerateHighlight}
   isGenerating={isGenerating}
   generationProgress={progress}
   generationStatus={status}
   canGenerateHighlight={!!interview.transcriptId}
-  requiredFields={[{ field: 'transcript', label: 'Transcription' }]}
-  onUploadHighlight={async (file) => uploadToStorage(file)}
-  onDeleteHighlight={handleDelete}
+  requiredFields={[{ label: 'Transcript', fulfilled: !!interview.transcriptId }]}
+  onUploadHighlight={async (file) => uploadHighlight(file)}
+  onDeleteHighlight={handleDeleteHighlight}
   onCancelGeneration={handleCancel}
 />
-```
+```
+
+**Source:** [`highlight-video-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/highlight-video-section.tsx)

package/src/components/features/.index.md

@@ -1,50 +1,54 @@
-<!-- source-hash: 14a224c533f658697e4039f0850c87ac -->
-Central barrel export file for the feature components library, re-exporting all UI components, providers, and utilities from their respective modules into a single public API surface.
+<!-- source-hash: b2ac5c8b15e9d1863c76fff129a5c8e4 -->
+Central barrel export file for the OpenFrame OSS library's feature components, re-exporting all public UI components, hooks, providers, and utilities from their respective module directories.
 
 ## Key Components
 
 ### Theme System
-- `ThemeProvider` / `useTheme` / `useThemeToggle` — Canonical ODS theme system wrapping `next-themes` with manual light/dark switching, default dark, and no-flash support
-- `DynamicThemeProvider` / `useDynamicTheme` — Dynamic theme provider variant
-- `THEME_STORAGE_KEY`, `THEME_ATTRIBUTE`, `DEFAULT_THEME` — Theme configuration constants
-- `Theme`, `ThemeProviderProps`, `UseThemeToggleResult` — TypeScript types
+- **`DynamicThemeProvider`** / **`useDynamicTheme`** — Dynamic runtime theming
+- **`ThemeProvider`** / **`useTheme`** / **`useThemeToggle`** — Canonical ODS theme system (thin wrapper over `next-themes`), headless by design with constants `THEME_STORAGE_KEY`, `THEME_ATTRIBUTE`, `DEFAULT_THEME` and types `Theme`, `ThemeProviderProps`, `UseThemeToggleResult`
 
 ### Video Primitives
-- `video` — Unified `<Video>` component replacing legacy `VideoPlayer` + `YouTubeEmbed`
-- `entity-video-section` / `video-bites-display` — Public detail-page wrappers
-- `video-ratio-tabs` — Aspect-ratio grouping primitives for bites grid and admin editors
-- `highlight-video-*` / `transcript-summary-editor` / `video-clips-section` — Video processing and display utilities
-
-### UI Components
-- `command-box`, `filters-dropdown`, `tags-selector`, `select-button`, `view-toggle`
-- `os-type-badge`, `platform-badge`, `platform-filter` — Platform/OS display components
-- `error-boundary`, `loading-provider` — App infrastructure components
-- `seo-editor-preview`, `social-links-manager`, `knowledge-base-links-manager`
-- `board`, `notifications`, `waitlist-form`, `ai-enrich`, `policy-configuration-panel`
-
-### Manager Components
-- `array-entry-manager`, `changelog-manager`, `changelog-sections-manager`
-- `clickup-tasks-manager`, `github-releases-manager`, `media-gallery-manager`
-- `release-media-manager`
+- **`<Video>`** — Unified video component replacing legacy `<VideoPlayer>` + `<YouTubeEmbed>`
+- **`<CardsStrip>`** — Horizontal card-strip engine (render-prop or organic `children` mode)
+- **`<EntityVideoSection>`** / **`<VideoBitesStrip>`** — Public detail-page wrappers
+- **`<VideoBitesDisplay>`** — Deprecated shim over the strip
+- **`video-bites-shared`** — Server-safe leaf, also published as its own subpath
+
+### Feature Components (selected)
+- `auth`, `auth-providers-list`, `command-box`, `error-boundary`
+- `filters-dropdown`, `loading-provider`, `media-gallery-manager`
+- `ai-enrich`, `board`, `notifications`, `time-tracker`
+- `seo-editor-preview`, `tags-selector`, `social-links-manager`
+- `changelog-manager`, `github-releases-manager`, `knowledge-base-links-manager`
 
 ## Usage Example
 
 ```typescript
-// Import theme system
-import { ThemeProvider, useThemeToggle } from '@/features'
-
-function App({ children }) {
-  return <ThemeProvider>{children}</ThemeProvider>
-}
-
-function ThemeToggle() {
+import {
+  ThemeProvider,
+  useThemeToggle,
+  Video,
+  CardsStrip,
+  CommandBox,
+  ErrorBoundary,
+} from '@openframe-oss-lib/features'
+
+function App() {
   const { toggle, theme } = useThemeToggle()
-  return <Button onClick={toggle}>Mode: {theme}</Button>
+
+  return (
+    <ThemeProvider>
+      <ErrorBoundary>
+        <Video src="https://example.com/video.mp4" />
+        <button onClick={toggle}>Current: {theme}</button>
+      </ErrorBoundary>
+    </ThemeProvider>
+  )
 }
+```
 
-// Import video primitives
-import { Video, EntityVideoSection, VideoBitesDisplay } from '@/features'
+## Notes
 
-// Import UI components
-import { CommandBox, FiltersDropdown, OsTypeBadge } from '@/features'
-```
+- Marked `"use client"` — all exports are client-side React components/hooks
+- Acts as the single public API surface for consumers; internal module paths should not be imported directly
+- Source: [`src/features/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/features/index.ts)

package/src/components/features/.media-gallery-manager.md

@@ -1,60 +1,62 @@
-<!-- source-hash: 19b6fb4bf578261808d64ed0dbbafcce -->
-Reusable React component for managing a media gallery with upload, display, drag-and-drop reordering, and deletion capabilities. Designed for use across events, product releases, and any content requiring media gallery management.
+<!-- source-hash: c88990c646ac00bc2153738bb81e7d24 -->
+Reusable React component for managing a media gallery — supports image and video upload, drag-to-reorder, and deletion with an optional modal wrapper.
 
 ## Key Components
 
-### `MediaItem` Interface
-Describes a single media entry with the following fields:
+### `MediaItem` (interface)
+Data shape for a single gallery entry:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string \| number` | Optional identifier for existing items |
-| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Type classification |
-| `media_url` | `string` | URL of the media asset |
-| `title` | `string` | Optional display title |
-| `description` | `string` | Optional description |
-| `display_order` | `number` | Optional sort order |
-| `_uploading` | `boolean` | Internal upload state flag |
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string \| number` | Optional; omitted for new items |
+| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Controls render path |
+| `media_url` | `string` | Resolved URL after upload |
+| `title` | `string` | Displayed below the thumbnail |
+| `display_order` | `number` | Updated automatically on reorder |
+| `_uploading` | `boolean` | Optimistic upload state flag |
 
-### `MediaGalleryManager` Component
-Primary export. Renders upload zone, media grid, drag-and-drop controls, and delete actions.
-
-**Props:**
+### `MediaGalleryManager` (component)
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `media` | `MediaItem[]` | — | Current media items array |
-| `onChange` | `(media: MediaItem[]) => void` | — | Called on any mutation |
-| `onUpload` | `(file, mediaType) => Promise<string>` | — | Handles file upload, returns URL |
-| `isUploading` | `boolean` | `false` | Disables controls during upload |
-| `showInModal` | `boolean` | `false` | Reserved for modal rendering |
-| `modalTitle` | `string` | `'Media Gallery'` | Modal heading text |
-| `className` | `string` | `''` | Additional CSS classes |
+|---|---|---|---|
+| `media` | `MediaItem[]` | — | Controlled list of media items |
+| `onChange` | `(media: MediaItem[]) => void` | — | Called on add, delete, or reorder |
+| `onUpload` | `(file, mediaType) => Promise<string>` | — | Async upload handler; returns resolved URL |
+| `isUploading` | `boolean` | `false` | Shows spinner and disables controls |
+| `showInModal` | `boolean` | `false` | Reserved for modal rendering mode |
+| `modalTitle` | `string` | `'Media Gallery'` | Title when rendered in a modal |
+| `className` | `string` | `''` | Additional wrapper classes |
+
+**Internal behaviors:**
+- `handleFileSelect` — detects MIME type, calls `onUpload`, appends new `MediaItem`
+- `handleDeleteMedia` — filters item by index, updates order
+- `handleDragStart / handleDrop` — HTML5 drag-and-drop reorder; recalculates `display_order` on drop
 
 ## Usage Example
 
 ```typescript
 import { MediaGalleryManager, MediaItem } from './media-gallery-manager';
 
-const [media, setMedia] = useState<MediaItem[]>([]);
-const [uploading, setUploading] = useState(false);
+const [gallery, setGallery] = useState<MediaItem[]>([]);
 
-async function handleUpload(file: File, mediaType: 'image' | 'video'): Promise<string> {
-  setUploading(true);
+async function uploadToStorage(file: File, mediaType: 'image' | 'video') {
   const formData = new FormData();
   formData.append('file', file);
   const res = await fetch('/api/upload', { method: 'POST', body: formData });
   const { url } = await res.json();
-  setUploading(false);
   return url;
 }
 
 <MediaGalleryManager
-  media={media}
-  onChange={setMedia}
-  onUpload={handleUpload}
-  isUploading={uploading}
+  media={gallery}
+  onChange={setGallery}
+  onUpload={uploadToStorage}
+  isUploading={false}
 />
 ```
 
-> **Note:** Accepted file types are `image/*` and `video/*` with a recommended maximum of 50MB. On upload, images map to `screenshot` and videos to `demo` media types.
+## Notes
+
+- Videos (`video`, `demo`) render via the internal `<Video>` component (MuxPlayer/HLS); images use Next.js `<Image>` with `fill` + `object-cover`.
+- `display_order` is recalculated as array index on every reorder or delete — keep it as the source of truth for server persistence.
+- The `showInModal` prop is wired to props but the modal rendering path is not yet implemented in this file.

package/src/components/features/.mux-origins.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 4b4394b8492af21f51a0eb384983e584 -->
+Provides Mux CDN origin constants and playback URL utilities in a server-safe (non-`'use client'`) module, enabling both server-side and client-side code to import Mux configuration without triggering Next.js client-reference poisoning.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `MUX_STREAM_ORIGIN` | `const string` | Base URL for Mux HLS playback and MP4 renditions (`https://stream.mux.com`) |
+| `MUX_IMAGE_ORIGIN` | `const string` | Base URL for Mux server-generated thumbnails (`https://image.mux.com`) |
+| `MuxMaxResolution` | `type` | Union of valid Mux `max_resolution` modifier values: `'720p' \| '1080p' \| '1440p' \| '2160p'` |
+| `toMuxPreviewUrl` | `function` | Appends a `max_resolution` query param to Mux HLS URLs for bandwidth-capped preview players |
+
+## Usage Example
+
+```typescript
+import { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN, toMuxPreviewUrl } from './mux-origins'
+
+// Server-side hostname comparison (safe — no client stubs)
+const streamHost = new URL(MUX_STREAM_ORIGIN).hostname // 'stream.mux.com'
+
+// Cap renditions for a small hover-card preview player
+const rawUrl = 'https://stream.mux.com/abc123.m3u8'
+const previewUrl = toMuxPreviewUrl(rawUrl, '720p')
+// → 'https://stream.mux.com/abc123.m3u8?max_resolution=720p'
+
+// Pass-through cases (no modification)
+toMuxPreviewUrl('https://example.supabase.co/clip.mp4')  // non-Mux host
+toMuxPreviewUrl('https://stream.mux.com/abc123.mp4')     // non-.m3u8 path
+toMuxPreviewUrl('https://stream.mux.com/abc123.m3u8?token=xyz') // signed URL
+```
+
+## Pass-Through Conditions
+
+`toMuxPreviewUrl` returns the original URL unchanged when:
+
+- Host is not `stream.mux.com` (e.g. Supabase MP4s, YouTube)
+- Path does not end in `.m3u8` (e.g. MP4 renditions)
+- URL already contains a `?token=` param (Mux prohibits loose modifiers alongside JWT tokens)
+- URL string is unparseable
+
+## Notes
+
+- **Server safety:** Intentionally omits `'use client'` so server modules (webhook handlers, Next.js middleware, `lib/config/mux-config.ts`) can import without crashing at Vercel build time. Re-exported from `use-video-warmup.ts` for backward compatibility.
+- **Safari compatibility:** The `max_resolution` param works at the HLS manifest level, which is the only effective rendition cap on Safari's native HLS player where `hls.js` is unavailable.
+
+**Source:** [`mux-origins.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mux-origins.ts)

package/src/components/features/.og-editor-preview.md

@@ -1,26 +1,29 @@
-<!-- source-hash: 7e8d4cbbf42c408ee48d1318fbf9c4e3 -->
-Unified SEO & Open Graph editor component that combines meta fields (title, description, keywords), OG image upload, and a live preview into a single reusable panel. Designed for content editors across blog posts, case studies, and product releases.
+<!-- source-hash: 01d000415365defb1a9149173d637f01 -->
+Unified SEO and Open Graph editor component that combines meta fields, OG image upload, and a live preview panel into a single composable UI block. Designed for reuse across blog posts, case studies, and product releases.
 
 ## Key Components
 
 ### `OGEditorPreview`
-Main exported component that renders a card-style panel with:
-- **SEO Title + Keywords** — side-by-side `Input` fields (responsive grid)
-- **SEO Description + OG Image** — `Textarea` paired with an injected upload widget
-- **OG Preview** — rendered below a divider via the `OGPreviewComponent` slot
+The primary exported function component. Renders a card-style panel containing:
+- **SEO Title** and **SEO Keywords** inputs (side-by-side on large screens)
+- **SEO Description** textarea and **OG Image** upload slot (side-by-side on large screens)
+- **OG Preview** section rendered below a divider
 
 ### `OGEditorPreviewProps`
-Full interface defining:
+Interface defining all accepted props:
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `seoTitle` / `seoDescription` / `seoKeywords` | `string` | Controlled SEO field values |
+|---|---|---|
+| `seoTitle` | `string` | Controlled SEO title value |
+| `seoDescription` | `string` | Controlled meta description value |
+| `seoKeywords` | `string` | Controlled keywords value |
 | `ogImageUrl` | `string` | Current OG image URL |
 | `title` / `summary` / `featuredImage` | `string` | Auto-populate sources from parent content |
-| `categories` | `Array<{name, slug}>` | Optional category metadata |
-| `OGImageUploadComponent` | `React.ReactNode` | Upload widget injected by parent |
-| `OGPreviewComponent` | `React.ReactNode` | Preview widget injected by parent |
-| `disabled` | `boolean` | Disables all inputs |
+| `categories` | `Array<{name, slug}>` | Optional category list for auto-population |
+| `OGImageUploadComponent` | `React.ReactNode` | Upload UI injected from parent |
+| `OGPreviewComponent` | `React.ReactNode` | Preview UI injected from parent |
+| `disabled` | `boolean` | Disables all inputs (default: `false`) |
+| `className` | `string` | Additional CSS classes |
 
 ## Usage Example
 
@@ -28,20 +31,22 @@ Full interface defining:
 import { OGEditorPreview } from './og-editor-preview';
 
 <OGEditorPreview
-  seoTitle={post.seoTitle}
-  seoDescription={post.seoDescription}
-  seoKeywords={post.seoKeywords}
-  ogImageUrl={post.ogImageUrl}
+  seoTitle={form.seoTitle}
+  seoDescription={form.seoDescription}
+  seoKeywords={form.seoKeywords}
+  ogImageUrl={form.ogImageUrl}
   title={post.title}
   summary={post.summary}
   featuredImage={post.featuredImage}
-  onSeoTitleChange={(val) => updateField('seoTitle', val)}
-  onSeoDescriptionChange={(val) => updateField('seoDescription', val)}
-  onSeoKeywordsChange={(val) => updateField('seoKeywords', val)}
-  onOgImageUrlChange={(val) => updateField('ogImageUrl', val)}
-  OGImageUploadComponent={<OGImageUploader postId={post.id} />}
-  OGPreviewComponent={<OGPreview title={post.seoTitle} description={post.seoDescription} image={post.ogImageUrl} />}
+  onSeoTitleChange={(v) => setForm({ ...form, seoTitle: v })}
+  onSeoDescriptionChange={(v) => setForm({ ...form, seoDescription: v })}
+  onSeoKeywordsChange={(v) => setForm({ ...form, seoKeywords: v })}
+  onOgImageUrlChange={(v) => setForm({ ...form, ogImageUrl: v })}
+  OGImageUploadComponent={<ImageUploader onUpload={handleUpload} />}
+  OGPreviewComponent={<OGPreview url={previewUrl} title={form.seoTitle} />}
 />
 ```
 
-> Upload and preview widgets are passed as render props (`React.ReactNode`), keeping this component decoupled from specific upload or preview implementations.
+> **Note:** `OGImageUploadComponent` and `OGPreviewComponent` are injected as render props (`React.ReactNode`), keeping upload and preview logic decoupled from this component. `ogImageUrl` and `onOgImageUrlChange` are declared in the interface but not consumed internally — they are intended for use by the injected child components via the parent's closure.
+
+**Source:** [`og-editor-preview.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/og-editor-preview.tsx)

package/src/components/features/.os-type-badge-group.md

@@ -1,31 +1,39 @@
-<!-- source-hash: 65ab317c1224391b2ef2d144c5e6b6ca -->
-A React component that displays multiple operating system type badges in a horizontal group, useful for showing supported platforms for scripts and applications.
+<!-- source-hash: cd5e91e4f786cf7bf20df7ec3e71c11d -->
+Renders a horizontal group of OS type icons, optionally truncating to a maximum count with a "+N more" overflow indicator.
 
 ## Key Components
 
-- **OSTypeBadgeGroup**: Main component that renders a collection of OS badges
-- **OSTypeBadgeGroupProps**: Interface defining component properties including OS types array, styling options, and display limits
-- Integrates with **OSTypeBadge** component for individual badge rendering
-- **maxDisplay** prop with overflow handling ("+N more" indicator)
+### `OSTypeBadgeGroup`
+
+The primary export. Iterates over an array of OS type strings and renders an [`OSTypeBadge`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/os-type-badge/os-type-badge.tsx) (icon-only mode) for each entry. Returns `null` when `osTypes` is empty or undefined.
+
+### `OSTypeBadgeGroupProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `osTypes` | `string[]` | — | OS type strings (case-insensitive, alias-aware) |
+| `className` | `string` | `''` | Additional CSS classes for the wrapper |
+| `iconSize` | `string` | `'w-5 h-5'` | Tailwind size classes applied to each icon |
+| `maxDisplay` | `number` | — | Cap on visible badges; excess shown as `+N more` |
 
 ## Usage Example
 
 ```typescript
 import { OSTypeBadgeGroup } from './os-type-badge-group'
 
-// Basic usage with multiple OS types
+// Show all three platform icons
 <OSTypeBadgeGroup osTypes={['windows', 'darwin', 'linux']} />
 
-// With display limit and custom styling
-<OSTypeBadgeGroup 
-  osTypes={['macos', 'linux', 'windows', 'freebsd']} 
-  maxDisplay={3}
-  iconSize="w-6 h-6"
-  className="my-4"
+// Cap at 2, renders "+1 more" for the third
+<OSTypeBadgeGroup
+  osTypes={['windows', 'macos', 'linux']}
+  maxDisplay={2}
+  iconSize="w-4 h-4"
 />
 
-// Handle empty arrays gracefully
-<OSTypeBadgeGroup osTypes={[]} /> // Returns null
-```
-
-The component automatically handles OS type aliases (e.g., 'darwin' → macOS), displays only icons without labels, and provides responsive wrapping with gap spacing. When the number of OS types exceeds `maxDisplay`, it shows a truncated list with a "+N more" indicator.
+// Custom wrapper styling
+<OSTypeBadgeGroup
+  osTypes={['linux']}
+  className="mt-2"
+/>
+```

package/src/components/features/.os-type-badge.md

@@ -1,38 +1,55 @@
-<!-- source-hash: ff4b493b1051ef66b833db7f551bfc8a -->
-A React component for displaying operating system types with icons and labels, supporting flexible display modes and automatic OS type normalization.
+<!-- source-hash: abfd76b408caa3d26e7e71712dadbe88 -->
+Displays operating system type with an icon and label, automatically normalizing OS type strings from various formats and aliases. Exports three focused sub-components for flexible rendering.
 
 ## Key Components
 
-- **OSTypeBadge** - Main component that displays OS type with icon and label
-- **OSTypeIcon** - Convenience component for icon-only display
-- **OSTypeLabel** - Convenience component for label-only display
-- **OSTypeBadgeProps** - Interface defining component props including display modes and styling options
+| Export | Type | Description |
+|---|---|---|
+| `OSTypeBadge` | `React.FC` | Full badge with icon + label (default), icon-only, or label-only rendering |
+| `OSTypeIcon` | `React.FC` | Convenience wrapper — renders only the OS icon |
+| `OSTypeLabel` | `React.FC` | Convenience wrapper — renders only the OS label text |
+| `OSTypeBadgeProps` | `interface` | Props interface for `OSTypeBadge` |
+
+### `OSTypeBadgeProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `osType` | `string` | — | OS type string (case-insensitive, handles aliases) |
+| `className` | `string` | `''` | Additional CSS classes |
+| `iconOnly` | `boolean` | `false` | Render icon only, no label |
+| `labelOnly` | `boolean` | `false` | Render label only, no icon |
+| `iconSize` | `string` | `'w-4 h-4'` | Tailwind size classes for the icon |
+| `iconColor` | `string` | `var(--color-text-secondary)` | Icon fill/stroke color |
+| `rightIcon` | `React.ReactNode` | `null` | Optional trailing icon element |
 
 ## Usage Example
 
 ```typescript
 import { OSTypeBadge, OSTypeIcon, OSTypeLabel } from './os-type-badge'
 
-// Full badge with icon and label
+// Full badge: icon + label
 <OSTypeBadge osType="windows" />
 <OSTypeBadge osType="Darwin" />
-<OSTypeBadge osType="Ubuntu" />
-
-// Icon only mode
-<OSTypeBadge osType="linux" iconOnly />
-<OSTypeIcon osType="macOS" size="w-6 h-6" />
-
-// Label only mode
-<OSTypeBadge osType="windows" labelOnly />
-<OSTypeLabel osType="fedora" />
-
-// With custom styling and right icon
-<OSTypeBadge 
-  osType="windows" 
-  className="bg-blue-100" 
-  iconColor="#0078d4"
-  rightIcon={<ChevronRight />}
+
+// Icon only (e.g. compact table cell)
+<OSTypeIcon osType="Ubuntu" size="w-5 h-5" />
+
+// Label only (e.g. plain text context)
+<OSTypeLabel osType="linux" className="font-medium" />
+
+// Badge with trailing action icon
+<OSTypeBadge
+  osType="windows"
+  rightIcon={<ChevronRightIcon className="w-3 h-3" />}
 />
+
+// Unknown / missing OS type
+<OSTypeBadge osType={undefined} labelOnly /> // renders "Unknown"
+<OSTypeBadge osType={undefined} />            // renders null
 ```
 
-The component automatically handles OS type normalization through utility functions, supports case-insensitive input, and gracefully handles unknown OS types. It uses responsive typography and includes proper TypeScript interfaces for type safety.
+## Notes
+
+- OS type strings are normalized via `normalizeOSType` from [`os-utils`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/os-utils.ts), so values like `"Darwin"`, `"ubuntu"`, or `"win32"` resolve correctly.
+- When `osType` is missing and `labelOnly` is `false`, the component returns `null` (safe for conditional rendering).
+- All three exports set a `displayName` for clear identification in React DevTools.