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

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

@@ -1,35 +1,32 @@
-<!-- source-hash: 2cb028936365715865c9571d3df0261e -->
-A reusable React component for managing a dynamic list of changelog entries, supporting add, remove, expand/collapse, and optional per-entry visibility toggling.
+<!-- source-hash: e6737cc6f4757d68e83c3688abe95603 -->
+A reusable React client component for managing a list of collapsible changelog entries, supporting add, remove, expand/collapse, field editing, and optional per-entry public/internal visibility toggling.
 
 ## Key Components
 
 ### `ChangelogManager` (default export)
 
-A controlled list manager rendered as a collapsible accordion of `ChangelogEntry` items.
+A controlled component that renders a titled list of `ChangelogEntry` items with accordion-style expand/collapse behavior.
 
 **Props (`ChangelogManagerProps`):**
 
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `title` | `string` | Section label displayed above the entry list |
 | `entries` | `ChangelogEntry[]` | Controlled array of changelog entries |
 | `onChange` | `(entries: ChangelogEntry[]) => void` | Callback fired on any mutation |
-| `className` | `string?` | Optional wrapper class override |
-| `expandAll` | `boolean?` | When `true`, expands all items (e.g. post-AI enrichment) |
-| `showVisibilityToggle` | `boolean?` | Renders a per-entry `Eye`/`EyeOff` toggle; used by investor updates |
+| `className` | `string?` | Optional CSS class override |
+| `expandAll` | `boolean?` | When `true`, expands all entries (e.g., after AI enrichment) |
+| `showVisibilityToggle` | `boolean?` | Enables per-entry Eye/EyeOff toggle for investor update flows |
 
 **Internal state:**
-- `expandedIndices` — `Set<number>` tracking which accordion items are open
+- `expandedIndices` — `Set<number>` tracking which entries are currently expanded
 
-**Key functions:**
-
-| Function | Behavior |
-|----------|----------|
-| `addEntry()` | Appends a blank entry and auto-expands it |
-| `removeEntry(index)` | Removes entry and adjusts the expanded indices set |
-| `updateEntry(index, field, value)` | Immutably updates a single field on an entry |
-| `toggleExpanded(index)` | Toggles accordion open/close state |
-| `toggleVisibility(index)` | Flips `visibility` between `'public'` and `'internal'` |
+**Key handlers:**
+- `addEntry` — appends a blank entry and auto-expands it; defaults `visibility` to `'public'` when `showVisibilityToggle` is enabled
+- `removeEntry` — filters out the entry and re-indexes `expandedIndices`
+- `updateEntry` — immutably patches a single field on an entry
+- `toggleExpanded` — toggles an index in the expanded set
+- `toggleVisibility` — flips an entry between `'public'` and `'internal'`
 
 ## Usage Example
 
@@ -39,14 +36,14 @@ import type { ChangelogEntry } from '../../types/product-release';
 
 const [entries, setEntries] = useState<ChangelogEntry[]>([]);
 
-// Basic product release changelog
+// Basic product release usage
 <ChangelogManager
   title="What's New"
   entries={entries}
   onChange={setEntries}
 />
 
-// Investor update with visibility control + auto-expand after AI fill
+// Investor update usage with visibility controls
 <ChangelogManager
   title="Highlights"
   entries={entries}
@@ -56,4 +53,4 @@ const [entries, setEntries] = useState<ChangelogEntry[]>([]);
 />
 ```
 
-> **Note:** `showVisibilityToggle` is intended for investor update flows. Leave it unset for standard product release changelogs to preserve their default UX. New entries default to `visibility: 'public'` when the toggle is enabled.
+> **Source:** [`changelog-manager.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/changelog-manager.tsx)

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

@@ -1,20 +1,16 @@
-<!-- source-hash: b7d1c615d3d37a540958daff7feed5f3 -->
-A reusable React component for displaying command strings in a styled monospace box with optional title and configurable action buttons.
+<!-- source-hash: 7694600bf3dea6d86fe13d3363d55f23 -->
+A unified React component for displaying command strings with optional action buttons, monospace formatting, and configurable line clamping.
 
 ## Key Components
 
 ### 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` |
+- **`CommandBoxAction`** — Defines a button's `label`, `onClick` handler, optional `variant` (`accent` | `outline` | `transparent` | `destructive`), `icon`, `disabled`, and `loading` states.
+- **`CommandBoxProps`** — Component props including `command` (required), `title`, `primaryAction`, `secondaryAction`, `className`, `commandClassName`, and `maxLines`.
 
 ### Exports
 
-- **`CommandBox`** — Main component rendering the command display box
-- **`CommandBoxAction`** — Interface for action button configuration
-- **`CommandBoxProps`** — Interface for component props
+- **`CommandBox`** — Main component rendering a styled command display area with up to two action buttons (primary stacked right, secondary before primary). Supports responsive flex layout (`flex-col` → `md:flex-row`).
 
 ## Usage Example
 
@@ -30,21 +26,20 @@ import { Copy, Play } from 'lucide-react'
     label: 'Copy Command',
     onClick: () => navigator.clipboard.writeText(command),
     icon: <Copy className="w-5 h-5" />,
-    variant: 'accent'
+    variant: 'accent',
   }}
   secondaryAction={{
-    label: 'Run on Machine',
+    label: 'Run on Current Machine',
     onClick: handleRun,
     icon: <Play className="w-5 h-5" />,
     variant: 'outline',
-    loading: isRunning
+    loading: isRunning,
   }}
 />
 ```
 
 ## 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.
+- **Line clamping** uses a static `lineClampClasses` map (`1`–`6`) to satisfy Tailwind's build-time static class requirement. Set `maxLines={0}` (default) for unlimited display.
+- Button variants default to `accent` for primary and `outline` for secondary if not specified.
+- Source: [`command-box.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/command-box.tsx)

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

@@ -1,24 +1,26 @@
-<!-- source-hash: 87dfd7f5b94bff0f44ed579685785b88 -->
-Reusable editor component for entity summary fields with AI generation badges and confidence score display.
+<!-- source-hash: e1202aba2fe24c4e9ad695931c0b8d92 -->
+A reusable React component for editing entity summaries (e.g., Release Summary, Interview Summary) with built-in support for AI generation badges and confidence score display.
 
 ## Key Components
 
-**`EntitySummaryEditor`** — Default export. A controlled textarea editor with optional AI metadata indicators.
+### `EntitySummaryEditor`
+The primary exported component rendering a labeled textarea with optional AI metadata indicators.
 
-**`EntitySummaryEditorProps`** — TypeScript interface defining all configurable props:
+### `EntitySummaryEditorProps`
+TypeScript interface defining the component's configuration:
 
 | 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 |
+|---|---|---|---|
+| `summary` | `string` | `''` | Current summary text value |
+| `onSummaryChange` | `(value: string) => void` | — | Change handler callback |
+| `isAIGenerated` | `boolean` | `false` | Shows `AIGeneratedBadge` when `true` |
+| `summaryConfidence` | `number \| null` | — | Confidence score (0–100) shown via `ConfidenceBadge` |
+| `label` | `string` | `'Summary (Markdown supported)'` | Field label text |
 | `helperText` | `string` | `'Entity summary...'` | Subtext below label |
 | `placeholder` | `string` | `'Brief summary...'` | Textarea placeholder |
-| `minHeight` | `number` | `200` | Minimum height in px |
+| `minHeight` | `number` | `200` | Minimum textarea height in pixels |
 | `disabled` | `boolean` | `false` | Disables the textarea |
-| `className` | `string` | `''` | Container class override |
+| `className` | `string` | `''` | Additional CSS classes on the container |
 
 ## Usage Example
 
@@ -35,12 +37,15 @@ function ReleaseForm() {
       isAIGenerated={true}
       summaryConfidence={87}
       label="Release Summary (Markdown supported)"
-      helperText="Displayed on release cards and detail page."
       placeholder="Describe this release..."
-      minHeight={240}
+      minHeight={250}
     />
   );
 }
 ```
 
-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.
+## Notes
+
+- Markdown is supported in the textarea value but rendering is handled upstream by the consumer.
+- `ConfidenceBadge` only renders when `summaryConfidence` is a non-null, non-undefined number.
+- Uses ODS design tokens (`ods-text-primary`, `ods-border`, `ods-card`) for theming consistency.

package/src/components/features/.entity-tag-badges.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 5f96942688ffceb3aba7f0e1cb5d04a5 -->
+Renders a row of OpenFrame-styled tag badges from a flat entity-tags association array, with optional click-through filtering and overflow collapsing.
+
+## Key Components
+
+### `EntityTagBadges` (exported component)
+The single canonical tag-badge renderer for the entire product. Accepts a `TagAssoc[]` array and maps each entry to a `StatusBadge` chip. Returns `null` when the tag list is empty.
+
+### `TAG_BADGE_CLASS` (exported constant)
+The shared CSS class string (`bg-ods-card border border-ods-border`) that defines the OpenFrame tag chip skin. Exported so other components (e.g. `FaqAccordion` section badges) can reuse the identical appearance without duplicating styles.
+
+### Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `tags` | `TagAssoc[] \| null` | Flat association array from entity hydration |
+| `basePath` | `string` | When set, wraps each slugged badge in a `next/link` to `${basePath}?tags=${slug}` |
+| `max` | `number` | Cap on visible badges; extras collapse into a `+N` overflow badge |
+| `className` | `string` | Extra classes on the wrapper `div` |
+
+## Usage Example
+
+```typescript
+// Non-interactive display
+<EntityTagBadges tags={article.article_tags} />
+
+// Clickable badges linking to filtered list
+<EntityTagBadges
+  tags={article.article_tags}
+  basePath="/blog"
+  max={5}
+  className="mt-2"
+/>
+
+// Reuse the tag skin on a custom chip
+import { TAG_BADGE_CLASS } from './entity-tag-badges'
+
+<StatusBadge text="SECTION" variant="card" className={TAG_BADGE_CLASS} />
+```
+
+**Overflow behavior:** `max={0}` shows no badges; `max={null | undefined}` shows all. Tags without a `slug` render as non-interactive even when `basePath` is provided.
+
+> **Source:** [`entity-tag-badges.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/entity-tag-badges.tsx)

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

@@ -1,28 +1,16 @@
-<!-- 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.
+<!-- source-hash: 995d46df2c0fb31513779a266d32e0e3 -->
+Renders the video block for a public entity detail page, combining a full video, AI-generated highlights, markdown summary, and video bites strip into a single composable section.
 
 ## 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` |
+**`EntityVideoSection`** — Primary export. Orchestrates three sub-sections:
+- **Tabbed video player** — shows "Full Video" / "Highlights" tabs when both exist; falls back to a single `<Video>` if only one is available. YouTube URL takes precedence over `mainVideoUrl` when both are provided.
+- **Markdown summary** — Rendered via an injected `MarkdownRenderer` component when `videoSummary` is present.
+- **Video bites strip** — Scrollable `<VideoBitesStrip>` rendered when `videoBites` array is non-empty.
+
+Returns `null` when no video, summary, or bites are available.
+
+**`EntityVideoSectionProps`** — Full prop interface covering video URLs, captions, poster images, bites configuration, and the injected markdown renderer.
 
 ## Usage Example
 
@@ -30,22 +18,24 @@ Full interface for controlling content and behavior:
 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
-    />
-  );
-}
-```
+<EntityVideoSection
+  youtubeUrl="https://www.youtube.com/watch?v=abc123"
+  highlightVideoUrl="https://cdn.example.com/highlight.mp4"
+  highlightVideoThumbnail="https://cdn.example.com/thumb.jpg"
+  title="Product Demo"
+  videoSummary="**Overview:** This video covers..."
+  videoBites={bites}
+  bitesTitle="Key Moments"
+  bitesProfile={speakerProfile}
+  bitesHref="/events/product-demo"
+  filterPublishedBites
+  priority
+  MarkdownRenderer={MarkdownRenderer}
+/>
+```
+
+## Notes
+
+- `youtubeUrl` always wins over `mainVideoUrl` when both are set — resolved at the section level to keep `<Video>` single-source-per-render.
+- `srtContent` is deprecated; use `captionsUrl` (VTT) instead.
+- `priority` forwards an LCP hint to the full-video tab's poster image.

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

@@ -1,37 +1,34 @@
-<!-- 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.
+<!-- source-hash: 498b200b8dc21bf9ce26af638e0ae002 -->
+Renders an interactive Figma prototype viewer with responsive scaling, section navigation, and multi-device support (desktop, mobile, touch). Integrates directly with the Figma Embed API and manages iframe lifecycle states.
 
 ## Key Components
 
-### 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'`
+### Exported Interfaces
+- **`FigmaPrototypeSection`** — Defines a navigable section with `id`, `number`, `title`, optional `description`, and per-device starting node IDs
+- **`FigmaPrototypeViewerConfig`** — Full viewer configuration including file keys (mobile/desktop/legacy), section list, dimension overrides, and CSS class customization
+- **`FigmaPrototypeViewerProps`** — Component props wrapping config with optional external section control
 
-### 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
+### Internal Types
+- **`ViewMode`** — `'DESKTOP' | 'MOBILE' | 'MOBILE_TOUCH'` — determined by screen width and touch capability
+- **`IframeState`** — Lifecycle states: `INITIAL → LOADING → READY`, plus `RELOADING` and `SLEEP_RECOVERY`
+- **`UnifiedState`** — Single source of truth for all rendering decisions (scaling, visibility flags, navigation)
 
-### Environment Variable Overrides
-Content dimensions and file keys can be set at the environment level:
+### Core Utility Functions
 
+| Function | Purpose |
+|---|---|
+| `getViewMode` | Classifies device based on screen width and touch support |
+| `calculateScaling` | Computes `scale`, `marginX`, `marginY` to fit content without upscaling |
+| `resolveFileKey` | Priority chain: env var → config field → legacy `fileKey` |
+| `resolveStartingPoint` | Priority chain: section node → env var → config → first section |
+| `generateEmbedUrl` | Builds Figma embed URL with correct params for device mode |
+| `renderUnifiedUI` | Renders full UI from declarative `UnifiedState` (section selector + iframe container) |
+
+### Configuration Priority (highest → lowest)
 ```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
+NEXT_PUBLIC_FIGMA_* env vars → config props → defaults
 ```
 
-Priority order: **env vars → config props → defaults**
-
 ## Usage Example
 
 ```typescript
@@ -40,25 +37,46 @@ import type { FigmaPrototypeViewerConfig } from './figma-prototype-viewer'
 
 const config: FigmaPrototypeViewerConfig = {
   title: 'Onboarding Flow',
-  desktopFileKey: 'abc123XYZ',
-  mobileFileKey: 'xyz789ABC',
-  desktopStartingPoint: '1:23',
-  mobileStartingPoint: '4:56',
+  desktopFileKey: 'abc123desktop',
+  mobileFileKey: 'abc123mobile',
+  desktopContentDimensions: { width: 1280, height: 720 },
+  mobileContentDimensions: { width: 390, height: 844 },
   sections: [
     {
-      id: 'sign-up',
+      id: 'welcome',
       number: '01',
-      title: 'Sign Up',
-      description: 'New user registration flow',
+      title: 'Welcome Screen',
       startingNodeId: '1:23',
-      mobileStartingNodeId: '4:56',
+      mobileStartingNodeId: '1:45'
     },
+    {
+      id: 'setup',
+      number: '02',
+      title: 'Account Setup',
+      startingNodeId: '2:10'
+    }
   ],
-  mobileContentDimensions: { width: 343, height: 600 },
-  desktopContentDimensions: { width: 944, height: 600 },
+  defaultSectionId: 'welcome'
 }
 
 export default function PrototypePage() {
-  return <FigmaPrototypeViewer config={config} />
+  return (
+    <FigmaPrototypeViewer
+      config={config}
+      onSectionClick={(id) => console.log('Navigated to:', id)}
+    />
+  )
 }
-```
+```
+
+**Environment variable overrides** (`.env.local`):
+```bash
+NEXT_PUBLIC_FIGMA_DESKTOP_FILE_KEY=your_desktop_key
+NEXT_PUBLIC_FIGMA_MOBILE_FILE_KEY=your_mobile_key
+NEXT_PUBLIC_FIGMA_DESKTOP_STARTING_POINT=1:23
+NEXT_PUBLIC_FIGMA_MOBILE_STARTING_POINT=1:45
+NEXT_PUBLIC_FIGMA_DESKTOP_WIDTH=1280
+NEXT_PUBLIC_FIGMA_DESKTOP_HEIGHT=720
+```
+
+**Source:** [`figma-prototype-viewer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/figma-prototype-viewer.tsx)

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

@@ -1,18 +1,18 @@
-<!-- source-hash: a3c5543a6675d1ff7a726459eb736d56 -->
-Animated filter dropdown component for selecting, applying, and resetting multi-section filter configurations with support for checkbox, radio, and select modes.
+<!-- source-hash: d381c68a67f3266ee8051c01fe38ea1d -->
+Accessible, animated filter dropdown component with support for checkbox, radio, and multi-section filter configurations.
 
 ## Key Components
 
 ### 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`
+- **`FilterOption`** — Defines individual filter items with `id`, `label`, `value`, optional `count`, and `type` (`'option' | 'separator'`)
+- **`FilterSection`** — Groups related filter options with a `type` (`"checkbox" | "radio" | "select"`), optional `allowSelectAll`, and `defaultSelected`
+- **`FiltersDropdownProps`** — Full component props including custom trigger, section definitions, callbacks, placement, and `currentFilters` for controlled state
 
 ### Internal Components
-- **`FilterCheckbox`** — Styled checkbox with accent fill and checkmark icon when selected
+- **`FilterCheckbox`** — Custom 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
+### Main Component: `FiltersDropdown`
+Manages open/close animation (mount/unmount split via `shouldRender`/`isVisible`), viewport-aware placement, mobile responsiveness, outside-click and Escape-key dismissal, per-section selection state, and filter application/reset.
 
 ## Usage Example
 
@@ -25,7 +25,7 @@ const sections: FilterSection[] = [
     allowSelectAll: true,
     options: [
       { id: "open", label: "Open", value: "open", count: 12 },
-      { id: "closed", label: "Closed", value: "closed", count: 4 },
+      { id: "closed", label: "Closed", value: "closed", count: 5 },
     ],
   },
 ]
@@ -42,7 +42,8 @@ const [appliedFilters, setAppliedFilters] = useState<Record<string, string[]>>({
 />
 ```
 
-### 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
+## Notes
+
+- **Animation**: Uses a double `requestAnimationFrame` pattern to ensure CSS transitions fire correctly on mount; `shouldRender`/`isVisible` are intentionally separate to allow smooth enter/exit without `@keyframes`.
+- **Placement auto-correction**: Dynamically overrides the `placement` prop if the dropdown would overflow the viewport.
+- **`currentFilters` sync**: Serialized to a JSON string for stable `useEffect` dependency comparison, avoiding infinite re-render loops.

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

@@ -1,31 +1,34 @@
-<!-- source-hash: d7af9befa8736257f5fa1a7169b8bc9d -->
-Reusable configuration section component for highlight video generation settings, providing duration selection and subtitle burning controls in a unified horizontal layout.
+<!-- source-hash: 3a44a8796eef8d6a87cab9dd243384f5 -->
+Reusable React configuration panel 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.
+
+A client-side React component that renders two controls side-by-side:
+
+- **Target Duration Select** — dropdown offering 1–5 minute presets (3 minutes recommended) via a controlled `<Select>` component
+- **Skip Subtitle Burning Checkbox** — toggle to bypass subtitle burn-in during video processing
 
 ### `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
+| Prop | Type | Description |
+|---|---|---|
+| `targetDurationSeconds` | `number` | Current duration value in seconds |
+| `onTargetDurationChange` | `(seconds: number) => void` | Fires on duration selection change |
+| `skipSubtitleBurning` | `boolean` | Current subtitle skip state |
+| `onSkipSubtitleBurningChange` | `(skip: boolean) => void` | Fires on checkbox toggle |
+| `disabled` | `boolean` | Disables all controls (default: `false`) |
+| `className` | `string` | Optional extra CSS classes |
 
 ## Usage Example
 
 ```typescript
 import { HighlightConfigSection } from './highlight-config-section';
 
-function VideoEditor() {
-  const [duration, setDuration] = useState(180);
-  const [skipSubs, setSkipSubs] = useState(false);
+function MyHighlightForm() {
+  const [duration, setDuration] = React.useState(180); // 3 minutes default
+  const [skipSubs, setSkipSubs] = React.useState(false);
 
   return (
     <HighlightConfigSection
@@ -39,4 +42,4 @@ function VideoEditor() {
 }
 ```
 
-> **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.
+> **Note:** This component is designed to be shared across `CustomerInterview` and `ProductRelease` entity flows. View the source at [`highlight-config-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/highlight-config-section.tsx).

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

@@ -1,20 +1,20 @@
-<!-- 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.
+<!-- source-hash: 3e63796e9b4bf8c671743bc94b9dd017 -->
+Unified section component that combines highlight video configuration, AI-powered generation, and video preview/upload into a single composable UI block.
 
 ## 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
+The primary export. Orchestrates three sub-sections in a vertical stack:
+
+1. **`HighlightConfigSection`** — Duration and subtitle burn settings
+2. **`AIEnrichSection`** — Generation trigger button with status feedback and cancel support
+3. **Preview + Upload Panel** — Displays the current highlight video or an empty state, with a manual upload button
 
 ### `HighlightVideoCombinedSectionProps`
-Full interface grouping props into four logical namespaces:
+Full interface grouping props into three logical namespaces:
 - **Config** — `targetDurationSeconds`, `skipSubtitleBurning`, `configDisabled`
-- **Generation** — `onGenerateHighlight`, `isProcessing`, `canEnrich`, `requiredFields`, `status`
-- **Preview** — `highlightVideoUrl`, `highlightVideoThumbnail`, `renderVideoPreview`, `onUpload`, `onDelete`
-- **Common** — `className`, `title`, `description`, `buttonLabel`
+- **Generation** — `onGenerateHighlight`, `isProcessing`, `canEnrich`, `requiredFields`, `status`, `hasResult`
+- **Preview** — `highlightVideoUrl`, `highlightVideoSource`, `onUpload`, `onDelete`, `renderVideoPreview`
 
 ## Usage Example
 
@@ -25,23 +25,32 @@ Full interface grouping props into four logical namespaces:
   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}
+  canEnrich={hasTranscription}
+  requiredFields={[{ field: 'transcription', label: 'Transcription' }]}
+  status={generationStatus}
   hasResult={!!highlightUrl}
+  showCancel
+  onCancel={handleCancel}
+
   // Preview
   highlightVideoUrl={highlightUrl}
-  onUpload={async (file) => await uploadFile(file)}
-  onDelete={async () => await deleteHighlight()}
+  highlightVideoSource="ai_generated"
+  highlightVideoDurationMs={118000}
+  onUpload={async (file) => uploadToStorage(file)}
+  onDelete={async () => deleteHighlight()}
   renderVideoPreview={({ videoUrl, title, thumbnailUrl, onDelete }) => (
-    <VideoPlayer url={videoUrl} thumbnail={thumbnailUrl} onDelete={onDelete} />
+    <VideoPlayer url={videoUrl} title={title} 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.
+## Notes
+
+- `renderVideoPreview` follows a render-prop pattern, giving callers full control over the player UI.
+- The upload button creates a hidden `<input type="file">` via `document.createElement` — no DOM ref required.
+- Button label auto-toggles between `"Generate Highlight"` and `"Regenerate Highlight"` based on `hasResult`.
+- Default description is derived from `targetDurationSeconds`: `"Generate a N-minute summary video using Claude AI + Shotstack"`.