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

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

@@ -1,46 +1,45 @@
-<!-- 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).
+<!-- source-hash: 6a2710f318159a01ed58b31f201488ba -->
+Transitional shim component that forwards its props to `<VideoBitesStrip>`, preserving the legacy four-prop signature for hub call sites during migration.
+
+> ⚠️ **Deprecated** — this component is scheduled for deletion after the hub-side migration completes. Use [`<VideoBitesStrip>`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/video-bites/video-bites-strip.tsx) directly in all new code.
 
 ## 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` |
+### `VideoBitesDisplayProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `bites` | `VideoTeaser[]` | — | Array of video bites/teasers to render |
+| `title` | `string` | `DEFAULT_VIDEO_BITES_TITLE` | Section heading text |
+| `filterPublished` | `boolean` | `true` | When true, only published bites are shown |
+| `showTitle` | `boolean` | `true` | Toggles visibility of the section heading |
 
-## Key Behaviors
+### `VideoBitesDisplay`
 
-- **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
+Client component that passes all four props directly to `<VideoBitesStrip>` with no additional logic.
 
 ## 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}
-    />
-  );
-}
-```
+// ⚠️ Deprecated — prefer VideoBitesStrip directly
+import { VideoBitesDisplay } from '@openframe/lib/components/video-bites';
+
+<VideoBitesDisplay
+  bites={videoTeasers}
+  title="Latest Clips"
+  filterPublished={true}
+  showTitle={true}
+/>
+
+// ✅ Preferred replacement
+import { VideoBitesStrip } from '@openframe/lib/components/video-bites';
+
+<VideoBitesStrip
+  bites={videoTeasers}
+  title="Latest Clips"
+  filterPublished={true}
+  showTitle={true}
+/>
+```
+
+Do not add features or new consumers to this component. Track migration progress via the grep gate described in the JSDoc before removal.

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

@@ -0,0 +1,44 @@
+<!-- source-hash: e280ed2bbd7fa3083e59e5490366cc24 -->
+Server-safe shared utilities for the video-bites surface, providing a title constant, profile adapter, and sort comparator that can be imported in server-side contexts without pulling in client-only dependencies.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `DEFAULT_VIDEO_BITES_TITLE` | `const` | Canonical section title string (`'Key Moments'`) |
+| `VideoBiteStripProfile` | `interface` | Profile shape rendered in the strip's hover overlay |
+| `toStripProfile()` | function | Adapter that maps repo-wide author/user rows to `VideoBiteStripProfile` |
+| `sortBitesByCreatedAtDesc()` | function | Null-safe `created_at`-descending comparator for `VideoTeaser` arrays |
+
+## Usage Example
+
+```typescript
+import {
+  DEFAULT_VIDEO_BITES_TITLE,
+  toStripProfile,
+  sortBitesByCreatedAtDesc,
+} from '@flamingo-stack/openframe-frontend-core/components/features/video-bites-shared'
+
+// Section title
+console.log(DEFAULT_VIDEO_BITES_TITLE) // 'Key Moments'
+
+// Map an author row → strip profile (returns null when full_name is absent)
+const profile = toStripProfile(
+  { full_name: 'Ada Lovelace', avatar_url: '/avatars/ada.jpg', job_title: 'Engineer' },
+  'Contributor', // fallback subtitle
+)
+// → { name: 'Ada Lovelace', avatarUrl: '/avatars/ada.jpg', subtitle: 'Engineer' }
+
+const profile2 = toStripProfile(null) // → null
+
+// Sort bites newest-first; missing created_at sorts last
+const sorted = [...videoBites].sort(sortBitesByCreatedAtDesc)
+```
+
+## Notes
+
+- **Server-safe by design** — no React imports, no `'use client'` directive. Mirrors the same isolation pattern as `mux-origins.ts`.
+- `toStripProfile` returns `null` (never `{ name: '' }`) when `full_name` is absent, enabling safe `profile ?? fallback` chains at call sites.
+- Client components (`<VideoBitesStrip>`, the features barrel) re-export from this file — definitions must never be duplicated.
+
+**Source:** [`video-bites-shared.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-bites-shared.ts)

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

@@ -0,0 +1,63 @@
+<!-- source-hash: f6cb5509048904127db3df5bae07f87b -->
+Brief description: `video-bites-strip.tsx` is the unified public video-bites surface component that renders a horizontally scrolling marquee strip of video preview cards with hover-activated muted autoplay, built on the shared `CardsStrip` engine.
+
+## Key Components
+
+### `VideoBitesStrip`
+The main section-level component. Filters and sorts bites by publish status and creation date, warms up Mux/Supabase origins, and delegates rendering to `CardsStrip` via render-prop.
+
+### `VideoBiteCard`
+The individual card component, exported for reuse in the admin bites editor. Manages:
+- Hover activation (controlled by strip or self-managed standalone)
+- Player mount gating via a two-way `IntersectionObserver` (~500px root margin) to bound live `MuxPlayer` instances to the visible strip width
+- Rendition-capped preview URLs via `toMuxPreviewUrl` (720p cap for HLS)
+- Overlay navigation (anchor or button depending on `href` vs `onNavigate`)
+
+### Key Types
+- **`VideoBiteStripItem`** — extends `VideoTeaserWithRatio` with per-bite `profile`, `href`, and `onNavigate`
+- **`VideoBitesStripProps`** — section-level config: bites array, title, scroll behavior, card dimensions, chevrons
+- **`VideoBiteCardProps`** — card-level config: controlled vs. self-managed hover/mount, toolbar slot, inline title editing
+
+## Usage Example
+
+```typescript
+import { VideoBitesStrip } from './video-bites-strip';
+
+// Section-level strip (typical public page usage)
+<VideoBitesStrip
+  bites={bites}
+  title="Key Moments"
+  profile={{ name: 'Acme Corp', avatarUrl: '/logo.png' }}
+  href="/entity/acme"
+  autoScroll
+  autoScrollSpeed={60}
+  cardHeightDesktop={416}
+  cardHeightMobile={300}
+/>
+
+// Standalone card (admin editor — self-managed hover/mount)
+import { VideoBiteCard } from './video-bites-strip';
+
+<VideoBiteCard
+  bite={bite}
+  index={0}
+  profile={profile}
+  toolbar={<AdminToolbar />}
+  titleEditable
+  onTitleCommit={handleTitleSave}
+/>
+```
+
+## Architecture Notes
+
+```mermaid
+graph TD
+    A[VideoBitesStrip] --> B[CardsStrip engine]
+    B --> C[VideoBiteCard]
+    C --> D[Video / MuxPlayer]
+    C --> E[IntersectionObserver gate]
+    A --> F[useVideoWarmup]
+    A --> G[sortBitesByCreatedAtDesc]
+```
+
+**Source:** [`video-bites-strip.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-bites-strip.tsx)

package/src/components/features/.video-center-badge.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 4badfa3be12a3b317bb3a4fb9a73fba2 -->
+Defines the canonical center-overlay glyph components used for play and unmute affordances across all video surfaces in the project — solid white icons with a legibility drop-shadow and no background disc.
+
+## Key Components
+
+### Types & Constants
+
+- **`VideoCenterBadgeSize`** — Union type `'sm' | 'md' | 'lg'` controlling icon pixel size (20 / 56 / 64px respectively)
+- **`SIZES`** — Size map: `sm` for gallery thumbnails, `md` for strip cards/unmute chip, `lg` for hero facades
+- **`GLYPH_SHADOW`** — Shared CSS `drop-shadow` filter applied to all glyphs for legibility over arbitrary video frames
+
+### Exports
+
+- **`VideoPlayBadge`** — Decorative (`pointer-events-none`) play glyph rendered via `PlayFilledIcon`. Host surfaces own click activation; accent color applied externally via `group-hover:text-ods-accent`
+- **`VideoUnmuteGlyph`** — Muted-volume glyph rendered via `VolumeOffFilledIcon`. Used by `<FilePlayer>`'s unmute button; shares the same visual identity as `VideoPlayBadge`
+
+## Usage Example
+
+```typescript
+// Play badge on a video poster (e.g. VideoBiteCard)
+<div className="group relative">
+  <img src={posterUrl} alt={title} />
+  <VideoPlayBadge
+    size="md"
+    className="absolute inset-0 m-auto group-hover:text-ods-accent"
+  />
+</div>
+
+// Unmute chip in FilePlayer
+<button onClick={handleUnmute}>
+  <VideoUnmuteGlyph size="md" className="text-ods-text-primary" />
+</button>
+
+// Small glyph for MediaCarousel thumbnails
+<VideoPlayBadge size="sm" className="group-hover:text-ods-accent" />
+```
+
+**Consumers:** `<VideoBiteCard>`, `<YouTubeFacade>`, `<MediaCarousel>`, `<FilePlayer>`. MuxPlayer's native center button is aligned to this glyph language via `styles/app-globals.css`.

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

@@ -1,56 +1,63 @@
-<!-- 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.
+<!-- source-hash: 98c77db08c2b5bd65885d9fe120e315e -->
+Aspect-ratio tab and grouping primitives for video surfaces, shared between admin editors and the public `VideoBitesStrip` component.
 
 ## 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'`
+### Types
+
+- **`VizardAspectRatio`** — Union type for Vizard clip extraction ratios: `'9:16' | '16:9' | '1:1'`
+- **`RatioCategory`** — Grid/tab grouping category: `'portrait' | 'square' | 'landscape'`
+- **`VideoTeaserWithRatio`** — Extends `VideoTeaser` with an optional `aspect_ratio` field; canonical type for display/aggregation code
 
 ### 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)
+
+- **`RATIO_GRID_CLASS`** — Tailwind grid classes per `RatioCategory` (admin editors)
+- **`RATIO_TO_CSS_ASPECT`** — CSS `aspect-ratio` values per category, consumed by strip cards and placeholders
 
 ### 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
+
+- **`RatioTabs`** — Tab wrapper rendering only populated ratio groups; uses `forceMount` + CSS hiding to prevent scroll-jump on tab switch. Collapses to a flat render when only one ratio has content.
 
 ### 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 }`
+
+- **`detectAspectRatio(ratioString?, width?, height?)`** — Resolves a `VizardAspectRatio` from a Vizard ratio string, falling back to dimension inference. Defaults to `'9:16'`.
+- **`ratioToCategory(ratio)`** — Maps a `VizardAspectRatio` to its `RatioCategory`
+- **`groupByAspectRatio(items, getAspectRatio)`** — Buckets an array into portrait/square/landscape groups; includes `hasMultiple` flag for downstream tab-vs-grid decisions
 
 ## Usage Example
 
 ```typescript
 import {
-  RatioTabs,
-  groupByAspectRatio,
   detectAspectRatio,
-  ratioToCategory,
-  RATIO_DISPLAY_GRID_CLASS,
+  groupByAspectRatio,
+  RatioTabs,
+  RATIO_TO_CSS_ASPECT,
 } from './video-ratio-tabs';
 
-// Group clips by detected aspect ratio
+// Detect ratio from Vizard metadata, with dimension fallback
+const ratio = detectAspectRatio(bite.aspect_ratio, bite.width, bite.height);
+// → '9:16'
+
+// Group bites into buckets
 const { portrait, square, landscape, hasMultiple } = groupByAspectRatio(
-  clips,
-  (clip) => detectAspectRatio(clip.aspect_ratio, clip.width, clip.height),
+  bites,
+  (b) => detectAspectRatio(b.aspect_ratio),
 );
 
-// Render with tabbed UI
+// Render tabbed grid (admin editors only)
 <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} /> },
+    portrait: { count: portrait.length, render: () => <PortraitGrid items={portrait} /> },
+    square:   { count: square.length,   render: () => <SquareGrid   items={square}   /> },
+    landscape:{ count: landscape.length, render: () => <LandscapeGrid items={landscape} /> },
   }}
   defaultTab="portrait"
 />
-```
+
+// Apply CSS aspect-ratio in strip cards
+const aspectStyle = { aspectRatio: RATIO_TO_CSS_ASPECT['portrait'] }; // '9 / 16'
+```
+
+> **Scope note:** `RatioTabs` and `RATIO_GRID_CLASS` are admin-only (`VideoBitesEditor`, `VideoLibraryGrid`). The public `VideoBitesStrip` consumes only `detectAspectRatio` and `RATIO_TO_CSS_ASPECT`.
+
+**Source:** [`lib/components/video-ratio-tabs.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/lib/components/video-ratio-tabs.tsx)

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

@@ -1,40 +1,41 @@
-<!-- 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.
+<!-- source-hash: dbedaa2fa25b04c2c550b2eefc8f1a0d -->
+Reusable React component that lets users switch between a YouTube URL input and a direct video upload, preserving both values across source-type toggles.
 
 ## Key Components
 
-### Exports
-- **`VideoSourceSelector`** — Main React component (default + named export)
-- **`VideoSourceType`** — Union type: `'youtube' | 'uploaded'`
-- **`VideoSourceSelectorProps`** — Full prop interface for the component
+### `VideoSourceSelector` (main export)
+Controlled component rendering a YouTube/Upload toggle with:
+- **YouTube mode** – URL text input with configurable placeholder and helper text
+- **Upload mode** – file picker trigger, progress bar (custom or built-in fallback), error display, and video preview
+- Supports optional AI-generated badge, custom preview/progress components, and disabled state
 
-### 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 |
+### `DefaultVideoPreview` (internal)
+Fallback preview rendered when no `VideoPreviewComponent` prop is supplied. Wraps the shared `<Video>` component (Mux HLS / MP4) inside a `16:9` aspect-ratio container with a floating delete button.
 
-### Key Handlers
-- **`handleUploadClick`** — Programmatically triggers a hidden `<input type="file">`, invokes `onUploadVideo`, and manages progress callbacks
-- **`handleDeleteVideo`** — Clears the uploaded video URL via `onMainVideoUrlChange('')`
+### Types
+| Export | Description |
+|---|---|
+| `VideoSourceType` | `'youtube' \| 'uploaded'` |
+| `VideoSourceSelectorProps` | Full prop interface with JSDoc on every field |
 
 ## Usage Example
 
 ```typescript
 import { VideoSourceSelector, VideoSourceType } from './video-source-selector';
+import { useState } from 'react';
 
-function MyForm() {
+function CourseEditor() {
   const [sourceType, setSourceType] = useState<VideoSourceType>('youtube');
   const [youtubeUrl, setYoutubeUrl] = useState('');
-  const [videoUrl, setVideoUrl] = useState('');
+  const [uploadedUrl, setUploadedUrl] = 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';
+    // Call your upload endpoint; report progress via onProgress
+    const res = await fetch('/api/upload-video', { method: 'POST', body: formData });
+    const { url } = await res.json();
+    return url; // returned URL stored in uploadedUrl
   };
 
   return (
@@ -43,8 +44,8 @@ function MyForm() {
       onVideoSourceTypeChange={setSourceType}
       youtubeUrl={youtubeUrl}
       onYoutubeUrlChange={setYoutubeUrl}
-      mainVideoUrl={videoUrl}
-      onMainVideoUrlChange={setVideoUrl}
+      mainVideoUrl={uploadedUrl}
+      onMainVideoUrlChange={setUploadedUrl}
       onUploadVideo={handleUpload}
       isAIGenerated={false}
       title="Course Video"
@@ -53,8 +54,4 @@ function MyForm() {
 }
 ```
 
-## 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
+**Source:** [`video-source-selector.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-source-selector.tsx)

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

@@ -1,44 +1,52 @@
-<!-- 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.
+<!-- source-hash: 9c0955b67c6b1b22bab746a927f92650 -->
+Renders video content from YouTube URLs, file URLs (HLS/MP4), or bare YouTube IDs with automatic source detection, three layout modes, and optional hover-play/muted-autoplay behavior.
 
 ## 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
+### Exports
+
+- **`extractYouTubeId(url: string): string | null`** — Parses any YouTube URL shape or bare 11-char ID into a video ID. Uses strict `URL` parsing with anchored regexes to prevent ReDoS attacks.
+- **`VideoLayout`** — Union type: `'centered' | 'fill' | 'native'`
+- **`<Video>`** (default export) — Single unified video component routing to lite-YouTube facade or `<MuxPlayer>` based on `kind` prop.
+
+### Internal Utilities
+
+- **`videoPerfDebugEnabled()`** — Gates hover-to-play latency instrumentation; always on in dev, opt-in via `localStorage.VIDEO_PERF_DEBUG` in production.
+- **`isYouTubeUrl(url)`** — Hostname-based YouTube detection against a strict allowlist.
+- **`extractYouTubeId(url)`** — Exported ID extractor usable by admin tooling without rendering the component.
+
+### Key Behaviors
+
+| Feature | Detail |
+|---|---|
+| `kind="auto"` | Bare 11-char ID → YouTube; YouTube hostname → YouTube; anything else → file |
+| `layout="centered"` | `max-w-3xl` centered wrapper — detail pages |
+| `layout="fill"` | `absolute inset-0` — carousel slides |
+| `layout="native"` | Intrinsic aspect ratio — grid/card embeds |
+| Cast suppression | Stubs `chrome.cast` to block MuxPlayer's CSP-violating Cast SDK injection |
+| Autoplay policy | Module-level `pointerdown`/`keydown` tracker gates muted vs. sound-first hover play |
 
 ## Usage Example
 
 ```typescript
-// Auto-detect source from URL (recommended)
-<Video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" layout="centered" />
+import { Video, extractYouTubeId } from '@/components/video';
 
-// Bare YouTube ID
-<Video url="dQw4w9WgXcQ" layout="native" priority />
+// Auto-detect source from URL
+<Video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" layout="centered" />
 
-// HLS or MP4 file with captions
+// Explicit file source with captions
 <Video
   kind="file"
-  url="https://cdn.example.com/video.m3u8"
+  url="https://cdn.example.com/clip.m3u8"
   captionsUrl="https://cdn.example.com/captions.vtt"
   layout="fill"
+  autoPlay
   muted
+  loop
 />
 
-// Marketing embed — minimal YouTube controls
-<Video
-  kind="youtube"
-  url="https://youtu.be/dQw4w9WgXcQ"
-  layout="centered"
-  minimalControls
-  title="Product demo"
-/>
+// Extract ID for thumbnail logic without rendering
+const id = extractYouTubeId('https://youtu.be/dQw4w9WgXcQ'); // "dQw4w9WgXcQ"
+```
 
-// Validate a URL without rendering
-import { extractYouTubeId } from './video';
-const id = extractYouTubeId('https://youtu.be/dQw4w9WgXcQ'); // → "dQw4w9WgXcQ"
-```
+**Source:** [`video.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video.tsx)

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

@@ -1,60 +1,66 @@
-<!-- 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.
+<!-- source-hash: 8fbc6cc433de62257e74785b11ef3d03 -->
+Platform-agnostic waitlist registration form component with email/phone capture, bot protection, geo-detection, and SMS consent handling.
 
 ## 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 |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onRegister` | `(email, phone?, signals?) => Promise<void>` | — | **Required.** Registration handler; must throw on failure |
+| `isSubmitting` | `boolean` | `false` | Controls loading state |
+| `isSuccess` | `boolean` | `false` | Toggles success label on submit button |
+| `defaultEmail` | `string` | `''` | Pre-filled email |
+| `defaultPhone` | `string` | `''` | Pre-filled phone |
+| `geoApiUrl` | `string \| null` | `'/api/geo'` | Geo-detection endpoint; set to `null` to disable |
+| `submitLabel` | `string` | `'Get Beta Access'` | Submit button label |
+| `successLabel` | `string` | `"You're in!"` | Post-success button label |
+| `termsOfServiceUrl` | `string` | — | ToS link in consent text |
+| `privacyPolicyUrl` | `string` | — | Privacy Policy link in consent text |
 
 ### `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
+The exported form component. Internally manages:
+
+- **Email validation** — warns on generic domains via `hasGenericEmailDomain`
+- **Phone handling** — E.164 formatting via `formatPhoneE164`; country auto-detected from geo API
+- **Bot protection** — invisible `HoneypotField` + timing signals via `useHumanitySignals`
+- **SMS consent gate** — blocks submission if phone is provided without consent
+- **Hydration safety** — renders an animated skeleton until client-side hydration completes
 
 ## Usage Example
 
 ```typescript
 import { WaitlistForm } from './waitlist-form'
 
-function WaitlistPage() {
+async function register(email: string, phone?: string, signals?: HumanitySignals) {
+  const res = await fetch('/api/waitlist', {
+    method: 'POST',
+    body: JSON.stringify({ email, phone, ...signals }),
+  })
+  if (!res.ok) throw new Error('Registration failed')
+}
+
+export default function Page() {
   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}
+      onRegister={async (email, phone, signals) => {
+        setIsSubmitting(true)
+        await register(email, phone, signals)
+        setIsSuccess(true)
+        setIsSubmitting(false)
+      }}
       isSubmitting={isSubmitting}
       isSuccess={isSuccess}
       geoApiUrl="/api/geo"
-      termsOfServiceUrl="/legal/terms"
-      privacyPolicyUrl="/legal/privacy"
+      termsOfServiceUrl="https://flamingo.run/terms"
+      privacyPolicyUrl="https://flamingo.run/privacy"
     />
   )
 }
 ```
 
-> **Note:** `onRegister` is responsible for its own error toasts. The form handles only email-empty and consent-missing validation client-side.
+**Source:** [`waitlist-form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/waitlist-form.tsx)