@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260725230219

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

@@ -1,55 +1,56 @@
-<!-- source-hash: 31fb4dc0d85de6bd77dd4c3210fe1592 -->
-Reusable React component for interactive image cropping, supporting drag/resize, zoom, rotation, circular crop mode, and PNG export via canvas.
+<!-- source-hash: 64a37d9b4443b9cc418e861a38bf66ff -->
+Interactive image cropping component built on `react-easy-crop`, supporting drag/resize, zoom, rotation, circular (avatar) mode, and PNG export with automatic downscaling.
 
 ## Key Components
 
-### `ImageCropperResult`
-Return type from a confirmed crop operation.
+| Export | Type | Description |
+|---|---|---|
+| `ImageCropper` | `React.FC` | Main cropper component |
+| `ImageCropperProps` | `interface` | Component prop contract |
+| `ImageCropperResult` | `interface` | Shape of the confirmed crop output |
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `dataUrl` | `string` | Cropped PNG as a data URI |
-| `blob` | `Blob` | Corresponding PNG Blob |
-
-### `ImageCropperProps`
+**Props**
 
 | 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 |
+| `onComplete` | `(result) => void` | — | Called with PNG data URL + Blob on confirm |
+| `onCancel` | `() => void` | — | Called when user cancels |
+| `aspectRatio` | `number` | free-form | Width / height ratio |
+| `circular` | `boolean` | `false` | Circular overlay for avatar crops |
+| `maxSizePx` | `number` | `512` | Maximum 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 AvatarEditor({ imageUrl }: { imageUrl: string }) {
-  const handleCropComplete = (result: ImageCropperResult) => {
-    // Upload the blob or set preview via dataUrl
-    console.log("PNG data URL:", result.dataUrl)
-    uploadAvatar(result.blob)
+function AvatarUploader({ imageUrl }: { imageUrl: string }) {
+  const handleComplete = (result: ImageCropperResult) => {
+    // Upload the Blob or use the data URL directly
+    console.log(result.dataUrl)   // "data:image/png;base64,..."
+    uploadToServer(result.blob)
   }
 
   return (
     <ImageCropper
       src={imageUrl}
-      aspectRatio={1}
-      circular
-      maxSizePx={256}
-      onComplete={handleCropComplete}
-      onCancel={() => console.log("Cancelled")}
-      className="max-w-lg"
+      onComplete={handleComplete}
+      onCancel={() => console.log("cancelled")}
+      circular          // avatar mode — circular clip mask
+      aspectRatio={1}   // 1:1 square
+      maxSizePx={256}   // export capped at 256×256 px
     />
   )
 }
-```
+```
+
+**Keyboard shortcuts:** `Enter` confirms the crop, `Escape` triggers `onCancel`.
+
+## Notes
+
+- Exported images are always **PNG**; the canvas is scaled so neither dimension exceeds `maxSizePx`.
+- The `crossOrigin="anonymous"` attribute on the internal image loader prevents canvas tainting for cross-origin sources.
+- Depends on `react-easy-crop`, `lucide-react`, and shadcn/ui `Button` / `Slider` primitives.
+- Source: [`components/image-cropper.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/image-cropper.tsx)

package/src/components/.index.md

@@ -1,42 +1,38 @@
-<!-- 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.
+<!-- source-hash: bd76de4698013e75e9f84d74a5ff3420 -->
+Central barrel export file for the `openframe-oss-lib` component library, aggregating all client-side React components, utilities, and shared modules under a single `"use client"` boundary.
 
 ## Key Components
 
-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`.
+| Export Group | Source Path | Description |
+|---|---|---|
+| Core UI modules | `./chat`, `./docs`, `./embeds`, `./features`, `./icons`, `./navigation`, `./platform`, `./ui` | Top-level feature category barrels |
+| Individual components | `./announcement-bar`, `./footer`, `./pagination`, `./pricing-display`, etc. | Standalone presentational components |
+| Shared modules | `./shared/onboarding`, `./shared/doc-search`, `./shared/dev-section`, `./shared/roadmap`, `./shared/legal-document` | Cross-host reusable feature slices |
+| Named exports | `DetailPageSkeleton`, `ArticleAuthorByline`, `MediaGalleryStrip`, `AuthorDetailView`, `EntityIcon` | Explicit exports for disambiguation or prop-type co-location |
+| `MediaItem` type | `../utils/media-carousel-utils-stub` | Canonical carousel item shape (overrides features barrel collision) |
 
 ## Usage Example
 
 ```typescript
-// 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 any component directly from the package root
 import {
-  VendorIcon,
+  Footer,
   Pagination,
+  EntityIcon,
+  type EntityIconValue,
+  ArticleAuthorByline,
+  type ArticleAuthorBylineProps,
+  MediaGalleryStrip,
+  type MediaGalleryStripProps,
   DetailPageSkeleton,
-  type DetailPageSkeletonProps,
-  MspDisplay,
-  MediaCarousel,
-  UnifiedFilterLogic,
-} from '@flamingo/components'
+} from '@openframe-oss-lib/components'
 ```
 
-## Notes
+## Important Notes
+
+- **Client boundary**: The entire barrel is marked `"use client"` — avoid importing into React Server Components.
+- **Server-safe JSON-LD**: For FAQ structured data in RSC contexts, import from the dedicated subpath `./components/faq/json-ld` instead of this barrel.
+- **`MediaItem` disambiguation**: This barrel exports `MediaItem` as the carousel item shape. The gallery-manager variant remains accessible via `./components/features`.
+- **`faq` subpath**: Also exposed as a standalone package.json subpath export, but it is equally client-only — not server-safe.
 
-- 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.
+**Source:** [`components/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/index.ts)

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

@@ -1,56 +1,60 @@
-<!-- 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.
+<!-- source-hash: 40c14f07658d894c96ba17a8967af646 -->
+Scrollable log feed component that renders a list of `LogEntry` items with severity indicators, timestamps, and optional tool icons — with loading and empty states.
 
 ## Key Components
 
 | 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` | `React.ForwardRefExoticComponent` | Main scrollable log list container |
+| `LogCard` | `React.FC` (internal) | Individual log entry row with click/keyboard support |
+| `formatTimestamp` | `function` (internal) | UTC-safe timestamp formatter preventing React hydration mismatch (#418) |
 
-### `LogsList` Props (`LogsListProps`)
+**`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 |
+|---|---|---|
+| `logs` | — | Array of `LogEntry` items to render |
+| `maxHeight` | `'400px'` | Container max height; use `'100%'` for full-height mode |
+| `showConnector` | `true` | Draws a vertical line connecting sequential log entries |
 | `onLogClick` | — | Callback fired with the clicked `LogEntry` |
-| `loading` | `false` | Shows a loading state placeholder |
+| `loading` | `false` | Shows a loading placeholder when `true` |
 | `emptyMessage` | `'No logs to display'` | Message shown when `logs` is empty |
-| `className` | — | Additional Tailwind classes for the container |
+| `className` | — | Additional CSS classes for the outer container |
 
 ## Usage Example
 
 ```typescript
-import { LogsList } from './components/logs-list'
-import { LogEntry } from './types/logs.types'
+import { LogsList } from '@openframe-oss-lib/components'
+import type { LogEntry } from '@openframe-oss-lib/types'
 
 const logs: LogEntry[] = [
   {
     id: '1',
-    title: 'Agent task completed successfully',
+    title: 'Backup job completed',
     severity: 'info',
     timestamp: new Date(),
-    toolType: 'bash',
+    toolType: 'backup',
   },
   {
     id: '2',
-    title: 'Connection timeout detected',
+    title: 'Disk usage above 90%',
     severity: 'warning',
-    timestamp: '2024-01-15T10:30:00Z',
+    timestamp: '2025-01-15T08:30:00Z',
   },
 ]
 
-export default function LogsPanel() {
+export default function AuditPanel() {
   return (
     <LogsList
       logs={logs}
-      maxHeight="500px"
-      showConnector={true}
+      maxHeight="600px"
+      showConnector
       onLogClick={(log) => console.log('Selected:', log.id)}
     />
   )
 }
-```
+```
+
+> **Hydration note:** `formatTimestamp` uses UTC getters (`getUTCFullYear`, etc.) to ensure timestamps are identical between SSR and client rendering, preventing React hydration error #418.
+
+**Source:** [`logs-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/logs-list.tsx)

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

@@ -1,48 +1,69 @@
-<!-- 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.
+<!-- source-hash: 8512b2544239a58f8faa59a6fd3794a7 -->
+Accessible, memoized React carousel component for displaying mixed media (images, videos, YouTube embeds) with dot pagination, keyboard navigation, touch swipe support, and broken-image fallback handling.
 
 ## Key Components
 
 ### `MediaCarousel` (default export)
-A memoized React component with the following props:
+A `memo`-wrapped component implementing the canonical slide viewer used across OpenFrame homepage categories, vendor screenshots, profiles, and Reddit embeds.
+
+**Props (`MediaCarouselProps`):**
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `media` | `MediaItem[]` | — | Array of media items to display |
-| `className` | `string` | — | Additional CSS classes |
+|---|---|---|---|
+| `media` | `MediaItem[]` | — | Array of slide descriptors |
 | `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 |
+| `showArrows` | `boolean` | `true` | Hover-revealed prev/next arrows |
+| `objectFit` | `'contain' \| 'cover'` | `'contain'` | Image fit within container |
+| `posterPriority` | `boolean` | `false` | Eager-loads first slide (LCP optimization) |
+| `transformImageSrc` | `(url: string) => string` | — | URL rewrite hook (e.g. proxy `http://` sources) |
+| `reserveDotRow` | `boolean` | `false` | Always reserves dot-row height to prevent layout shift on media set swaps |
+
+### Internal Helpers
 
-### 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
+| Function | Description |
+|---|---|
+| `renderVideo` | Routes `video`/`youtube` items through the `<Video>` SSoT component |
+| `renderImage` | Renders images with skeleton loading, opacity fade-in, and broken-URL fallback UI |
+| `renderImageUnavailable` | Fallback UI with `ImageOffIcon` and original URL link when image 404s |
+| `renderMainMedia` | Dispatches to `renderVideo` or `renderImage` based on `item.type` |
+| `getAspectRatioClass` | Maps `aspectRatio` prop to Tailwind aspect-ratio class |
 
 ## Usage Example
 
 ```typescript
 import { MediaCarousel } from './media-carousel';
-import { MediaItem } from '../utils/media-carousel-utils-stub';
+import type { MediaItem } from '../utils/media-carousel-utils-stub';
 
-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' },
+const slides: MediaItem[] = [
+  { type: 'image', src: 'https://cdn.example.com/screenshot.png', alt: 'Dashboard' },
+  { type: 'youtube', src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', alt: 'Demo' },
+  { type: 'video', src: 'https://stream.mux.com/video.m3u8', poster: 'https://cdn.example.com/poster.jpg' },
 ];
 
+// Vendor detail page — prioritize first image for LCP, proxy mixed content
 <MediaCarousel
-  media={items}
+  media={slides}
   aspectRatio="16/9"
-  showThumbnails={true}
   objectFit="contain"
+  posterPriority
+  transformImageSrc={(url) => url.replace('http://', 'https://proxy.example.com/')}
+/>
+
+// Categories showcase — reserve dot row so 1-vs-N-slide swap never shifts layout
+<MediaCarousel
+  media={categorySlides}
+  reserveDotRow
+  showArrows={false}
 />
 ```
 
-## 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
+## Interaction Model
+
+- **Touch:** Swipe threshold of 50px triggers `nextSlide`/`prevSlide`; edge-case `clientX === 0` handled via explicit `null` checks (not truthiness).
+- **Keyboard:** `ArrowLeft`/`ArrowRight` when the carousel `<div>` has focus; disabled for single-slide sets.
+- **Index safety:** `currentIndex` is clamped via `useEffect` whenever `media.length` shrinks at runtime.
+- **Image loading:** Each image is keyed by URL (`loadedImageSrc`), preventing a late `onLoad` from a previous slide from revealing the current image prematurely.
+
+## Source
+
+[`media-carousel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/media-carousel.tsx)

package/src/components/.metric-value.md

@@ -1,37 +1,40 @@
-<!-- source-hash: 4ad98f6815de9109cf1a167244731e12 -->
-A React component that displays a metric value with an associated label in a clean, inline format. The main value is prominently displayed with a smaller, muted label to provide context.
+<!-- source-hash: 386c4083aa6f39bec5016b7561a578c9 -->
+Renders a styled metric display pairing a prominent primary value with a smaller secondary label, suitable for dashboards and stat blocks.
 
 ## Key Components
 
-- **MetricValue**: Main component that renders a value-label pair
-- **MetricValueProps**: TypeScript interface defining the component's props
-  - `value`: The primary metric value (string or number)
-  - `label`: Descriptive text shown in smaller, muted styling
-  - `className`: Optional CSS classes for customization
+**`MetricValue`** — Named export functional component
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string \| number` | ✅ | The primary metric to display (e.g., `30`, `"99%"`) |
+| `label` | `string` | ✅ | Descriptive label rendered below/beside the value (e.g., `"Generation Time"`) |
+| `className` | `string` | ❌ | Optional class overrides via `cn()` utility |
 
 ## Usage Example
 
 ```typescript
-import { MetricValue } from './metric-value';
+import { MetricValue } from '@/components/metric-value';
 
-// Display generation time metric
-<MetricValue 
-  value="30s" 
-  label="Generation Time" 
-/>
+// Basic numeric stat
+<MetricValue value={30} label="s Generation Time" />
 
-// Display numeric metrics with custom styling
-<MetricValue 
-  value={1249} 
-  label="Total Requests"
-  className="text-xl font-bold"
+// String percentage with custom class
+<MetricValue
+  value="99.9%"
+  label="Uptime"
+  className="mt-4"
 />
 
-// Display percentage values
-<MetricValue 
-  value="94.2%" 
-  label="Success Rate"
-/>
+// Inside a stat grid
+<div className="flex gap-8">
+  <MetricValue value={142} label="Tickets Resolved" />
+  <MetricValue value="4.8" label="Avg CSAT Score" />
+</div>
 ```
 
-The component uses a horizontal flex layout with the value displayed in primary text color and the label in secondary (muted) text. It's styled with the DM Sans font family and includes whitespace-nowrap to prevent line breaks, making it ideal for dashboard metrics and status displays.
+## Notes
+
+- Uses `text-h4` for the value and `text-h6 text-ods-text-secondary` for the label, following the ODS (OpenFrame Design System) typography scale.
+- `whitespace-nowrap` prevents wrapping on tight layouts.
+- Composes with [`cn()`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/cn.ts) for safe Tailwind class merging.

package/src/components/.msp-display.md

@@ -1,36 +1,42 @@
-<!-- source-hash: 277daefc2a9ad48ff5ace711df4ffcf5 -->
-A React component that displays MSP (Managed Service Provider) information with a logo avatar and truncated name display.
+<!-- source-hash: a699424bd0f8d631d337d18d2000076d -->
+Renders an MSP (Managed Service Provider) identity display combining a square avatar logo with the MSP's name in a flex layout.
 
 ## Key Components
 
-- **MSPDisplay**: Main component that renders an MSP with their logo and name
-- **MSPDisplayProps**: TypeScript interface defining component props
-  - `name`: MSP name (required)
-  - `logoUrl`: Optional logo image URL
-  - `size`: Avatar size in pixels (defaults to 40px)
-  - `className`: Additional CSS classes
+### `MSPDisplay`
+A client-side React component that displays an MSP's branding with a fallback-aware avatar and truncated name label.
+
+**Props (`MSPDisplayProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | MSP display name (used as avatar fallback and `alt` text) |
+| `logoUrl` | `string \| null` | `undefined` | Optional logo URL, run through the image proxy |
+| `size` | `number` | `40` | Avatar dimensions in pixels (square) |
+| `className` | `string` | — | Additional CSS classes for the wrapper |
+
+**Internal dependencies:**
+- [`SquareAvatar`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/ui/square-avatar.tsx) — renders the square avatar with fallback initials
+- [`getProxiedImageUrl`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/image-proxy.ts) — proxies external logo URLs to avoid CORS/mixed-content issues
+- [`cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/cn.ts) — utility for conditional class merging
 
 ## Usage Example
 
 ```typescript
-import { MSPDisplay } from './msp-display';
-
-// Basic MSP display
-<MSPDisplay name="TechCorp Solutions" />
+import { MSPDisplay } from '@flamingo-stack/openframe-oss-lib';
 
-// With logo and custom size
-<MSPDisplay 
-  name="Acme IT Services"
-  logoUrl="https://example.com/logo.png"
-  size={60}
+// With a logo
+<MSPDisplay
+  name="Acme IT Solutions"
+  logoUrl="https://acme.example.com/logo.png"
+  size={48}
 />
 
-// With custom styling
-<MSPDisplay 
-  name="Global Tech Partners"
-  logoUrl="/logos/global-tech.png"
-  className="bg-gray-100 p-3 rounded-lg"
+// Name-only fallback (renders initials avatar)
+<MSPDisplay
+  name="Acme IT Solutions"
+  className="border-b pb-4"
 />
 ```
 
-The component uses a `SquareAvatar` for the logo display with automatic fallback to initials if no logo is provided. The name is truncated with ellipsis if it overflows the container width. The layout uses flexbox with a 2-unit gap and ensures proper text truncation with `min-w-0`.
+> **Note:** If `logoUrl` is provided but `getProxiedImageUrl` returns `null` or an empty string, the component falls back to the original `logoUrl` directly. If no URL is available at all, `SquareAvatar` renders initials derived from `name`.

package/src/components/.open-source-features.md

@@ -1,28 +1,30 @@
-<!-- source-hash: 86b90e3350490d5e683b6b4b06497f43 -->
-A Next.js client component that renders a responsive marketing section showcasing OpenFrame's open-source value propositions as a 4-column feature card grid.
+<!-- source-hash: 3a6d55ae1b91e13e9941c8273186b79b -->
+A client-side React section component that renders a responsive grid of feature cards highlighting OpenFrame's open-source value proposition.
 
 ## Key Components
 
-- **`FeatureCard`** — Reusable card component accepting an icon, title, and description; renders with hover transition styling using ODS design tokens
-- **`OpenSourceFeatures`** — Main section component that composes the feature grid with a headline and four predefined feature entries
-- **`features` array** — Static data defining the four pillars: *Built on FOSS*, *Own Your Stack*, *Modular by Design*, and *Community-Powered*
-
-## Props
-
-### `FeatureCardProps`
+### `FeatureCard` (internal)
+A styled card component displaying an icon, title, and description. Accepts `FeatureCardProps`:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `icon` | `React.ReactNode` | Lucide icon element rendered in the card header |
-| `title` | `string` | Feature headline text |
-| `description` | `string` | Supporting body copy |
+| `icon` | `React.ReactNode` | Lucide icon element |
+| `title` | `string` | Feature heading |
+| `description` | `string` | Feature body text |
+
+### `OpenSourceFeatures` (default export)
+The main section component. Renders four hardcoded feature cards in a responsive 1→2→4 column grid:
+
+- **Built on FOSS** — `Terminal` icon
+- **Own Your Stack** — `DollarSign` icon
+- **Modular by Design** — `Network` icon
+- **Community-Powered** — `Users` icon
 
 ## Usage Example
 
 ```typescript
-import OpenSourceFeatures from '@/components/open-source-features';
+import OpenSourceFeatures from './open-source-features';
 
-// Drop into any page layout — no props required
 export default function LandingPage() {
   return (
     <main>
@@ -32,17 +34,12 @@ export default function LandingPage() {
 }
 ```
 
-To add a custom feature card standalone:
+## Notes
 
-```typescript
-import { FeatureCard } from '@/components/open-source-features';
-import { Shield } from 'lucide-react';
-
-<FeatureCard
-  icon={<Shield className="w-6 h-6" />}
-  title="Secure by Default"
-  description="Auditable code with no vendor lock-in."
-/>
-```
+- Marked `"use client"` — requires a Next.js App Router client boundary.
+- Icons sourced from `lucide-react` (`Terminal`, `DollarSign`, `Network`, `Users`).
+- Section heading style imported from `./layout/page-heading` via `SECTION_HEADING_CLASS`.
+- Hover states and transitions handled via Tailwind utility classes (`hover:bg-ods-bg-hover`, `transition-colors`).
+- Feature list is statically defined inside the component; to make it data-driven, extract the `features` array to a separate constants file.
 
-> **Note:** `FeatureCard` is not a named export by default — export it explicitly if reuse outside this component is needed. The section uses ODS design tokens (`ods-card`, `ods-border`, `ods-accent`) from the OpenFrame design system.
+**Source:** [`open-source-features.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/open-source-features.tsx)