@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/features/.status-filter-component.md

@@ -1,40 +1,56 @@
-<!-- source-hash: 4db0e02f86ff4b3306433ead043438a2 -->
-A reusable status filter component for admin dashboards that displays filter buttons with an optional item count.
+<!-- source-hash: f987a6879214f07a120da4bd03335b15 -->
+Reusable client-side status filter component that renders a row of toggle buttons for filtering content by status, following the admin dashboard pattern used across the Flamingo/OpenFrame platform.
 
 ## Key Components
 
-- **StatusFilterComponent**: Main React component that renders a horizontal row of status filter buttons
-- **StatusOption**: Interface defining the structure for filter options with value and label
-- **StatusFilterComponentProps**: Props interface supporting status selection, change handlers, options, and optional count display
+### Interfaces
 
-The component automatically handles the "All" filter option separately and applies the ODS design system styling with responsive typography.
+| Interface | Description |
+|-----------|-------------|
+| `StatusOption` | Defines a filter option with `value` and `label` strings |
+| `StatusFilterComponentProps` | Full props contract for the component |
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectedStatus` | `string` | — | Currently active filter value |
+| `onStatusChange` | `(status: string) => void` | — | Callback fired on filter selection |
+| `statusOptions` | `StatusOption[]` | — | Array of filter options to render |
+| `showCount` | `boolean` | `false` | Toggles item count display |
+| `count` | `number` | `0` | Number shown when `showCount` is enabled |
+| `className` | `string` | `''` | Additional CSS classes for the wrapper |
+
+### Exported
+
+- `StatusFilterComponent` — named export, main component
+- `StatusOption` — exported interface
+- `StatusFilterComponentProps` — exported interface
 
 ## Usage Example
 
 ```typescript
 import { StatusFilterComponent, StatusOption } from './status-filter-component';
 
-const statusOptions: StatusOption[] = [
-  { value: 'published', label: 'Published' },
-  { value: 'draft', label: 'Draft' },
-  { value: 'archived', label: 'Archived' }
+const ticketStatusOptions: StatusOption[] = [
+  { value: 'open', label: 'Open' },
+  { value: 'in_progress', label: 'In Progress' },
+  { value: 'closed', label: 'Closed' },
 ];
 
-function BlogDashboard() {
-  const [selectedStatus, setSelectedStatus] = useState('all');
-  const [itemCount, setItemCount] = useState(42);
+export function TicketDashboard() {
+  const [status, setStatus] = React.useState('all');
 
   return (
     <StatusFilterComponent
-      selectedStatus={selectedStatus}
-      onStatusChange={setSelectedStatus}
-      statusOptions={statusOptions}
-      showCount={true}
-      count={itemCount}
-      className="mb-6"
+      selectedStatus={status}
+      onStatusChange={setStatus}
+      statusOptions={ticketStatusOptions}
+      showCount
+      count={42}
     />
   );
 }
 ```
 
-The component uses the Filter icon from Lucide React and integrates with the ODS design system for consistent styling across admin interfaces.
+> **Note:** The `'all'` option is always rendered as a dedicated button — any `StatusOption` with `value: 'all'` in the input array is automatically excluded from the mapped list to prevent duplication.

package/src/components/features/.tags-selector.md

@@ -1,45 +1,61 @@
-<!-- source-hash: 47cbe94daf59a2aa16dfaa405816a3d9 -->
-A comprehensive React component for selecting multiple tags with search functionality and visual chip display inside the input field.
+<!-- source-hash: 0d6f9a8deca3671804c89abef2d0469f -->
+A reusable React component for selecting and creating tags with search autocomplete, chip display, and tag limit enforcement.
 
 ## Key Components
 
-**TagsSelector** - Main component featuring:
-- Search autocomplete with dropdown suggestions
-- Selected tags displayed as removable chips inside the search input
-- Configurable tag limits (default 10)
-- Focus-triggered dropdown with all available tags
-- Real-time filtering based on search query
-- Disabled state support with visual feedback
+### `TagsSelector`
+Main exported component that renders a search input with inline tag chips, an autocomplete dropdown, and a tag counter.
 
-**Interfaces**:
-- `Tag` - Defines tag structure with id, name, and slug
-- `TagsSelectorProps` - Component configuration including available tags, selection state, and UI options
+**Props (`TagsSelectorProps`):**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `availableTags` | `Tag[]` | — | Pool of tags to search from |
+| `selectedTagIds` | `number[]` | — | Currently selected tag IDs |
+| `onTagsChange` | `(tagIds: number[]) => void` | — | Callback when selection changes |
+| `onCreateTag` | `(name: string) => Promise<Tag \| null>` | — | Optional async tag creation handler |
+| `maxTags` | `number` | `10` | Maximum selectable tags |
+| `allowCreate` | `boolean` | `true` | Enables the "Create tag" option |
+| `disabled` | `boolean` | `false` | Disables all interactions |
+
+### Internal Helpers
+
+- `handleTagAdd` — Adds a tag if not already selected and under the limit
+- `handleTagRemove` — Removes a tag chip from selection
+- `handleCreateTag` — Calls `onCreateTag`, auto-selects the result, manages loading state
+- `getFilteredTagsForAutocomplete` — Filters available tags by search query, excluding already selected
+- `tagExistsWithName` — Case-insensitive duplicate check before showing "Create" option
 
 ## Usage Example
 
 ```typescript
-import { TagsSelector } from './components/tags-selector';
+import { TagsSelector } from './tags-selector';
 
-const availableTags = [
-  { id: 1, name: 'React', slug: 'react' },
-  { id: 2, name: 'TypeScript', slug: 'typescript' },
-  { id: 3, name: 'Next.js', slug: 'nextjs' }
-];
-
-function BlogEditor() {
+function BlogPostForm() {
   const [selectedTagIds, setSelectedTagIds] = useState<number[]>([]);
 
+  const handleCreateTag = async (name: string) => {
+    const res = await fetch('/api/tags', {
+      method: 'POST',
+      body: JSON.stringify({ name }),
+    });
+    return res.json(); // { id, name, slug }
+  };
+
   return (
     <TagsSelector
-      availableTags={availableTags}
+      availableTags={[
+        { id: 1, name: 'MSP', slug: 'msp' },
+        { id: 2, name: 'AI', slug: 'ai' },
+      ]}
       selectedTagIds={selectedTagIds}
       onTagsChange={setSelectedTagIds}
+      onCreateTag={handleCreateTag}
       maxTags={5}
-      placeholder="Search and select tags..."
-      className="w-full"
+      placeholder="Search tags..."
     />
   );
 }
 ```
 
-The component automatically handles tag addition/removal, search filtering, and displays a counter showing current selection against the maximum limit. Selected tags appear as yellow chips with remove buttons directly in the search input area.
+> **Note:** The dropdown auto-opens on focus and supports keyboard creation — pressing `Enter` while typing a new tag name triggers `handleCreateTag` when `allowCreate` is enabled.

package/src/components/features/.transcribe-and-summarize-combined-section.md

@@ -0,0 +1,45 @@
+<!-- source-hash: a9ac065f3da523be3fea0a878f95156f -->
+Unified React component that combines the `AIEnrichSection` (trigger button + status) and `TranscriptSummaryEditor` (editable output fields) into a single cohesive UI for video transcription and summarization workflows.
+
+## Key Components
+
+- **`TranscribeAndSummarizeCombinedSection`** — Default export; renders an `AIEnrichSection` followed by a `TranscriptSummaryEditor` in a vertical stack
+- **`TranscribeAndSummarizeCombinedSectionProps`** — Full interface merging props from both child components, split into two logical groups via inline comments
+- Automatically resolves `buttonLabel` to `"Generate"` or `"Regenerate"` based on the `hasResult` flag when no custom label is provided
+
+## Usage Example
+
+```typescript
+import { TranscribeAndSummarizeCombinedSection } from './transcribe-and-summarize-combined-section';
+
+<TranscribeAndSummarizeCombinedSection
+  // Trigger controls
+  onTranscribe={handleTranscribe}
+  isProcessing={isLoading}
+  canEnrich={!!videoFile}
+  requiredFields={[{ label: 'Video file', met: !!videoFile }]}
+  status={status}
+  statusMessage={statusMessage}
+  hasResult={!!transcript}
+  showCancel
+  onCancel={handleCancel}
+
+  // Editor content
+  videoSummary={summary}
+  onVideoSummaryChange={setSummary}
+  transcript={transcript}
+  onTranscriptChange={setTranscript}
+  isAIGenerated={isAIGenerated}
+  videoSummaryConfidence={0.92}
+  transcriptConfidence={0.88}
+  subtitles={srtContent}
+  onSubtitlesChange={setSrtContent}
+  hasSubtitles={hasSubtitles}
+/>
+```
+
+## Notes
+
+- Used by both `CustomerInterview` and `ProductRelease` modals
+- All text labels (`title`, `description`, `videoSummaryLabel`, etc.) are fully customizable with sensible defaults
+- The `disabled` prop propagates only to `TranscriptSummaryEditor`, not to the enrich trigger button

package/src/components/features/.transcribe-summarize-section.md

@@ -0,0 +1,48 @@
+<!-- source-hash: e9e7f82a90db0014d3b7c868be383461 -->
+A reusable React wrapper around `AIEnrichSection` that provides a standardized UI for video transcription and summarization workflows across `CustomerInterview` and `ProductRelease` entities.
+
+## Key Components
+
+### `TranscribeSummarizeSection`
+The primary export — a client-side React component that delegates rendering to `AIEnrichSection` with transcription-specific defaults.
+
+### `TranscribeSummarizeSectionProps`
+Full TypeScript interface exposing all configurable props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onTranscribe` | `() => void` | — | Triggers transcription processing |
+| `isProcessing` | `boolean` | — | Controls loading state |
+| `canEnrich` | `boolean` | — | Enables/disables the action button |
+| `requiredFields` | `AIRequiredField[]` | — | Fields displayed as prerequisites |
+| `hasResult` | `boolean` | `false` | Switches button label to "Regenerate" |
+| `disabledMessage` | `string` | `"Upload a video first"` | Shown when button is disabled |
+| `title` | `string` | `"Transcribe & Summarize"` | Section heading |
+| `description` | `string` | `"Generate transcript..."` | Section subtext |
+| `loadingLabel` | `string` | `"Processing..."` | Label during active processing |
+| `showCancel` | `boolean` | `true` | Toggles cancel button visibility |
+
+## Usage Example
+
+```typescript
+import { TranscribeSummarizeSection } from './transcribe-summarize-section';
+
+function CustomerInterviewPanel() {
+  const [isProcessing, setIsProcessing] = React.useState(false);
+
+  return (
+    <TranscribeSummarizeSection
+      onTranscribe={() => setIsProcessing(true)}
+      isProcessing={isProcessing}
+      canEnrich={true}
+      requiredFields={[{ key: 'videoUrl', label: 'Video URL' }]}
+      hasResult={false}
+      onCancel={() => setIsProcessing(false)}
+      status="loading"
+      statusMessage="Transcribing video..."
+    />
+  );
+}
+```
+
+The button label automatically toggles between `"Generate"` and `"Regenerate"` based on the `hasResult` prop, or can be fully overridden via `buttonLabel`.

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

@@ -0,0 +1,53 @@
+<!-- source-hash: 82679c7416bd1640d332a170504ba800 -->
+A reusable React component that renders editable textarea fields for video summary, transcript, and optional SRT subtitles — with AI generation badges and confidence score indicators.
+
+## Key Components
+
+### `TranscriptSummaryEditor`
+The default export. Renders up to three labeled textarea sections:
+
+| Section | Shown When |
+|---|---|
+| **Video Summary** | Always |
+| **Transcript** | Always |
+| **Subtitles (SRT)** | `subtitles` content exists OR `onSubtitlesChange` is provided |
+
+Each section supports:
+- Customizable label, helper text, and placeholder
+- Configurable minimum height
+- `isAIGenerated` badge (Sparkles icon / CC icon for subtitles)
+- `ConfidenceBadge` for AI confidence scores (video summary and transcript only)
+- `disabled` state propagated to all textareas
+
+### `TranscriptSummaryEditorProps`
+Full TypeScript interface with all configurable props — all optional except `onVideoSummaryChange` and `onTranscriptChange`.
+
+## Usage Example
+
+```typescript
+import { TranscriptSummaryEditor } from './transcript-summary-editor';
+
+function InterviewEditor() {
+  const [summary, setSummary] = useState('');
+  const [transcript, setTranscript] = useState('');
+  const [subtitles, setSubtitles] = useState('');
+
+  return (
+    <TranscriptSummaryEditor
+      videoSummary={summary}
+      onVideoSummaryChange={setSummary}
+      transcript={transcript}
+      onTranscriptChange={setTranscript}
+      isAIGenerated={true}
+      videoSummaryConfidence={87}
+      transcriptConfidence={92}
+      subtitles={subtitles}
+      onSubtitlesChange={setSubtitles}
+      videoSummaryMinHeight={250}
+      transcriptMinHeight={400}
+    />
+  );
+}
+```
+
+> Designed for use with `CustomerInterview` and `ProductRelease` entities in the Flamingo/OpenFrame platform, providing a consistent editing UI across entity types.

package/src/components/features/.video-bites-display.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 5b4e3ad25ef1abb4f28d722afea48eb0 -->
+Renders a responsive, lazily-loaded grid of short video bites grouped by aspect ratio (portrait, square, landscape), using viewport-gating to defer off-screen player mounts and prevent cumulative layout shift (CLS).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `VideoBitesDisplay` | Component | Primary public component; filters, sorts, and groups bites by aspect ratio |
+| `VideoBiteCard` | Component | Individual bite card wrapping `<Video>` inside a styled `<Card>` |
+| `LazyBite` | Component (internal) | Defers child mount until within 500px of the viewport via `useNearViewport` |
+| `BiteGrid` | Component (internal) | Renders ratio-appropriate column grid with each bite wrapped in `LazyBite` |
+
+## Key Behaviors
+
+- **Filtering & sorting**: Optionally filters to published bites only, sorted newest-first by `created_at`
+- **Aspect ratio grouping**: When multiple ratios exist, renders `<RatioTabs>`; otherwise falls back to a flat `<BiteGrid>`
+- **CLS prevention**: `LazyBite` uses a CSS `aspect-ratio` placeholder matching the bite's ratio before the player mounts; `layout="fill"` on `<Video>` fills the card from first paint
+- **Player routing**: All bites go through the `<Video>` primitive (no raw `VideoPlayer` carve-out) since MuxPlayer loads its HLS engine lazily
+
+## Usage Example
+
+```typescript
+import { VideoBitesDisplay } from './video-bites-display';
+import type { VideoTeaser } from '../../types/video-processing';
+
+const bites: VideoTeaser[] = [
+  {
+    url: 'https://stream.example.com/clip1.mp4',
+    title: 'Product Demo',
+    thumbnail_url: 'https://cdn.example.com/thumb1.jpg',
+    published: true,
+    created_at: '2024-06-01T12:00:00Z',
+  },
+];
+
+export function HighlightsSection() {
+  return (
+    <VideoBitesDisplay
+      bites={bites}
+      title="Product Highlights"
+      filterPublished={true}
+      showTitle={true}
+    />
+  );
+}
+```

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

@@ -0,0 +1,41 @@
+<!-- source-hash: 81400380536975a05d6ee9dc0f9ea30f -->
+Reusable wrapper component around `AIEnrichSection` that provides a standardized UI for triggering and managing video clips extraction from uploaded media.
+
+## Key Components
+
+### `VideoClipsSection`
+A pre-configured `AIEnrichSection` wrapper that handles the video clips extraction step for `CustomerInterview` and `ProductRelease` entities. Automatically toggles the button label between `"Generate Clips"` and `"Regenerate Clips"` based on whether a result already exists.
+
+### `VideoClipsSectionProps`
+Full interface for controlling extraction state, UI labels, cancel behavior, and required field validation display.
+
+## Usage Example
+
+```typescript
+import { VideoClipsSection } from './video-clips-section';
+
+<VideoClipsSection
+  onExtractClips={handleExtract}
+  isProcessing={isLoading}
+  canEnrich={!!uploadedVideo}
+  requiredFields={[{ label: 'Video', isMet: !!uploadedVideo }]}
+  status={extractionStatus}
+  statusMessage="Clips extracted successfully"
+  hasResult={clips.length > 0}
+  showCancel={true}
+  onCancel={handleCancel}
+  isCancelling={isCancelling}
+/>
+```
+
+## Props Summary
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onExtractClips` | `() => void` | — | Triggers extraction |
+| `isProcessing` | `boolean` | — | Shows loading state |
+| `canEnrich` | `boolean` | — | Enables the button |
+| `hasResult` | `boolean` | `false` | Switches label to "Regenerate" |
+| `disabledMessage` | `string` | `"Upload a video first"` | Tooltip when disabled |
+| `loadingLabel` | `string` | `"Extracting clips..."` | In-progress button label |
+| `showCancel` | `boolean` | `true` | Shows cancel option |

package/src/components/features/.video-ratio-tabs.md

@@ -0,0 +1,56 @@
+<!-- source-hash: d2815a723188c45f4c5d2910a19ffd76 -->
+Aspect-ratio tab and grouping primitives for video grids, used by `VideoBitesDisplay` and admin editors to render portrait, square, and landscape clips in cohesive tabbed groups.
+
+## Key Components
+
+### Types & Interfaces
+- **`VizardAspectRatio`** — Union type for Vizard clip ratios: `'9:16' | '16:9' | '1:1'`
+- **`VideoTeaserWithRatio`** — Extends `VideoTeaser` with `aspect_ratio`, `confidence`, `viral_reason`, and timing metadata
+- **`RatioCategory`** — Grid grouping label: `'portrait' | 'square' | 'landscape'`
+
+### Constants
+- **`RATIO_GRID_CLASS`** — Tailwind grid classes for admin editor views (narrower columns)
+- **`RATIO_DISPLAY_GRID_CLASS`** — Tailwind grid classes for public display pages (wider columns)
+
+### Components
+- **`RatioTabs`** — Tab wrapper that only renders tabs with content; auto-collapses to flat render when only one ratio group is populated; uses `forceMount` to prevent scroll-jump on tab switch
+
+### Utilities
+- **`detectAspectRatio(ratioString?, width?, height?)`** — Resolves a `VizardAspectRatio` from a string, falling back to dimension inference, defaulting to `'9:16'`
+- **`ratioToCategory(ratio)`** — Maps `VizardAspectRatio` → `RatioCategory`
+- **`groupByAspectRatio(items, getAspectRatio)`** — Buckets any item array into `{ portrait, square, landscape, hasMultiple }`
+
+## Usage Example
+
+```typescript
+import {
+  RatioTabs,
+  groupByAspectRatio,
+  detectAspectRatio,
+  ratioToCategory,
+  RATIO_DISPLAY_GRID_CLASS,
+} from './video-ratio-tabs';
+
+// Group clips by detected aspect ratio
+const { portrait, square, landscape, hasMultiple } = groupByAspectRatio(
+  clips,
+  (clip) => detectAspectRatio(clip.aspect_ratio, clip.width, clip.height),
+);
+
+// Render with tabbed UI
+<RatioTabs
+  groups={{
+    portrait: {
+      count: portrait.length,
+      render: () => (
+        <div className={RATIO_DISPLAY_GRID_CLASS.portrait}>
+          {portrait.map((c) => <ClipCard key={c.id} clip={c} />)}
+        </div>
+      ),
+    },
+    square: { count: square.length, render: () => <SquareGrid items={square} /> },
+    landscape: { count: landscape.length, render: () => <LandscapeGrid items={landscape} /> },
+  }}
+  defaultTab="portrait"
+/>
+```

package/src/components/features/.video-source-selector.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 1995e98822c487bba791ce8689ae2447 -->
+Unified toggle component for selecting between a YouTube URL input and a direct video file upload, managing upload state, progress, and preview rendering internally.
+
+## Key Components
+
+### Exports
+- **`VideoSourceSelector`** — Main React component (default + named export)
+- **`VideoSourceType`** — Union type: `'youtube' | 'uploaded'`
+- **`VideoSourceSelectorProps`** — Full prop interface for the component
+
+### Internal State
+| State | Purpose |
+|---|---|
+| `isUploading` | Tracks active upload operation |
+| `uploadProgress` | Numeric progress (0–100) |
+| `uploadMessage` | Status message during upload |
+| `uploadError` | Error string if upload fails |
+
+### Key Handlers
+- **`handleUploadClick`** — Programmatically triggers a hidden `<input type="file">`, invokes `onUploadVideo`, and manages progress callbacks
+- **`handleDeleteVideo`** — Clears the uploaded video URL via `onMainVideoUrlChange('')`
+
+## Usage Example
+
+```typescript
+import { VideoSourceSelector, VideoSourceType } from './video-source-selector';
+
+function MyForm() {
+  const [sourceType, setSourceType] = useState<VideoSourceType>('youtube');
+  const [youtubeUrl, setYoutubeUrl] = useState('');
+  const [videoUrl, setVideoUrl] = useState('');
+
+  const handleUpload = async (file: File, onProgress?: (p: number) => void) => {
+    const formData = new FormData();
+    formData.append('file', file);
+    // ... upload logic with progress callbacks
+    return 'https://cdn.example.com/video.mp4';
+  };
+
+  return (
+    <VideoSourceSelector
+      videoSourceType={sourceType}
+      onVideoSourceTypeChange={setSourceType}
+      youtubeUrl={youtubeUrl}
+      onYoutubeUrlChange={setYoutubeUrl}
+      mainVideoUrl={videoUrl}
+      onMainVideoUrlChange={setVideoUrl}
+      onUploadVideo={handleUpload}
+      isAIGenerated={false}
+      title="Course Video"
+    />
+  );
+}
+```
+
+## Notes
+
+- Switching between `youtube` and `uploaded` tabs **preserves both values** — no data is cleared on toggle
+- Accepts optional `VideoPreviewComponent` and `UploadProgressComponent` for custom rendering; falls back to built-in implementations if omitted
+- All text labels and placeholders are customizable via props for reuse across different contexts

package/src/components/features/.video.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 9e88b910bdaffc13eb668740a6d415f4 -->
+Renders video content from YouTube URLs, bare video IDs, or file sources (HLS/MP4) with smart auto-detection and three layout modes. Consolidates the previous `<VideoPlayer>` and `<YouTubeEmbed>` primitives into a single component.
+
+## Key Components
+
+- **`Video`** — Primary export. Discriminates on `kind` prop (`'youtube'` | `'file'` | `'auto'`) to route to the correct player branch, then wraps in the chosen layout
+- **`extractYouTubeId`** — Exported utility that parses any YouTube URL shape or bare 11-char video ID into a raw video ID. Uses strict URL parsing + anchored regex (ReDoS-safe)
+- **`VideoProps`** — Discriminated union type (`VideoFileProps | VideoYouTubeProps | VideoAutoProps`)
+- **`VideoLayout`** — `'centered'` | `'fill'` | `'native'`
+- **`resolveKind`** (internal) — URL classifier that maps a URL to `'youtube'` or `'file'`
+- **`YouTubeFacade`** (internal) — Lite-YouTube poster + click-to-iframe embed
+- **`FilePlayer`** (internal) — `<MuxPlayer>` wrapper handling HLS, MP4, captions, and Mux Data
+
+## Usage Example
+
+```typescript
+// Auto-detect source from URL (recommended)
+<Video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" layout="centered" />
+
+// Bare YouTube ID
+<Video url="dQw4w9WgXcQ" layout="native" priority />
+
+// HLS or MP4 file with captions
+<Video
+  kind="file"
+  url="https://cdn.example.com/video.m3u8"
+  captionsUrl="https://cdn.example.com/captions.vtt"
+  layout="fill"
+  muted
+/>
+
+// Marketing embed — minimal YouTube controls
+<Video
+  kind="youtube"
+  url="https://youtu.be/dQw4w9WgXcQ"
+  layout="centered"
+  minimalControls
+  title="Product demo"
+/>
+
+// Validate a URL without rendering
+import { extractYouTubeId } from './video';
+const id = extractYouTubeId('https://youtu.be/dQw4w9WgXcQ'); // → "dQw4w9WgXcQ"
+```

package/src/components/features/.waitlist-form.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 6dd94b5db8fe43eb78a9a8032c387c0e -->
+A platform-agnostic waitlist registration form component for OpenFrame/Flamingo, handling email capture, optional phone input with country detection, SMS consent, and submission state management.
+
+## Key Components
+
+### `WaitlistFormProps`
+Configuration interface with the following notable props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onRegister` | `(email, phone?) => Promise<void>` | Required submission handler; must throw on failure |
+| `geoApiUrl` | `string \| null` | Geo-detection endpoint for auto-selecting country code (default: `"/api/geo"`) |
+| `isSubmitting` | `boolean` | Controls loading state on the submit button |
+| `isSuccess` | `boolean` | Switches button label to `successLabel` |
+| `defaultEmail` / `defaultPhone` | `string` | Pre-filled values from auth context or user profile |
+| `termsOfServiceUrl` / `privacyPolicyUrl` | `string` | Links rendered in SMS consent copy |
+
+### `WaitlistForm`
+The exported form component. Key internal behaviors:
+
+- **Hydration-safe skeleton** — renders animated placeholder blocks until client-side mount
+- **Geo-detection** — fetches `geoApiUrl` on mount to pre-select the user's country code via `libphonenumber-js`
+- **Generic email warning** — surfaces a warning (not a block) when a personal domain is detected
+- **SMS consent gate** — requires checkbox agreement before submitting a phone number
+- **E.164 formatting** — converts raw phone input via `formatPhoneE164` before calling `onRegister`
+- **Enter key support** — `handleKeyDown` triggers submission from any field
+
+## Usage Example
+
+```typescript
+import { WaitlistForm } from './waitlist-form'
+
+function WaitlistPage() {
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [isSuccess, setIsSuccess] = useState(false)
+
+  const handleRegister = async (email: string, phone?: string) => {
+    setIsSubmitting(true)
+    try {
+      await api.joinWaitlist({ email, phone })
+      setIsSuccess(true)
+    } finally {
+      setIsSubmitting(false)
+    }
+  }
+
+  return (
+    <WaitlistForm
+      onRegister={handleRegister}
+      isSubmitting={isSubmitting}
+      isSuccess={isSuccess}
+      geoApiUrl="/api/geo"
+      termsOfServiceUrl="/legal/terms"
+      privacyPolicyUrl="/legal/privacy"
+    />
+  )
+}
+```
+
+> **Note:** `onRegister` is responsible for its own error toasts. The form handles only email-empty and consent-missing validation client-side.