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

package/src/components/.footer-waitlist-button.md

@@ -1,38 +1,45 @@
-<!-- source-hash: f79f8bb1d9edf6587a6e5969375e5636 -->
-A Next.js client component that provides a context-aware waitlist button for use in footers, with smart navigation and form focusing capabilities.
+<!-- source-hash: 8e25a68fa3e51dd5cde8b484877f10f2 -->
+A footer button component that navigates users to the OpenFrame waitlist page, routing through the unified navigation system when available.
 
 ## Key Components
 
-**`FooterWaitlistButton`**: Main component that renders a button with OpenFrame logo and intelligent click behavior
-- **Props**: `FooterWaitlistButtonProps` interface with optional `className`
-- **Dependencies**: Next.js navigation hooks (`usePathname`, `useRouter`), custom UI components (`Button`, `OpenFrameLogo`)
+### `FooterWaitlistButtonProps`
+- `className?: string` — Optional CSS class for styling overrides.
+
+### `FooterWaitlistButton`
+A `Button` wrapper that handles navigation to `/waitlist#top` via a two-tier fallback strategy:
+
+1. **Primary:** `runtime.navigation.navigate` — the host's unified-nav hook (provided by `HubRuntimeProvider`), which handles cross-platform new-tab decisions, same-URL re-scroll, and embed-mode short-circuiting.
+2. **Fallback:** `router.push` via the embed-shim's `useRouter` — used when no `ChatRuntimeContext` is mounted (e.g., third-party embedders).
+
+Renders with the `OpenFrameLogo` icon as a left icon inside the button.
 
 ## Usage Example
 
 ```typescript
 import { FooterWaitlistButton } from './footer-waitlist-button';
 
-// Basic usage in footer
-function Footer() {
+// Basic usage inside a footer layout
+export function AppFooter() {
   return (
-    <footer className="bg-gray-900">
-      <div className="container mx-auto px-4 py-8">
-        <FooterWaitlistButton className="mt-4" />
-      </div>
+    <footer>
+      <FooterWaitlistButton className="mt-4 w-full" />
     </footer>
   );
 }
-
-// With custom styling
-function CustomFooter() {
-  return (
-    <FooterWaitlistButton className="bg-primary hover:bg-primary/90 text-white" />
-  );
-}
 ```
 
-The component implements smart navigation logic:
-- **On `/waitlist` page**: Smoothly scrolls to `#waitlist-form` element and focuses the email input after 400ms delay
-- **On other pages**: Navigates to `/waitlist#waitlist-form` URL with anchor
+> **Navigation note:** The `#top` anchor targets an explicit `<div id="top">` at the top of the waitlist page's `<main>` element, ensuring consistent scroll behavior across all browsers regardless of HTML5 magic-anchor handling.
+
+## Navigation Flow
 
-The button displays "Join Waitlist" text with the OpenFrame logo as a left icon, providing consistent branding across the application.
+```mermaid
+graph TD
+    A["FooterWaitlistButton clicked"] --> B{"runtime.navigation.navigate available?"}
+    B -->|Yes| C["Call runtime.navigation.navigate"]
+    C --> D{"Handled?"}
+    D -->|Yes| E["Done - unified nav handled"]
+    D -->|No| F["Fallback: router.push"]
+    B -->|No| F
+    F --> G["Navigate to /waitlist#top"]
+```

package/src/components/.footer.md

@@ -1,53 +1,53 @@
-<!-- source-hash: 4a3128feff9dea66bb7c1e8038ce07e8 -->
-A configurable React footer component that provides flexible layout options and platform-specific customization through a comprehensive configuration interface. This component supports responsive design with customizable sections, social links, and content positioning.
+<!-- source-hash: 71df967a1bb27327de1d15d5c696e36b -->
+A configurable, platform-aware footer component for Next.js (client-side) that renders navigation sections, social icons, branding, and custom content slots based on a `FooterConfig` object.
 
 ## Key Components
 
-- **Footer** - Main platform-aware component that accepts configuration
-- **UniversalFooter** - Internal component that renders the actual footer layout
-- **FooterConfig** - TypeScript interface defining configuration options
-- **FooterLink/FooterSection** - Type definitions for navigation structure
-- **NavLinkSkeleton** - Loading skeleton for navigation links
+**`Footer`** — Public entry point. Validates config presence and delegates to `UniversalFooter`. Returns `null` with a console warning if no config is provided.
 
-## Configuration Options
+**`UniversalFooter`** — Core rendering logic. Builds a responsive 4-column grid layout with:
+- **Column 1:** Logo, platform name, description, social icons (`SocialIconRow`)
+- **Dynamic sections:** Rendered from `config.sections[]`
+- **Custom component slot:** `config.customComponent`
+- **Right column slot:** `config.rightColumnContent` or relocated description via `config.moveDescriptionToRight`
 
-The `FooterConfig` interface provides extensive customization:
+**`FooterConfig`** — Interface driving all layout behavior. Key flags:
 
-- **Content**: `name`, `legalName`, `description`, `logo`, `nameElement`
-- **Navigation**: `sections` array with links organized by category  
-- **Layout**: `customComponent`, `rightColumnContent`, `moveDescriptionToRight`
-- **Social**: `social` object with platform URLs (GitHub, Twitter, LinkedIn, etc.)
-- **Styling**: `backgroundColor` with ODS design system classes
-- **Behavior**: `hideSocialRow`, `keepBelowDescriptionLeft`
+| Flag | Effect |
+|------|--------|
+| `moveDescriptionToRight` | Moves description to the right column |
+| `keepBelowDescriptionLeft` | Keeps `belowDescriptionContent` in column 1 when description is moved |
+| `hideSocialRow` | Suppresses the `SocialIconRow` |
+| `backgroundColor` | ODS utility class override (default: `bg-ods-bg-card`) |
+
+**`renderLink`** — Optional prop to override the default anchor renderer per link.
 
 ## Usage Example
 
 ```typescript
-import { Footer } from './footer'
+import { Footer } from "@/components/footer"
 
-const footerConfig = {
-  name: "OpenFrame",
+const config: FooterConfig = {
+  name: "Flamingo",
   legalName: "Flamingo Technologies Inc.",
-  description: "AI-powered MSP platform replacing expensive proprietary software.",
-  backgroundColor: "bg-ods-bg-card",
+  description: "AI-powered MSP platform.",
   sections: [
     {
       title: "Product",
       links: [
-        { href: "/features", label: "Features" },
-        { href: "/pricing", label: "Pricing" }
-      ]
-    }
+        { href: "/openframe", label: "OpenFrame" },
+        { href: "/pricing", label: "Pricing" },
+      ],
+    },
   ],
   social: {
-    github: "https://github.com/flamingo-run",
-    twitter: "https://twitter.com/flamingorun"
-  }
+    github: "https://github.com/flamingo",
+    twitter: "https://twitter.com/flamingo",
+  },
+  backgroundColor: "bg-ods-system-greys-black",
 }
 
-export function AppFooter() {
-  return <Footer config={footerConfig} />
+export default function Layout() {
+  return <Footer config={config} />
 }
-```
-
-The component automatically handles responsive breakpoints, Suspense loading states, and integrates with the ODS design system for consistent theming across the platform.
+```

package/src/components/.icons-block.md

@@ -1,32 +1,42 @@
-<!-- source-hash: a61eab21a69ef6c9de591ad1e2b96e8b -->
-A responsive client-side component that displays a grid of icons with dynamic column sizing based on viewport width and smart adjacent icon filtering to prevent visual clustering.
+<!-- source-hash: 0fcf2c17c123f63f9ecc989146d3d3d7 -->
+Renders a responsive 2-row decorative icon grid that fills the viewport width, randomly distributing icons while avoiding adjacent duplicates. Used as a visual background/separator element.
 
 ## Key Components
 
-- **ResponsiveIconsBlock**: Main component that renders a responsive 2-row grid of icons
-- **availableIcons**: Static array containing custom icons from stub file and Lucide React icons
-- **IconsBlockProps**: Interface defining optional `loading` prop for placeholder state control
-- **Dynamic grid generation**: Algorithm that prevents adjacent duplicate icons using position-based filtering
+- **`ResponsiveIconsBlock`** — Main exported component that calculates column count from viewport width and renders a grid of icons
+- **`IconsBlockProps`** — Interface with optional `loading` boolean to force the placeholder skeleton state
+- **`availableIcons`** — Static array of 12 icon components (custom SVGs + Lucide icons) defined outside the component to prevent re-instantiation
+- **Seeded pseudo-random layout** — Uses `Date.now()` as a stable seed per mount to deterministically assign icons without adjacent repeats
 
 ## Usage Example
 
 ```typescript
 import { ResponsiveIconsBlock } from './icons-block';
 
-function MyComponent() {
+// Standard decorative separator
+export default function PageHeader() {
   return (
-    <div>
-      {/* Default behavior - shows placeholder until grid loads */}
+    <>
+      <HeroSection />
       <ResponsiveIconsBlock />
-      
-      {/* Force loading state */}
-      <ResponsiveIconsBlock loading={true} />
-      
-      {/* Responsive grid that adapts to screen width */}
-      <ResponsiveIconsBlock loading={false} />
-    </div>
+    </>
   );
 }
+
+// Force loading skeleton (e.g. while parent data fetches)
+export function LoadingLayout() {
+  return <ResponsiveIconsBlock loading={true} />;
+}
 ```
 
-The component automatically calculates columns based on viewport width (56px per column + 4 buffer), uses deterministic pseudo-random placement to ensure consistent layouts across renders, and includes responsive sizing with Tailwind classes. Icons are displayed with grayscale styling and proper grid borders for a cohesive visual presentation.
+## Behavior Notes
+
+| State | Renders |
+|---|---|
+| `loading={true}` | Pulsing `#2A2A2A` placeholder bar |
+| Grid not yet computed | Same placeholder bar |
+| Grid ready | Full icon grid |
+
+- Column count recalculates on `window.resize` (`Math.ceil(width / 56) + 4`)
+- All icons are forced to a muted gray (`grayscale + brightness` CSS filter) via an injected `<style>` block scoped to `.icons-block`
+- Marked `aria-hidden="true"` throughout — purely decorative, no accessibility semantics

package/src/components/.image-cropper.md

@@ -1,46 +1,55 @@
-<!-- source-hash: 42b352936943a6bb7818e0cd50fb78b7 -->
-A reusable React component that provides interactive image cropping functionality with drag/resize controls, rotation, zoom, and optional circular crop overlay for avatar creation.
+<!-- source-hash: 31fb4dc0d85de6bd77dd4c3210fe1592 -->
+Reusable React component for interactive image cropping, supporting drag/resize, zoom, rotation, circular crop mode, and PNG export via canvas.
 
 ## Key Components
 
-- **ImageCropper**: Main component providing full cropping interface
-- **ImageCropperResult**: Interface for exported crop data (dataUrl + blob)
-- **ImageCropperProps**: Configuration interface supporting aspect ratios, circular mode, and size limits
-- **loadImage**: Helper function for loading images with CORS support
-- **exportCrop**: Internal method that handles canvas-based image export with automatic scaling
+### `ImageCropperResult`
+Return type from a confirmed crop operation.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dataUrl` | `string` | Cropped PNG as a data URI |
+| `blob` | `Blob` | Corresponding PNG Blob |
+
+### `ImageCropperProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Source image URL or data URI |
+| `onComplete` | `(result) => void` | — | Fired when user confirms crop |
+| `onCancel` | `() => void` | — | Fired when user cancels |
+| `aspectRatio` | `number` | free-form | Width/height ratio |
+| `circular` | `boolean` | `false` | Circular overlay for avatars |
+| `maxSizePx` | `number` | `512` | Max exported image dimension |
+| `className` | `string` | — | Wrapper class override |
+
+### `ImageCropper`
+Main component. Internally manages crop position, zoom (1–3×), and rotation (0–360°). On confirm, renders the crop to an off-screen `<canvas>`, scales it to `maxSizePx`, optionally clips to a circle, then resolves a PNG `Blob` + data URL.
+
+**Keyboard shortcuts:** `Enter` confirms, `Escape` cancels.
 
 ## Usage Example
 
 ```typescript
-import { ImageCropper, ImageCropperResult } from './components/image-cropper'
-
-function AvatarUpload() {
-  const [imageSrc, setImageSrc] = useState<string>('')
-  const [showCropper, setShowCropper] = useState(false)
+import { ImageCropper, ImageCropperResult } from "@/components/image-cropper"
 
+function AvatarEditor({ imageUrl }: { imageUrl: string }) {
   const handleCropComplete = (result: ImageCropperResult) => {
-    // Use the cropped image
-    console.log('Cropped image:', result.dataUrl)
-    // Upload the blob: result.blob
-    setShowCropper(false)
+    // Upload the blob or set preview via dataUrl
+    console.log("PNG data URL:", result.dataUrl)
+    uploadAvatar(result.blob)
   }
 
   return (
-    <>
-      {showCropper && (
-        <ImageCropper
-          src={imageSrc}
-          onComplete={handleCropComplete}
-          onCancel={() => setShowCropper(false)}
-          aspectRatio={1} // Square crop
-          circular={true} // Avatar mode
-          maxSizePx={256} // Limit output size
-          className="max-w-md mx-auto"
-        />
-      )}
-    </>
+    <ImageCropper
+      src={imageUrl}
+      aspectRatio={1}
+      circular
+      maxSizePx={256}
+      onComplete={handleCropComplete}
+      onCancel={() => console.log("Cancelled")}
+      className="max-w-lg"
+    />
   )
 }
-```
-
-The component uses react-easy-crop for the cropping interface, shadcn/ui components for controls, and includes keyboard accessibility (Enter to apply, Esc to cancel). It automatically scales exported images to prevent oversized outputs while maintaining quality.
+```

package/src/components/.index.md

@@ -1,48 +1,42 @@
-<!-- source-hash: 99cf8e9f151ea0bbc01cf6e6113ebfc4 -->
-Central export hub for the Flamingo UI component library, providing a unified entry point for all components across chat, navigation, platform features, and utility components.
+<!-- source-hash: 6641c546041f6054d9c547ffd4f0f173 -->
+Central barrel export file for the Flamingo/OpenFrame shared UI component library. Re-exports all components, hooks, and utilities from the component subdirectories and individual component modules, enabling single-import access across the platform.
 
 ## Key Components
 
-**Component Categories:**
-- `chat` - Chat interface components and functionality
-- `features` - Platform-specific feature components  
-- `icons` - Icon system and components
-- `navigation` - Navigation and routing components
-- `platform` - Core platform UI elements
-- `ui` - Base UI component library
-
-**Individual Components:**
-- **Layout:** `fixed-layout-container`, `sliding-panel`, `footer`
-- **Data Display:** `vendor-display-button`, `pricing-display`, `metric-value`, `results-count`
-- **Media:** `media-carousel`, `image-cropper`, `hero-image-uploader`
-- **Interactive:** `filter-chip`, `pagination`, `contact-button`, `join-waitlist-cta`
-- **Loading States:** `dynamic-skeleton`, `content-loading-container`, `vendor-page-skeleton`
-- **Specialized:** `auth-stub`, `date-time-picker`, `onboarding`, `product-release`
+The file organizes exports into logical groups:
+
+| Group | Source |
+|---|---|
+| **Component Directories** | `chat`, `features`, `icons`, `navigation`, `platform`, `ui` |
+| **Individual Components** | `announcement-bar`, `media-carousel`, `pricing-display`, `vendor-display-button`, etc. |
+| **Shared Modules** | `onboarding`, `product-release`, `dev-section`, `roadmap`, `delivery`, `legal-document` |
+| **Utilities** | `unified-filter-logic`, `unified-pagination`, `persistent-filter-controls` |
+| **Auth & Loading** | `auth-stub`, `loading` |
+| **Date/Time** | `date-time-picker` |
+
+Notable named export: `DetailPageSkeleton` and its `DetailPageSkeletonProps` type are explicitly re-exported from `./shared/detail-page-skeleton`.
 
 ## Usage Example
 
 ```typescript
-// Import specific components
-import { 
-  VendorDisplayButton, 
-  MediaCarousel, 
-  FilterChip,
-  PricingDisplay 
-} from '@/components'
-
-// Or import component categories
-import { Button, Card } from '@/components' // from ui
-import { ChatInterface } from '@/components' // from chat
-
-function ProductPage() {
-  return (
-    <div>
-      <MediaCarousel images={productImages} />
-      <PricingDisplay price={pricing} />
-      <VendorDisplayButton vendor={vendor} />
-    </div>
-  )
-}
+// Instead of deep imports across many paths:
+import { VendorIcon } from '@flamingo/components/vendor-icon'
+import { Pagination } from '@flamingo/components/pagination'
+
+// Import everything from the single barrel:
+import {
+  VendorIcon,
+  Pagination,
+  DetailPageSkeleton,
+  type DetailPageSkeletonProps,
+  MspDisplay,
+  MediaCarousel,
+  UnifiedFilterLogic,
+} from '@flamingo/components'
 ```
 
-The index file uses client-side directive and maintains organized exports to prevent circular dependencies while providing clean import paths for consuming applications.
+## Notes
+
+- Marked `"use client"` — all exported components are React Client Components (Next.js App Router compatible).
+- `PageContainer` is intentionally not re-exported here; it is already available via `./ui/page-container`.
+- Duplicate `chat` export exists in the file; only one is resolved at runtime.

package/src/components/.input.md

@@ -1,44 +1,40 @@
-<!-- source-hash: 2373499921af8da961467280b796e6bc -->
-A reusable input component with dark theme styling, error states, and responsive typography that matches the admin interface design system.
+<!-- source-hash: 5d248f58ad416e0486c3eb74baeb29fc -->
+A styled, accessible HTML input component built with `React.forwardRef`, supporting error states and full HTML input attribute passthrough.
 
 ## Key Components
 
-- **Input**: Forwardable React input component with custom styling
-- **InputProps**: Interface extending HTML input attributes with an `invalid` prop for error states
+- **`Input`** — Forwarded-ref input component with ODS (OpenFrame Design System) theming, focus/disabled states, hover animations, and optional error styling
+- **`InputProps`** — Extended interface adding an `invalid` boolean prop on top of standard `React.InputHTMLAttributes<HTMLInputElement>`
 
 ## Usage Example
 
 ```typescript
-import { Input } from './components/input'
-
-function LoginForm() {
-  const [email, setEmail] = React.useState('')
-  const [hasError, setHasError] = React.useState(false)
-
-  return (
-    <div className="space-y-4">
-      <Input
-        type="email"
-        placeholder="Enter your email"
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-      />
-      
-      <Input
-        type="password"
-        placeholder="Enter password"
-        invalid={hasError}
-        className="mb-2"
-      />
-      
-      <Input
-        type="file"
-        accept="image/*"
-        className="file:mr-4 file:py-2 file:px-4"
-      />
-    </div>
-  )
-}
+import { Input } from "./input"
+
+// Basic usage
+<Input placeholder="Enter your email" type="email" />
+
+// With error state
+<Input
+  type="text"
+  invalid={true}
+  placeholder="Invalid field"
+/>
+
+// With ref forwarding
+const ref = React.useRef<HTMLInputElement>(null)
+<Input ref={ref} type="text" />
+
+// Disabled state
+<Input disabled placeholder="Not editable" />
 ```
 
-The component features a dark theme (`#161616` background), yellow accent colors (`#FFC008`), responsive text sizing (14px mobile, 18px desktop), and smooth transitions. The `invalid` prop adds red error styling, while the component maintains accessibility with proper focus states and touch optimization.
+## Styling Highlights
+
+| State | Applied Classes |
+|-------|----------------|
+| Default | `bg-ods-card border-ods-border text-ods-text-primary` |
+| Hover | `hover:border-ods-accent/30` |
+| Focus | `focus:border-ods-accent focus-visible:ring-ods-accent/20` |
+| Disabled | `disabled:cursor-not-allowed disabled:bg-ods-bg` |
+| Invalid | `border-red-500 focus-visible:ring-red-500` |

package/src/components/.logs-list.md

@@ -1,45 +1,56 @@
-<!-- source-hash: 7bc5ad978cbbb05e80afab56428fada8 -->
-A React component that renders a scrollable list of log entries with severity indicators, timestamps, and optional connecting lines between entries.
+<!-- source-hash: a6c222ce8e1ab58308ac9ed1a6a4776e -->
+A scrollable log viewer component that renders a list of `LogEntry` items with severity indicators, timestamps, and optional tool icons, connected by visual timeline connectors.
 
 ## Key Components
 
-- **`LogsList`** - Main component that renders a scrollable container of log entries with customizable height and styling
-- **`LogCard`** - Individual log entry component displaying severity dot, title, timestamp, and optional tool icon
-- **`formatTimestamp`** - Utility function that formats Date objects or ISO strings into "YYYY/MM/DD,HH:MM" format
+| Export | Type | Description |
+|--------|------|-------------|
+| `LogsList` | `React.ForwardRefExoticComponent` | Main container that renders a scrollable, bordered list of log entries |
+| `LogCard` | `React.FC` (internal) | Individual log row with severity dot, title, formatted timestamp, and optional tool icon |
+| `formatTimestamp` | `function` (internal) | Formats a `string \| Date` into `YYYY/MM/DD,HH:mm` display format |
+
+### `LogsList` Props (`LogsListProps`)
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `logs` | — | Array of `LogEntry` items to display |
+| `maxHeight` | `'400px'` | Container max height; use `'100%'` for full-height flex layout |
+| `showConnector` | `true` | Renders vertical timeline connector lines between entries |
+| `onLogClick` | — | Callback fired with the clicked `LogEntry` |
+| `loading` | `false` | Shows a loading state placeholder |
+| `emptyMessage` | `'No logs to display'` | Message shown when `logs` is empty |
+| `className` | — | Additional Tailwind classes for the container |
 
 ## Usage Example
 
 ```typescript
-import { LogsList } from './logs-list'
-import { LogEntry } from '../types/logs.types'
+import { LogsList } from './components/logs-list'
+import { LogEntry } from './types/logs.types'
 
 const logs: LogEntry[] = [
   {
     id: '1',
-    title: 'Application started successfully',
+    title: 'Agent task completed successfully',
     severity: 'info',
     timestamp: new Date(),
-    toolType: 'nodejs'
+    toolType: 'bash',
   },
   {
-    id: '2', 
-    title: 'Database connection failed',
-    severity: 'error',
-    timestamp: '2024-01-15T10:30:00Z'
-  }
+    id: '2',
+    title: 'Connection timeout detected',
+    severity: 'warning',
+    timestamp: '2024-01-15T10:30:00Z',
+  },
 ]
 
-function LogsViewer() {
+export default function LogsPanel() {
   return (
     <LogsList
       logs={logs}
       maxHeight="500px"
       showConnector={true}
-      onLogClick={(log) => console.log('Clicked:', log.title)}
-      emptyMessage="No logs available"
+      onLogClick={(log) => console.log('Selected:', log.id)}
     />
   )
 }
-```
-
-The component supports loading states, empty states, keyboard navigation, and visual connectors between log entries for a timeline-like appearance.
+```

package/src/components/.media-carousel.md

@@ -1,49 +1,48 @@
-<!-- source-hash: ff9ab9dccc65286acc64c16442ec5b60 -->
-A React carousel component that displays media items (images, videos, YouTube embeds) with navigation controls, touch/swipe support, and thumbnail preview.
+<!-- source-hash: 3e808df6d9836b82a787de725d9821af -->
+A responsive, accessible media carousel component supporting images, videos (MP4/HLS via MuxPlayer), and YouTube embeds with thumbnail navigation, swipe gestures, and keyboard controls.
 
 ## Key Components
 
-- **MediaCarousel**: Main carousel component with navigation and media display
-- **CarouselYouTubeEmbed**: Specialized YouTube embed with click-to-play functionality
-- **Navigation Icons**: SVG components for carousel controls (ChevronLeft, ChevronRight, Play)
-- **Media Renderers**: Separate functions for rendering images, videos, and YouTube embeds
-- **Touch/Swipe Handler**: Gesture-based navigation for mobile devices
+### `MediaCarousel` (default export)
+A memoized React component with the following props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `MediaItem[]` | — | Array of media items to display |
+| `className` | `string` | — | Additional CSS classes |
+| `aspectRatio` | `'16/9' \| '4/3' \| '3/2' \| '1/1'` | `'16/9'` | Container aspect ratio |
+| `showThumbnails` | `boolean` | `true` | Toggle thumbnail strip |
+| `autoPlay` | `boolean` | `false` | Auto-advance slides |
+| `objectFit` | `'contain' \| 'cover'` | `'contain'` | Image fit behavior |
+
+### Internal Renderers
+- `renderImage` — renders images with lazy loading and error fallback
+- `renderVideo` — delegates to `<Video>` (MuxPlayer facade) for MP4/HLS
+- `renderYouTubeEmbed` — delegates to `<Video>` with `kind="youtube"` for lite-youtube embed
+- `renderThumbnail` — clickable thumbnail with active indicator and video play overlay
 
 ## Usage Example
 
 ```typescript
 import { MediaCarousel } from './media-carousel';
+import { MediaItem } from '../utils/media-carousel-utils-stub';
 
-const mediaItems = [
-  {
-    type: 'image' as const,
-    src: '/images/photo1.jpg',
-    alt: 'Sample image'
-  },
-  {
-    type: 'video' as const,
-    src: '/videos/demo.mp4',
-    poster: '/images/video-thumb.jpg',
-    alt: 'Demo video'
-  },
-  {
-    type: 'youtube' as const,
-    src: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
-    alt: 'YouTube video'
-  }
+const items: MediaItem[] = [
+  { type: 'image', src: 'https://example.com/photo.jpg', alt: 'Photo' },
+  { type: 'youtube', src: 'https://youtube.com/watch?v=dQw4w9WgXcQ', alt: 'Demo' },
+  { type: 'video', src: 'https://example.com/clip.mp4', poster: 'https://example.com/thumb.jpg' },
 ];
 
-function App() {
-  return (
-    <MediaCarousel
-      media={mediaItems}
-      aspectRatio="16/9"
-      showThumbnails={true}
-      objectFit="contain"
-      className="max-w-4xl mx-auto"
-    />
-  );
-}
+<MediaCarousel
+  media={items}
+  aspectRatio="16/9"
+  showThumbnails={true}
+  objectFit="contain"
+/>
 ```
 
-The component automatically handles different media types, provides keyboard navigation (arrow keys), supports touch gestures for mobile, and includes error handling for failed media loads. YouTube videos use a click-to-activate pattern for better performance.
+## Interaction Support
+- **Keyboard**: `←` / `→` arrow keys when carousel is focused
+- **Touch/Swipe**: 50px minimum swipe distance triggers slide change
+- **Hover**: Navigation arrows reveal on hover; hidden for single-item carousels
+- **Accessibility**: `role="region"` and `aria-label` applied when multiple items exist