@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/features/.changelog-sections-manager.md

@@ -1,11 +1,11 @@
-<!-- source-hash: 24082a43cb0377e101a4f1957ec35829 -->
-A React component that organizes and manages changelog entries across four distinct categories, providing a structured interface for editing product release notes.
+<!-- source-hash: 25788d62c9b251ff8382443ab8b6fcff -->
+A client-side React component that renders all four standard changelog sections (Features Added, Bugs Fixed, Improvements, Breaking Changes) as a unified, styled panel by composing multiple `ChangelogManager` instances.
 
 ## Key Components
 
-- **ChangelogSectionsManager**: Main component that renders four `ChangelogManager` instances for different changelog categories
-- **ChangelogSectionsManagerProps**: Interface defining props including entry arrays, change handlers, and display options
-- **Category Sections**: Features Added, Bugs Fixed, Improvements, and Breaking Changes
+- **`ChangelogSectionsManager`** — Main exported component that groups and renders all changelog sections in a single card layout
+- **`ChangelogSectionsManagerProps`** — Interface defining per-section entry arrays, change handlers, optional `className`, and `expandAll` flag
+- **`expandAll`** — Boolean prop that expands all entries across all sections simultaneously, intended for use after AI enrichment populates fields
 
 ## Usage Example
 
@@ -13,27 +13,22 @@ A React component that organizes and manages changelog entries across four disti
 import { ChangelogSectionsManager } from './changelog-sections-manager';
 import type { ChangelogEntry } from '../../types/product-release';
 
-function ReleaseEditor() {
-  const [features, setFeatures] = useState<ChangelogEntry[]>([]);
-  const [bugs, setBugs] = useState<ChangelogEntry[]>([]);
-  const [improvements, setImprovements] = useState<ChangelogEntry[]>([]);
-  const [breaking, setBreaking] = useState<ChangelogEntry[]>([]);
+const [featuresAdded, setFeaturesAdded] = useState<ChangelogEntry[]>([]);
+const [bugsFixed, setBugsFixed] = useState<ChangelogEntry[]>([]);
+const [improvements, setImprovements] = useState<ChangelogEntry[]>([]);
+const [breakingChanges, setBreakingChanges] = useState<ChangelogEntry[]>([]);
 
-  return (
-    <ChangelogSectionsManager
-      featuresAdded={features}
-      bugsFixed={bugs}
-      improvements={improvements}
-      breakingChanges={breaking}
-      onFeaturesAddedChange={setFeatures}
-      onBugsFixedChange={setBugs}
-      onImprovementsChange={setImprovements}
-      onBreakingChangesChange={setBreaking}
-      expandAll={true} // Expand all sections after AI enrichment
-      className="my-4"
-    />
-  );
-}
+<ChangelogSectionsManager
+  featuresAdded={featuresAdded}
+  bugsFixed={bugsFixed}
+  improvements={improvements}
+  breakingChanges={breakingChanges}
+  onFeaturesAddedChange={setFeaturesAdded}
+  onBugsFixedChange={setBugsFixed}
+  onImprovementsChange={setImprovements}
+  onBreakingChangesChange={setBreakingChanges}
+  expandAll={aiEnrichmentComplete}
+/>
 ```
 
-The component uses a consistent card layout with ODS (OpenFrame Design System) styling and delegates individual section management to the `ChangelogManager` component. The `expandAll` prop is particularly useful for displaying AI-enhanced changelog entries.
+Each section delegates entry management (add, edit, remove) to its own `ChangelogManager` instance while sharing the `expandAll` state, keeping the parent component's state management straightforward with one array and one setter per section.

package/src/components/features/.command-box.md

@@ -1,12 +1,20 @@
-<!-- source-hash: 58a52ec93cc9a268c0cf74ea4894e9e7 -->
-A unified React component for displaying commands with optional title and configurable action buttons, featuring responsive design and consistent styling within the ODS design system.
+<!-- source-hash: b7d1c615d3d37a540958daff7feed5f3 -->
+A reusable React component for displaying command strings in a styled monospace box with optional title and configurable action buttons.
 
 ## Key Components
 
-- **`CommandBoxAction`** - Interface defining action button properties including label, click handler, variant, icon, and state
-- **`CommandBoxProps`** - Main component props interface with command text, title, actions, and styling options
-- **`CommandBox`** - Primary component that renders command text in a styled card with optional action buttons
-- **`lineClampClasses`** - Static mapping object for Tailwind line-clamp classes to enable build-time optimization
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `CommandBoxAction` | Defines a button with `label`, `onClick`, optional `variant`, `icon`, `disabled`, and `loading` states |
+| `CommandBoxProps` | Component props including `command` (required), `title`, `primaryAction`, `secondaryAction`, layout classes, and `maxLines` |
+
+### Exports
+
+- **`CommandBox`** — Main component rendering the command display box
+- **`CommandBoxAction`** — Interface for action button configuration
+- **`CommandBoxProps`** — Interface for component props
 
 ## Usage Example
 
@@ -14,34 +22,29 @@ A unified React component for displaying commands with optional title and config
 import { CommandBox } from '@flamingo/ui-kit/components/features'
 import { Copy, Play } from 'lucide-react'
 
-// Basic command display with copy action
 <CommandBox
-  title="Installation Command"
-  command="npm install @flamingo/ui-kit"
-  primaryAction={{
-    label: 'Copy',
-    onClick: () => navigator.clipboard.writeText(command),
-    icon: <Copy className="w-4 h-4" />,
-    variant: 'primary'
-  }}
-/>
-
-// Multi-line command with line limiting
-<CommandBox
-  command="curl -L https://example.com/install.sh | bash -s -- --config production"
-  maxLines={2}
+  title="Device Add Command"
+  command="curl -L https://example.com/install.sh | bash"
+  maxLines={3}
   primaryAction={{
     label: 'Copy Command',
-    onClick: handleCopy,
-    variant: 'outline'
+    onClick: () => navigator.clipboard.writeText(command),
+    icon: <Copy className="w-5 h-5" />,
+    variant: 'accent'
   }}
   secondaryAction={{
-    label: 'Execute',
-    onClick: handleExecute,
-    icon: <Play className="w-4 h-4" />,
-    loading: isExecuting
+    label: 'Run on Machine',
+    onClick: handleRun,
+    icon: <Play className="w-5 h-5" />,
+    variant: 'outline',
+    loading: isRunning
   }}
 />
 ```
 
-The component automatically handles responsive layout, switching from row to column layout on smaller screens, and supports up to 6 lines of text clamping for long commands.
+## Notes
+
+- **Line clamping** uses a static `lineClampClasses` map (`1–6`) to ensure Tailwind generates the correct `line-clamp-*` classes at build time. Set `maxLines={0}` (default) for unlimited display.
+- **Button layout** stacks vertically on mobile and aligns right horizontally on `md+` screens.
+- Secondary action renders before the primary action visually, consistent with standard UI conventions.
+- `variant` defaults to `'accent'` for primary and `'outline'` for secondary if not specified.

package/src/components/features/.entity-summary-editor.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 87dfd7f5b94bff0f44ed579685785b88 -->
+Reusable editor component for entity summary fields with AI generation badges and confidence score display.
+
+## Key Components
+
+**`EntitySummaryEditor`** — Default export. A controlled textarea editor with optional AI metadata indicators.
+
+**`EntitySummaryEditorProps`** — TypeScript interface defining all configurable props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `summary` | `string` | `''` | Controlled text value |
+| `onSummaryChange` | `(value: string) => void` | required | Change handler |
+| `isAIGenerated` | `boolean` | `false` | Shows AI Generated badge |
+| `summaryConfidence` | `number \| null` | — | Confidence score (0–100) |
+| `label` | `string` | `'Summary (Markdown supported)'` | Field label |
+| `helperText` | `string` | `'Entity summary...'` | Subtext below label |
+| `placeholder` | `string` | `'Brief summary...'` | Textarea placeholder |
+| `minHeight` | `number` | `200` | Minimum height in px |
+| `disabled` | `boolean` | `false` | Disables the textarea |
+| `className` | `string` | `''` | Container class override |
+
+## Usage Example
+
+```typescript
+import { EntitySummaryEditor } from './entity-summary-editor';
+
+function ReleaseForm() {
+  const [summary, setSummary] = React.useState('');
+
+  return (
+    <EntitySummaryEditor
+      summary={summary}
+      onSummaryChange={setSummary}
+      isAIGenerated={true}
+      summaryConfidence={87}
+      label="Release Summary (Markdown supported)"
+      helperText="Displayed on release cards and detail page."
+      placeholder="Describe this release..."
+      minHeight={240}
+    />
+  );
+}
+```
+
+When `isAIGenerated` is `true`, a `Sparkles` icon badge renders next to the label. When `summaryConfidence` is provided, `ConfidenceBadge` renders inline showing the AI confidence percentage.

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

@@ -0,0 +1,51 @@
+<!-- source-hash: e2ba951ef60128447d27416a00b1a586 -->
+Renders the video block for entity detail pages, combining full video, highlight video, AI-generated summary, and video bites into a unified tabbed layout.
+
+## Key Components
+
+### `EntityVideoSection` (default export)
+Main component that orchestrates the video display logic:
+- **Tab UI** — renders "Full Video" / "Highlights" tabs when both a full video and highlight video are present; falls back to a single `<Video>` when only one exists
+- **YouTube precedence** — resolves `youtubeUrl` vs `mainVideoUrl` priority at this level, keeping `<Video>` as a single-source-per-render primitive
+- **Video summary** — renders an AI-generated markdown summary via injected `MarkdownRenderer`
+- **Video bites grid** — delegates to `<VideoBitesDisplay>` when `videoBites` are provided
+- **Null guard** — returns `null` when no video, summary, or bites are present
+
+### `EntityVideoSectionProps`
+Full interface for controlling content and behavior:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `youtubeUrl` | `string \| null` | YouTube URL (takes priority over `mainVideoUrl`) |
+| `mainVideoUrl` | `string \| null` | Uploaded video URL |
+| `highlightVideoUrl` | `string \| null` | AI-generated highlight clip |
+| `captionsUrl` | `string \| null` | HTTPS URL to a VTT captions file |
+| `MarkdownRenderer` | `ComponentType` | Injected renderer for summary markdown |
+| `priority` | `boolean` | LCP hint for eager poster loading |
+| `srtContent` | `string \| null` | Deprecated — use `captionsUrl` |
+
+## Usage Example
+
+```typescript
+import { EntityVideoSection } from './entity-video-section';
+import { MarkdownRenderer } from '@/components/markdown-renderer';
+
+export function TalkDetailPage({ talk }) {
+  return (
+    <EntityVideoSection
+      youtubeUrl={talk.youtubeUrl}
+      mainVideoUrl={talk.videoUrl}
+      highlightVideoUrl={talk.highlightUrl}
+      highlightVideoThumbnail={talk.highlightThumb}
+      mainVideoPoster={talk.posterUrl}
+      title={talk.title}
+      videoSummary={talk.aiSummary}
+      videoBites={talk.bites}
+      bitesTitle="Key Moments"
+      captionsUrl={talk.captionsUrl}
+      MarkdownRenderer={MarkdownRenderer}
+      priority
+    />
+  );
+}
+```

package/src/components/features/.figma-prototype-viewer.md

@@ -1,45 +1,64 @@
-<!-- source-hash: 334f79ef37d39fafa41a9fecfc6bf342 -->
-A responsive React component for embedding and viewing Figma prototypes with automatic device detection, adaptive scaling, and section-based navigation.
+<!-- source-hash: d8463fe41098681892c9956a4d6c77ce -->
+Renders an interactive Figma prototype viewer component with responsive layout, automatic device detection, section navigation, and scaled iframe embedding for both desktop and mobile viewports.
 
 ## Key Components
 
-- **FigmaPrototypeViewer**: Main component with unified state management and responsive iframe embedding
-- **UnifiedState**: Comprehensive state interface managing view modes, scaling, navigation, and UI states
-- **ViewMode Types**: `DESKTOP`, `MOBILE`, `MOBILE_TOUCH` with automatic detection based on screen size and touch capability
-- **Configuration System**: Supports environment variables and config-based setup for file keys, dimensions, and starting points
-- **Scaling Engine**: Calculates optimal iframe scaling and positioning for different screen sizes
-- **Section Navigation**: Integration with SectionSelector for prototype flow navigation
+### Interfaces & Types
+- **`FigmaPrototypeViewerConfig`** — Main configuration object; accepts file keys (per-device or legacy single), sections, dimensions, starting points, and UI class overrides
+- **`FigmaPrototypeSection`** — Defines a navigable prototype section with separate desktop/mobile node IDs
+- **`UnifiedState`** — Consolidated state shape covering view mode, iframe lifecycle, scaling, UI visibility flags, and navigation
+- **`ViewMode`** — `'DESKTOP' | 'MOBILE' | 'MOBILE_TOUCH'`
+- **`IframeState`** — `'INITIAL' | 'LOADING' | 'READY' | 'RELOADING' | 'SLEEP_RECOVERY'`
+
+### Core Functions
+- **`getViewMode(screenWidth, isTouchDevice)`** — Derives current `ViewMode` from screen width against the 768px breakpoint
+- **`calculateScaling(viewMode, containerDimensions, config?)`** — Computes `scale`, `marginX/Y`, and `scaledDimensions` to fit content without upscaling
+- **`resolveFileKey(config, viewMode)`** — Picks the correct Figma file key via env vars → per-device config → legacy `fileKey`
+- **`resolveStartingPoint(config, viewMode, section?)`** — Resolves the initial prototype node via env vars → config → first section fallback
+- **`generateEmbedUrl(...)`** — Builds the `embed.figma.com/proto` URL with all required query parameters
+- **`renderUnifiedUI(state, handlers, config, iframeRef)`** — Pure render function producing the full component JSX from state
+
+### Environment Variable Overrides
+Content dimensions and file keys can be set at the environment level:
+
+```text
+NEXT_PUBLIC_FIGMA_MOBILE_FILE_KEY
+NEXT_PUBLIC_FIGMA_DESKTOP_FILE_KEY
+NEXT_PUBLIC_FIGMA_MOBILE_STARTING_POINT
+NEXT_PUBLIC_FIGMA_DESKTOP_STARTING_POINT
+NEXT_PUBLIC_FIGMA_MOBILE_WIDTH / _HEIGHT
+NEXT_PUBLIC_FIGMA_DESKTOP_WIDTH / _HEIGHT
+```
+
+Priority order: **env vars → config props → defaults**
 
 ## Usage Example
 
 ```typescript
 import { FigmaPrototypeViewer } from './figma-prototype-viewer'
+import type { FigmaPrototypeViewerConfig } from './figma-prototype-viewer'
 
-const config = {
-  title: "Design System Prototype",
-  desktopFileKey: "abc123...",
-  mobileFileKey: "def456...",
+const config: FigmaPrototypeViewerConfig = {
+  title: 'Onboarding Flow',
+  desktopFileKey: 'abc123XYZ',
+  mobileFileKey: 'xyz789ABC',
+  desktopStartingPoint: '1:23',
+  mobileStartingPoint: '4:56',
   sections: [
     {
-      id: "onboarding",
-      number: "01",
-      title: "User Onboarding",
-      startingNodeId: "123:456",
-      mobileStartingNodeId: "789:012"
-    }
+      id: 'sign-up',
+      number: '01',
+      title: 'Sign Up',
+      description: 'New user registration flow',
+      startingNodeId: '1:23',
+      mobileStartingNodeId: '4:56',
+    },
   ],
+  mobileContentDimensions: { width: 343, height: 600 },
   desktopContentDimensions: { width: 944, height: 600 },
-  mobileContentDimensions: { width: 343, height: 600 }
 }
 
-function PrototypePage() {
-  return (
-    <FigmaPrototypeViewer 
-      config={config}
-      onSectionClick={(sectionId) => console.log('Section changed:', sectionId)}
-    />
-  )
+export default function PrototypePage() {
+  return <FigmaPrototypeViewer config={config} />
 }
-```
-
-The component automatically detects device capabilities, manages iframe states (loading, ready, reloading), and provides smooth transitions between sections. Environment variables can override config settings for deployment flexibility.
+```

package/src/components/features/.filters-dropdown.md

@@ -1,61 +1,48 @@
-<!-- source-hash: 43ec97c557bde453e1b537b137f6f8db -->
-A customizable dropdown component for filtering UI elements with multi-section support, checkboxes, radio buttons, and responsive mobile behavior.
+<!-- source-hash: a3c5543a6675d1ff7a726459eb736d56 -->
+Animated filter dropdown component for selecting, applying, and resetting multi-section filter configurations with support for checkbox, radio, and select modes.
 
 ## Key Components
 
-- **FilterOption**: Interface defining individual filter options with id, label, value, and optional separator type
-- **FilterSection**: Interface for grouping filters by type (checkbox/radio/select) with optional select-all functionality
-- **FilterCheckbox**: Custom checkbox component with Flamingo branding (yellow accent color)
-- **FiltersDropdown**: Main dropdown component with intelligent positioning, mobile responsiveness, and state management
+### Interfaces
+- **`FilterOption`** — Individual filter item with `id`, `label`, `value`, optional `count`, and `type`
+- **`FilterSection`** — Grouping of options with a selection `type` (`"checkbox"` | `"radio"` | `"select"`), optional `allowSelectAll`, and `defaultSelected`
+- **`FiltersDropdownProps`** — Full component props including `sections`, `onApply`, `onReset`, `currentFilters`, and `placement`
+
+### Internal Components
+- **`FilterCheckbox`** — Styled checkbox with accent fill and checkmark icon when selected
+
+### Main Export
+- **`FiltersDropdown`** — Dropdown panel with animated open/close (mount/unmount + CSS transitions), smart viewport-aware placement, mobile-responsive layout, outside-click and Escape key dismissal, and active filter count indicator
 
 ## Usage Example
 
 ```typescript
-import { FiltersDropdown, FilterSection } from './filters-dropdown'
-
-const filterSections: FilterSection[] = [
+const sections: FilterSection[] = [
   {
-    id: 'status',
-    title: 'Status',
-    type: 'checkbox',
+    id: "status",
+    title: "Status",
+    type: "checkbox",
     allowSelectAll: true,
     options: [
-      { id: 'active', label: 'Active', value: 'active' },
-      { id: 'inactive', label: 'Inactive', value: 'inactive' },
-      { id: 'pending', label: 'Pending', value: 'pending' }
-    ]
+      { id: "open", label: "Open", value: "open", count: 12 },
+      { id: "closed", label: "Closed", value: "closed", count: 4 },
+    ],
   },
-  {
-    id: 'priority',
-    title: 'Priority',
-    type: 'radio',
-    options: [
-      { id: 'high', label: 'High', value: 'high' },
-      { id: 'medium', label: 'Medium', value: 'medium' },
-      { id: 'low', label: 'Low', value: 'low' }
-    ]
-  }
 ]
 
-function MyComponent() {
-  const [appliedFilters, setAppliedFilters] = useState({})
-
-  const handleApplyFilters = (filters: Record<string, string[]>) => {
-    setAppliedFilters(filters)
-    // Apply filters to your data
-  }
-
-  return (
-    <FiltersDropdown
-      triggerLabel="Filter Items"
-      sections={filterSections}
-      onApply={handleApplyFilters}
-      currentFilters={appliedFilters}
-      placement="bottom-start"
-      responsive={true}
-    />
-  )
-}
+const [appliedFilters, setAppliedFilters] = useState<Record<string, string[]>>({})
+
+<FiltersDropdown
+  sections={sections}
+  triggerLabel="STATUS"
+  placement="bottom-start"
+  currentFilters={appliedFilters}
+  onApply={(filters) => setAppliedFilters(filters)}
+  onReset={() => setAppliedFilters({})}
+/>
 ```
 
-The component features intelligent positioning to avoid viewport overflow, mobile-responsive behavior with full-width dropdowns, and preserves filter state when reopening. It supports custom trigger elements and includes visual indicators for active filter counts.
+### Key Behaviors
+- `currentFilters` syncs external state back into the dropdown when reopened
+- Placement auto-adjusts (`bottom-start` ↔ `bottom-end`) based on available viewport space
+- On mobile (`< 640px`), the panel switches to a fixed, full-width overlay mode

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

@@ -0,0 +1,42 @@
+<!-- source-hash: d7af9befa8736257f5fa1a7169b8bc9d -->
+Reusable configuration section component for highlight video generation settings, providing duration selection and subtitle burning controls in a unified horizontal layout.
+
+## Key Components
+
+### `HighlightConfigSection`
+A client-side React component used across `CustomerInterview` and `ProductRelease` entity workflows to configure highlight video output options.
+
+### `HighlightConfigSectionProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `targetDurationSeconds` | `number` | Current selected duration in seconds |
+| `onTargetDurationChange` | `(seconds: number) => void` | Callback fired on duration change |
+| `skipSubtitleBurning` | `boolean` | Whether subtitle burning is skipped |
+| `onSkipSubtitleBurningChange` | `(skip: boolean) => void` | Callback fired on subtitle toggle |
+| `disabled` | `boolean?` | Disables all controls (default: `false`) |
+| `className` | `string?` | Additional CSS class override |
+
+**Duration options:** 60s, 120s, 180s *(recommended)*, 240s, 300s
+
+## Usage Example
+
+```typescript
+import { HighlightConfigSection } from './highlight-config-section';
+
+function VideoEditor() {
+  const [duration, setDuration] = useState(180);
+  const [skipSubs, setSkipSubs] = useState(false);
+
+  return (
+    <HighlightConfigSection
+      targetDurationSeconds={duration}
+      onTargetDurationChange={setDuration}
+      skipSubtitleBurning={skipSubs}
+      onSkipSubtitleBurningChange={setSkipSubs}
+      disabled={false}
+    />
+  );
+}
+```
+
+> **Note:** Renders as a dark-themed panel (`bg-[#1a1a1a]`) with a `Select` dropdown for duration and a checkbox for subtitle burning, laid out horizontally via flexbox.

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

@@ -0,0 +1,46 @@
+<!-- source-hash: 9a48f5db58e0fc209ed8daeba5dd9324 -->
+A reusable React wrapper around `AIEnrichSection` that provides a standardized UI for triggering AI-powered highlight video generation for `CustomerInterview` and `ProductRelease` entities.
+
+## Key Components
+
+### `HighlightGenerationSection`
+The primary export — a thin, opinionated wrapper that pre-configures `AIEnrichSection` with highlight-specific defaults:
+
+| Prop | Type | Default |
+|------|------|---------|
+| `onGenerateHighlight` | `() => void` | — |
+| `isProcessing` | `boolean` | — |
+| `canEnrich` | `boolean` | — |
+| `requiredFields` | `AIRequiredField[]` | — |
+| `targetDurationSeconds` | `number` | `180` |
+| `hasResult` | `boolean` | `false` |
+| `disabledMessage` | `string` | `"Upload a video and run transcription first"` |
+| `showCancel` | `boolean` | `true` |
+| `loadingLabel` | `string` | `"Generating highlight..."` |
+
+### `HighlightGenerationSectionProps`
+The exported interface describing all configurable props, including optional overrides for `title`, `description`, `buttonLabel`, and cancellation controls.
+
+## Usage Example
+
+```typescript
+import { HighlightGenerationSection } from './highlight-generation-section';
+
+<HighlightGenerationSection
+  onGenerateHighlight={handleGenerate}
+  isProcessing={isGenerating}
+  canEnrich={hasTranscription}
+  requiredFields={[
+    { label: 'Video Upload', satisfied: hasVideo },
+    { label: 'Transcription', satisfied: hasTranscription },
+  ]}
+  hasResult={!!highlightUrl}
+  targetDurationSeconds={120}
+  onCancel={handleCancel}
+  isCancelling={isCancelling}
+  status={status}
+  statusMessage={statusMessage}
+/>
+```
+
+> **Note:** Pair this component with `HighlightConfigSection` for the full highlight generation experience. The button label automatically switches between `"Generate Highlight"` and `"Regenerate Highlight"` based on the `hasResult` prop.

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

@@ -0,0 +1,47 @@
+<!-- source-hash: 396284dd8be1b09a6ecb781dd4fed0ce -->
+Unified React component that combines highlight video configuration, AI-powered generation, and video preview/upload into a single composable section used across multiple modal contexts.
+
+## Key Components
+
+### `HighlightVideoCombinedSection`
+The primary export. Renders three sequential sub-sections:
+1. **`HighlightConfigSection`** — Duration and subtitle burning settings
+2. **`AIEnrichSection`** — AI generation trigger with status feedback and cancel support
+3. **Preview + Upload** — Inline video preview with manual upload fallback
+
+### `HighlightVideoCombinedSectionProps`
+Full interface grouping props into four logical namespaces:
+- **Config** — `targetDurationSeconds`, `skipSubtitleBurning`, `configDisabled`
+- **Generation** — `onGenerateHighlight`, `isProcessing`, `canEnrich`, `requiredFields`, `status`
+- **Preview** — `highlightVideoUrl`, `highlightVideoThumbnail`, `renderVideoPreview`, `onUpload`, `onDelete`
+- **Common** — `className`, `title`, `description`, `buttonLabel`
+
+## Usage Example
+
+```typescript
+<HighlightVideoCombinedSection
+  // Config
+  targetDurationSeconds={120}
+  onTargetDurationChange={(s) => setDuration(s)}
+  skipSubtitleBurning={false}
+  onSkipSubtitleBurningChange={(v) => setSkipSubs(v)}
+  // Generation
+  onGenerateHighlight={handleGenerate}
+  isProcessing={isGenerating}
+  canEnrich={hasTranscript}
+  requiredFields={[{ key: 'transcript', label: 'Transcription' }]}
+  status={jobStatus}
+  statusMessage={jobMessage}
+  onCancel={handleCancel}
+  hasResult={!!highlightUrl}
+  // Preview
+  highlightVideoUrl={highlightUrl}
+  onUpload={async (file) => await uploadFile(file)}
+  onDelete={async () => await deleteHighlight()}
+  renderVideoPreview={({ videoUrl, title, thumbnailUrl, onDelete }) => (
+    <VideoPlayer url={videoUrl} thumbnail={thumbnailUrl} onDelete={onDelete} />
+  )}
+/>
+```
+
+> **Note:** `renderVideoPreview` uses a render-prop pattern, keeping the component decoupled from any specific video player implementation. The manual upload uses a hidden `<input type="file">` created programmatically to avoid controlled input complexity.

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

@@ -0,0 +1,44 @@
+<!-- source-hash: 9c2fe27cb025dab5e630418cc7b208a0 -->
+Reusable React component for displaying and managing highlight video previews with support for manual upload, AI-generated badges, and duration display.
+
+## Key Components
+
+### `HighlightVideoPreviewProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `highlightVideoUrl` | `string \| null` | URL of the highlight video |
+| `highlightVideoThumbnail` | `string \| null` | Thumbnail image 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 |
+| `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.
+
+## Usage Example
+
+```typescript
+import { HighlightVideoPreview } from './highlight-video-preview';
+
+<HighlightVideoPreview
+  highlightVideoUrl="https://cdn.example.com/video.mp4"
+  highlightVideoThumbnail="https://cdn.example.com/thumb.jpg"
+  highlightVideoDurationMs={125000}
+  highlightVideoSource="ai_generated"
+  onUpload={async (file) => {
+    const url = await uploadToStorage(file);
+    return url;
+  }}
+  onDelete={async () => {
+    await deleteVideo();
+  }}
+  renderVideoPreview={({ videoUrl, thumbnailUrl, onDelete }) => (
+    <VideoPlayer src={videoUrl} poster={thumbnailUrl} onDelete={onDelete} />
+  )}
+/>
+```
+
+> **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.