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

package/src/components/embeds/.pdf-viewer.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 5e30f7353e7e3464bee931d93655ddb7 -->
+A React client component that renders a PDF file with an embedded iframe viewer and action buttons for previewing and downloading.
+
+## Key Components
+
+### `PdfViewerProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `src` | `string` | URL of the PDF file to display |
+| `fileName` | `string?` | Display name shown in the header (defaults to `"PDF Document"`) |
+| `onPreview` | `() => void?` | Custom preview handler; if omitted, opens `src` in a new tab |
+| `onDownload` | `() => void?` | Custom download handler; if omitted, opens `src` in a new tab |
+| `height` | `string?` | Optional height passed to the embedded iframe |
+
+### `PdfViewer`
+The primary exported component. Renders an empty state with an Adobe PDF icon when `src` is falsy, otherwise displays:
+- A header row with the PDF icon, file name, and **Preview**/**Download** buttons
+- An `EmbedIframe` for inline viewing
+
+## Usage Example
+
+```typescript
+// Basic usage — buttons open src in a new tab
+<PdfViewer
+  src="https://example.com/report.pdf"
+  fileName="Q1 Report"
+/>
+
+// With custom handlers
+<PdfViewer
+  src="https://example.com/report.pdf"
+  fileName="Q1 Report"
+  height="600px"
+  onPreview={() => openPreviewModal()}
+  onDownload={() => triggerDownload()}
+/>
+```
+
+## Notes
+
+- When `onPreview` or `onDownload` callbacks are provided, the corresponding button uses `onClick` instead of an `href`, preventing a new tab from opening.
+- The component is responsive: button layout switches from stacked (`flex-col`) on mobile to inline (`flex-row`) on `sm` breakpoints.
+- Source: [`pdf-viewer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/pdf-viewer.tsx)

package/src/components/embeds/.reddit-embed-client.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 69e19d1dd3c34ac5624e382237522c62 -->
+React client component that fetches and renders Reddit post embeds with support for video, gallery, and image previews, using a centralized social embed cache for data fetching.
+
+## Key Components
+
+### `RedditEmbedClient`
+Main export. Accepts a Reddit post `url` and optional `maxWidth`, fetches post data via `socialCache.fetchWithHierarchy`, and renders a styled embed card.
+
+### `RedditPost` Interface
+Typed shape for the Reddit API JSON response, covering text, author, vote counts, preview images, hosted video, gallery data, and media metadata.
+
+### `getMediaContent(): MediaItem[]`
+Internal helper that extracts media from a post in priority order:
+1. **Reddit-hosted video** (`v.redd.it` DASH streams) with poster image generation
+2. **Gallery posts** (`gallery_data` + `media_metadata`)
+3. **Single preview images** (best resolution ≤ 1200 px wide)
+
+Skips all media extraction when the API signals a removed or deleted post (`selftext === '[removed]'`, `author === '[deleted]'`, etc.).
+
+### Inline SVG Icons
+`MessageCircleIcon`, `ExternalLinkIcon`, `ArrowUpIcon`, `ClockIcon`, `UserIcon`, `RedditIcon` — self-contained SVGs to avoid external icon dependencies.
+
+### `RedditProfilePic`
+Minimal avatar component rendering a Reddit-orange circle with `u/` text instead of fetching user avatars.
+
+## Usage Example
+
+```typescript
+import { RedditEmbedClient } from './reddit-embed-client';
+
+// In a React component / MDX page:
+<RedditEmbedClient
+  url="https://www.reddit.com/r/nextjs/comments/abc123/some_post"
+  maxWidth={600}
+/>
+```
+
+The component is a `"use client"` boundary — server components should use dynamic import or a server-side wrapper. It renders a skeleton loader while fetching, a fallback error card (with a direct Reddit link) on failure, and the full post card with `MediaCarousel` on success.
+
+**Source:** [`reddit-embed-client.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/reddit-embed-client.tsx)

package/src/components/embeds/.rich-markdown-runtime.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 5b535a89e6cfb9cb002c7fd306bbaa13 -->
+Provides a lightweight React context (`RichMarkdownRuntimeContext`) that threads proxy endpoint URLs and an optional image-transform function from `<RichMarkdownRenderer>` down to its satellite embed clients, without depending on the chat runtime.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `RichMarkdownRuntime` | Interface | Defines the three proxy URLs and the `transformImageSrc` knob |
+| `RichMarkdownRuntimeProvider` | React component | Wraps subtrees with resolved runtime values; memoizes to prevent unnecessary re-renders |
+| `useRichMarkdownRuntime` | Hook | Reads the ambient runtime; returns hub-matching defaults when called outside any provider |
+
+### `RichMarkdownRuntime` Interface Fields
+
+| Field | Default | Description |
+|---|---|---|
+| `redditProxyUrl` | `/api/blog/reddit-proxy` | Proxy endpoint for Reddit embeds |
+| `twitterProxyUrl` | `/api/blog/twitter-proxy` | Proxy endpoint for Twitter/X embeds |
+| `ogScraperUrl` | `/api/og-scraper` | Endpoint for OG link-preview scraping |
+| `transformImageSrc` | `() => null` (identity / no rewrite) | Hub-only Supabase image transformer; return `null` to use `src` as-is |
+
+## Usage Example
+
+**Hub usage — override the image transformer, inherit proxy defaults:**
+
+```typescript
+import { RichMarkdownRuntimeProvider } from './rich-markdown-runtime'
+
+function BlogLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <RichMarkdownRuntimeProvider
+      transformImageSrc={(src, opts) =>
+        supabaseImageTransform(src, opts)
+      }
+    >
+      {children}
+    </RichMarkdownRuntimeProvider>
+  )
+}
+```
+
+**Embedder usage — read the runtime inside a satellite client:**
+
+```typescript
+import { useRichMarkdownRuntime } from './rich-markdown-runtime'
+
+function RedditEmbedClient({ postUrl }: { postUrl: string }) {
+  const { redditProxyUrl } = useRichMarkdownRuntime()
+  // Falls back to '/api/blog/reddit-proxy' if no provider is in scope
+  const data = useFetch(`${redditProxyUrl}?url=${postUrl}`)
+}
+```
+
+**Source:** [`rich-markdown-runtime.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/rich-markdown-runtime.tsx)

package/src/components/embeds/.twitter-embed-client.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 4a337b178db352704df1ccdf20c1ec95 -->
+A client-side React component that fetches and renders a styled Twitter/X post embed using the oEmbed API, with loading skeletons, error fallback states, and extracted tweet metadata.
+
+## Key Components
+
+### `TwitterEmbedClient`
+The main exported component. Accepts a tweet URL (or optional `tweetId`) and renders a fully styled card with profile picture, tweet text, links, and engagement stat labels.
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `url` | `string` | — | Full Twitter/X post URL |
+| `tweetId` | `string?` | — | Optional explicit tweet ID |
+| `maxWidth` | `number` | `700` | Controls content area max height calculation |
+
+### Internal SVG Icons
+Inline SVG components (`MessageCircleIcon`, `ExternalLinkIcon`, `HeartIcon`, `RepeatIcon`, `ClockIcon`, `UserIcon`) avoid external icon library dependencies. `XIcon` wraps the shared `XLogo` component.
+
+### `TwitterOEmbedResponse`
+TypeScript interface modeling the oEmbed API response shape (author info, HTML, dimensions, provider metadata).
+
+### Key Behaviors
+- **Cache-first fetching** via `socialCache.fetchWithHierarchy` — deduplicated, runs once via `initializationDone` ref
+- **URL normalization** — extracts tweet ID via regex from any `twitter.com` or `x.com` URL
+- **Profile pictures** — fetched from `unavatar.io/twitter/{username}` with an inline SVG base64 fallback on error
+- **Text extraction** — parses oEmbed HTML with `DOMParser`, strips attribution suffix, truncates at 600 characters
+
+## Usage Example
+
+```typescript
+import { TwitterEmbedClient } from './twitter-embed-client';
+
+// Minimal usage with full URL
+<TwitterEmbedClient url="https://x.com/OpenAI/status/1234567890123456789" />
+
+// With explicit tweet ID and custom width
+<TwitterEmbedClient
+  url="https://x.com/OpenAI/status/1234567890123456789"
+  tweetId="1234567890123456789"
+  maxWidth={500}
+/>
+```
+
+**Runtime requirement:** The component calls `useRichMarkdownRuntime()` to obtain `twitterProxyUrl`. A compatible runtime provider must exist in the component tree — see [`useRichMarkdownRuntime`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/rich-markdown/rich-markdown-runtime.ts) for context setup details.

package/src/components/faq/.faq-document-page.md

@@ -0,0 +1,68 @@
+<!-- source-hash: 8a01e8caf8a388648de21a863fa2e4b4 -->
+Full-page FAQ document component that composes `PageShell`, `PageLayout`, and `FaqSection` into a single drop-in page, mirroring the `LegalDocumentPage` / `DevSectionPage` pattern so host pages need only pass config and SSR-resolved data.
+
+## Key Components
+
+### `FaqDocumentPage`
+
+The primary export. Renders a complete `/faqs` page with:
+
+- **`PageLayout` `TitleBlock`** — owns the `<h1>` (title + subtitle), keeping `FaqSection` headings at `<h2>`/`<h3>` for correct SEO outline
+- **`PageShell`** — optional standalone `<main>` container (disable via `shell={false}` when the host layout already provides one)
+- **`FaqSection`** — receives SSR-hydrated `initialFaqs` to skip its client self-fetch, or omit for self-fetching embed mode
+- **Back button** — follows the same `{ label, href } | false` pattern as `LegalDocumentPage` / `DevSectionPage`
+
+### `FaqDocumentPageProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `'Frequently Asked Questions'` | Page `<h1>` text |
+| `subtitle` | `string` | — | Subtitle beneath the title |
+| `backButton` | `{ label?, href? } \| false` | `{ label: 'Back to home', href: '/' }` | Back nav; `false` hides it |
+| `shell` | `boolean` | `true` | Wrap with `PageShell`; set `false` when host owns `<main>` |
+| `initialFaqs` | `Faq[]` | — | SSR-resolved FAQs; omit for client self-fetch |
+| `emitJsonLd` | `boolean` | `false` | Emit `FAQPage` schema.org JSON-LD |
+| `jsonLd` | `FaqSchemaOptions` | — | JSON-LD name/description/url overrides |
+| `apiBaseUrl` | `string` | — | Base URL for `/api/faqs` (reverse-proxy embedders) |
+| `entityType` / `entityId` | `string / number` | — | Optional entity scoping |
+| `minResults` | `number` | — | Minimum FAQ count before rendering |
+
+## Usage Example
+
+**Standalone page (SSR, shell on):**
+
+```typescript
+// app/faqs/page.tsx
+import { FaqDocumentPage } from '@openframe-oss-lib/components/faq';
+import { fetchFaqs } from '@/lib/api';
+
+export default async function FaqsPage() {
+  const initialFaqs = await fetchFaqs({ platform: 'acme' });
+
+  return (
+    <FaqDocumentPage
+      title="Help Center"
+      subtitle="Find answers to common questions"
+      initialFaqs={initialFaqs}
+      emitJsonLd
+      jsonLd={{ url: 'https://acme.com/faqs' }}
+    />
+  );
+}
+```
+
+**Embedded inside host layout (shell off, no back button):**
+
+```typescript
+<FaqDocumentPage
+  shell={false}
+  backButton={false}
+  apiBaseUrl="https://api.acme.com"
+  entityType="product"
+  entityId={42}
+/>
+```
+
+## Source
+
+[`faq-document-page.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/faq-document-page.tsx)

package/src/components/faq/.faq-section.md

@@ -0,0 +1,55 @@
+<!-- source-hash: b59367c69f5c5d87cc41d5f3c3c747da -->
+Renders a grouped, deep-linkable FAQ section with category jump-navigation, scroll-spy active states, hash-based accordion expansion, and optional JSON-LD schema emission.
+
+## Key Components
+
+### `FaqSection` (default export)
+The top-level client component that fetches FAQ data via `useSelfFetch`, groups results by section, and renders either a flat or grouped accordion layout depending on whether multiple categories exist.
+
+**Props (`FaqSectionProps`):**
+
+| Prop | Type | Description |
+|---|---|---|
+| `initialFaqs` | `Faq[]` | SSR hydration seed — skips first client fetch |
+| `entityType` / `entityId` | `string` / `number\|string` | Scopes the `/api/faqs` request to a specific entity |
+| `heading` | `ReactNode \| null` | Custom heading; `null` = no heading (host owns `<h1>`) |
+| `emitJsonLd` | `boolean` | Injects FAQPage `schema.org` JSON-LD `<script>` |
+| `jsonLd` | `FaqSchemaOptions` | Overrides for JSON-LD `name`/`description`/`url` |
+| `minResults` | `number` | Maps to `?count=` query param |
+| `apiBaseUrl` | `string` | Fetch-URL prefix for third-party embeds/proxies |
+
+### `GroupedFaqList` (internal)
+Renders category jump-nav pills (`<a href="#slug">`) above stacked accordion sections. Includes:
+- **Scroll-spy** via `IntersectionObserver` — highlights the pill for the section in view
+- **Hash dispatch** — item hashes (`#faq-item-<id>`) auto-expand the cited accordion row; section hashes (`#faq-<slug>`) activate the matching pill
+- `useScrollToHash` with sticky-header offset compensation
+
+### `groupFaqsBySection` (internal)
+Pure function that groups `Faq[]` into `FaqGroup[]` ordered by first-seen display order. Uncategorized items (blank/missing `section`) sink to the end.
+
+### `buildFaqsUrl` (internal)
+Composes the `/api/faqs` fetch URL via `buildSuggestionUrl`, compatible with `apiBaseUrl`, `entityType`, `entityId`, and `minResults`.
+
+## Usage Example
+
+```typescript
+// Server component passes SSR-fetched FAQs; client skips re-fetch
+import { FaqSection } from '@openframe-oss-lib/components'
+
+export default async function SupportPage() {
+  const faqs = await fetchFaqsForEntity('product', 42)
+
+  return (
+    <FaqSection
+      initialFaqs={faqs}
+      entityType="product"
+      entityId={42}
+      emitJsonLd
+      jsonLd={{ name: 'Product FAQs', url: 'https://example.com/support' }}
+      minResults={10}
+    />
+  )
+}
+```
+
+> **Source:** [`faq-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/faq-section.tsx)

package/src/components/faq/.index.md

@@ -0,0 +1,29 @@
+<!-- source-hash: f21bd805bd5c6f7a4aa946b0f56c688e -->
+Re-exports the client-side FAQ UI components (`FaqSection` and `FaqDocumentPage`) from the `components/faq` subpath barrel, explicitly excluding server-only JSON-LD utilities to preserve `"use client"` bundle safety.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `FaqSection` | Component | Client-side FAQ accordion/section UI component |
+| `FaqSectionProps` | Type | Props interface for `FaqSection` |
+| `FaqDocumentPage` | Component | Full-page FAQ document layout component |
+| `FaqDocumentPageProps` | Type | Props interface for `FaqDocumentPage` |
+
+> **Not exported here:** `baseFaqSchema` and `buildFaqJsonLdFromFaqs` — these are server-safe utilities intentionally excluded from this client bundle. Import them from the dedicated server subpath instead.
+
+## Usage Example
+
+```typescript
+// ✅ Client Component — import from the client subpath
+import { FaqSection, FaqDocumentPage } from '@flamingo-stack/openframe-oss-lib/components/faq'
+
+// ✅ Server Component — import JSON-LD builder from the server-safe subpath
+import { buildFaqJsonLdFromFaqs } from '@flamingo-stack/openframe-oss-lib/components/faq/json-ld'
+```
+
+## Notes
+
+- This barrel is compiled by tsup with a `"use client"` banner, making it safe for React client component trees.
+- Server Components **must not** import JSON-LD builders from this subpath — use `./components/faq/json-ld` as wired in `tsup.config.ts` and exposed via `package.json#exports`.
+- See [`tsup.config.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tsup.config.ts) for the server/universal entry block configuration.

package/src/components/faq/.json-ld.md

@@ -0,0 +1,48 @@
+<!-- source-hash: a1dee0a9eb92d427adbd583bf0d77420 -->
+Utility for building [Schema.org FAQPage](https://schema.org/FAQPage) JSON-LD structured data from FAQ entries. Designed as a pure, framework-free module safe for use in React Server Components.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `FaqSchemaOptions` | Interface | Optional branding overrides: `name`, `description`, `url` |
+| `baseFaqSchema` | Function | Returns base `FAQPage` schema object without `mainEntity` |
+| `buildFaqJsonLdFromFaqs` | Function | Builds complete FAQ JSON-LD from a `Faq[]` array |
+
+## Usage Example
+
+```typescript
+import { buildFaqJsonLdFromFaqs } from 'openframe-oss-lib/components/faq'
+
+const faqs = [
+  { question: 'What is OpenFrame?', answer: 'A unified MSP platform.' },
+  { question: 'Is it open source?', answer: 'Yes.' },
+]
+
+const jsonLd = buildFaqJsonLdFromFaqs(faqs, {
+  name: 'OpenFrame FAQ',
+  description: 'Common questions about the OpenFrame platform.',
+  url: 'https://openframe.ai/faq',
+})
+
+// In a Next.js Server Component:
+export default function FaqPage() {
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      {/* ... */}
+    </>
+  )
+}
+```
+
+## Notes
+
+- **Server Component safe** — no React or browser dependencies. Import via the `./components/faq` subpath export only. Avoid the root `./components` barrel (`"use client"`) to prevent pulling the client graph into the server bundle.
+- Defaults to `"Frequently Asked Questions"` / `"Answers to common questions."` when no `FaqSchemaOptions` are provided.
+- The `url` field is omitted from the schema output when not supplied.
+
+**Source:** [`src/components/faq/json-ld.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/faq/json-ld.ts)

package/src/components/features/.array-entry-manager.md

@@ -1,44 +1,52 @@
-<!-- source-hash: 9a66a790bb4e14efee7ac5e9ffc0cfb8 -->
-A generic, reusable React component for managing arrays of objects with inline add, edit, remove, and multi-line paste support. Supports both immediate and deferred (save-gated) change modes.
+<!-- source-hash: f65d2f7c16e2d70cc404f49cf8a55c51 -->
+A generic, reusable React component for managing ordered lists of structured objects, supporting inline editing, item removal, multi-line paste, and optional deferred saves.
 
 ## Key Components
 
-### `ArrayEntryManager<T>`
-A generic client component that renders a labeled list of editable input entries backed by a typed array.
-
-**Props:**
+### `ArrayEntryManagerProps<T>`
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `title` | `ReactNode` | Section label; supports strings or badge components |
-| `items` | `T[]` | Array of objects to manage |
-| `onChange` | `(items: T[]) => void` | Called on change (immediate) or save (deferred) |
+|---|---|---|
+| `title` | `ReactNode` | Section header; supports strings or badge elements |
+| `items` | `T[]` | Array of items to manage |
+| `onChange` | `(items: T[]) => void` | Called when items change (immediately or on save) |
 | `fieldKey` | `keyof T` | Object key to bind each input to |
-| `requireSave` | `boolean` | When `true`, buffers edits locally until "Save" is clicked |
+| `placeholder` | `string` | Input placeholder text |
+| `emptyMessage` | `string` | Text shown when the list is empty |
+| `addButtonText` | `string` | Label for the add button |
+| `requireSave` | `boolean` | Enables draft mode — defers `onChange` until Save is clicked |
 | `onDirtyChange` | `(isDirty: boolean) => void` | Notifies parent of unsaved changes |
-| `renderLabel` | `(item: T, index: number) => ReactNode` | Custom renderer above each input |
-| `isSaving` | `boolean` | Shows spinner on the save button during async operations |
+| `renderLabel` | `(item: T, index: number) => ReactNode` | Custom per-entry label or badge renderer |
+| `isSaving` | `boolean` | Shows spinner on the Save button during async operations |
+
+### `ArrayEntryManager<T>` (Component)
 
-**Behaviors:**
-- **Draft mode** (`requireSave=true`): edits are buffered in local state; `onChange` fires only on explicit save
-- **Immediate mode** (`requireSave=false`): every edit calls `onChange` directly
-- **Multi-line paste**: pasting newline-separated values auto-creates multiple entries
-- **Add at top**: new items are prepended for better UX
+- **Draft mode** (`requireSave=true`): maintains local `draftItems` state and syncs to parent only on explicit save, preventing mid-edit prop conflicts.
+- **Multi-line paste**: splits clipboard text on newlines and inserts each line as a separate entry starting at the pasted position.
+- **Add at top**: new entries are prepended for faster access.
 
 ## Usage Example
 
 ```typescript
-<ArrayEntryManager<{ github_release_url: string }>
-  title="Release URLs"
+import { ArrayEntryManager } from './array-entry-manager';
+
+interface ReleaseUrl {
+  github_release_url: string;
+}
+
+<ArrayEntryManager<ReleaseUrl>
+  title="GitHub Release URLs"
   items={releaseUrls}
   onChange={setReleaseUrls}
   fieldKey="github_release_url"
   placeholder="https://github.com/org/repo/releases/tag/v1.0.0"
-  emptyMessage="No release URLs configured."
+  emptyMessage="No release URLs added yet."
   addButtonText="Add URL"
+  requireSave
   saveButtonText="Save URLs"
-  requireSave={true}
-  onDirtyChange={(dirty) => setHasUnsavedChanges(dirty)}
   isSaving={isSaving}
+  onDirtyChange={(dirty) => setHasUnsavedChanges(dirty)}
 />
-```
+```
+
+**Source:** [`array-entry-manager.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/array-entry-manager.tsx)

package/src/components/features/.auth-providers-list.md

@@ -1,20 +1,26 @@
-<!-- source-hash: 440c53934ab651211436b1edf3ea4fe0 -->
-A React component that renders a list of authentication provider buttons with configurable layout and divider options.
+<!-- source-hash: d7253522e7ee7bae898c156797543da4 -->
+Renders a list of SSO provider buttons with optional divider, supporting vertical and horizontal layouts. Filters and maps enabled providers to `ProviderButton` components with built-in error handling.
 
 ## Key Components
 
-- **`SSOConfigStatus`** - Interface defining provider configuration with enabled status and optional client ID
-- **`AuthProvidersList`** - Main component that renders filtered provider buttons with error handling
-- **`ProviderButton`** - Imported component for individual provider buttons
-
-## Properties
-
-- `enabledProviders` - Array of SSO provider configurations
-- `onProviderClick` - Async callback for handling provider authentication
-- `loading` - Optional loading state that disables all buttons
-- `showDivider` - Toggle for divider display (default: true)
-- `dividerText` - Custom divider text (default: "or")
-- `orientation` - Layout direction: vertical or horizontal (default: vertical)
+### `SSOConfigStatus` (exported interface)
+| Property | Type | Description |
+|---|---|---|
+| `provider` | `string` | Provider identifier (e.g. `"google"`, `"microsoft"`) |
+| `enabled` | `boolean` | Whether this provider should be rendered |
+| `clientId` | `string?` | Optional OAuth client ID |
+
+### `AuthProvidersList` (exported component)
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `enabledProviders` | `SSOConfigStatus[]` | — | List of SSO provider configs |
+| `onProviderClick` | `(provider: string) => Promise<void>` | — | Auth callback per provider |
+| `loading` | `boolean` | `false` | Disables all buttons while loading |
+| `showDivider` | `boolean` | `true` | Renders an `"or"` divider above the list |
+| `dividerText` | `string` | `"or"` | Custom divider label |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
+
+Returns `null` if `enabledProviders` is empty. Errors thrown by `onProviderClick` are caught and logged without crashing the UI.
 
 ## Usage Example
 
@@ -22,26 +28,21 @@ A React component that renders a list of authentication provider buttons with co
 import { AuthProvidersList, SSOConfigStatus } from './auth-providers-list';
 
 const providers: SSOConfigStatus[] = [
-  { provider: 'google', enabled: true, clientId: 'google-client-id' },
-  { provider: 'github', enabled: true },
-  { provider: 'microsoft', enabled: false }
+  { provider: 'google',    enabled: true,  clientId: 'abc123' },
+  { provider: 'microsoft', enabled: true,  clientId: 'def456' },
+  { provider: 'slack',     enabled: false },
 ];
 
-export function LoginForm() {
-  const handleAuth = async (provider: string) => {
-    // Implement your auth logic (OAuth redirect, etc.)
-    window.location.href = `/auth/${provider}`;
-  };
-
-  return (
-    <AuthProvidersList
-      enabledProviders={providers}
-      onProviderClick={handleAuth}
-      orientation="horizontal"
-      dividerText="or continue with"
-    />
-  );
+async function handleSignIn(provider: string) {
+  await signInWithProvider(provider); // your auth logic
 }
+
+<AuthProvidersList
+  enabledProviders={providers}
+  onProviderClick={handleSignIn}
+  orientation="horizontal"
+  dividerText="or continue with"
+/>
 ```
 
-The component automatically filters out disabled providers and includes error handling for failed authentication attempts.
+**Source:** [`auth-providers-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/auth-providers-list.tsx)

package/src/components/features/.captions-url.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 91af97ee03e3f4fa98e259bed1e212df -->
+Builds the captions API URL for a video entity, returning the HTTPS path to the `/api/captions/[entityType]/[entityId]` endpoint that serves VTT content for iOS native fullscreen subtitles.
+
+## Key Components
+
+### `getCaptionsUrl(entityType, entityId, srtContent?)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `entityType` | `string` | Entity-type discriminator for the reverse-proxied captions route |
+| `entityId` | `string \| number` | Unique identifier of the video entity |
+| `srtContent` | `string \| null \| undefined` | Raw SRT subtitle content; returns `undefined` if absent |
+
+**Returns:** `string | undefined` — A cache-busted URL of the form `/api/captions/{entityType}/{entityId}?v={hash}`, or `undefined` when no SRT content exists.
+
+**Cache-busting strategy:** The `?v=` hash is derived from the SRT content length combined with the first 8 non-whitespace characters. This forces iOS Safari to re-fetch the VTT track when subtitles are regenerated, working around Safari's aggressive `<track>` `src` caching.
+
+## Usage Example
+
+```typescript
+import { getCaptionsUrl } from './captions-url'
+
+// Returns a cache-busted captions URL
+const url = getCaptionsUrl('ticket', 42, 'WEBVTT\n\n1\n00:00:01...')
+// → '/api/captions/ticket/42?v=23-WEBVTT'
+
+// Returns undefined when no subtitles exist
+const noUrl = getCaptionsUrl('ticket', 42, null)
+// → undefined
+
+// Use in a <track> element
+const trackSrc = getCaptionsUrl(entityType, entityId, video.srt_content)
+if (trackSrc) {
+  // <track kind="subtitles" src={trackSrc} default />
+}
+```
+
+## Notes
+
+- Ported from the Flamingo hub's `lib/utils/captions-url.ts`; the hub's `VideoEnabledEntityType` enum is widened to `string` so embedders can pass any entity-type their proxied route expects.
+- VTT conversion from SRT happens server-side at the `/api/captions/...` endpoint, not in this utility.
+
+**Source:** [`lib/captions-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/lib/captions-url.ts)

package/src/components/features/.cards-strip.md

@@ -0,0 +1,48 @@
+<!-- source-hash: a95a8735a6e13b8d71845dddc72be3e2 -->
+Horizontal card-strip engine that serves as a single source of truth for marquee/chevron/seam/measure behavior across all strip surfaces. Supports two input modes: render-prop (`items` + `renderCard`) for full control, and children (organic JSX) for zero-registration card composition.
+
+## Key Components
+
+- **`CardsStrip<T>`** — Primary export. Generic component accepting either render-prop mode (Mode A) or children mode (Mode B).
+- **`ManagedCell`** — Internal cell wrapper for children mode; handles fixed widths, hover/keyboard activation, and clone a11y (`aria-hidden` + focus suppression via `useSuppressCloneFocus`).
+- **`CardStripRenderCtx`** — Context interface passed to `renderCard`; exposes activation callbacks, clone flag, touch/mobile state, and a shared near-viewport mount gate.
+- **`CardsStripProps<T>`** — XOR-discriminated union of `CardsStripEngineProps & (RenderCardMode<T> | ChildrenMode)`.
+- **`STRIP_CELL_MAX_WIDTH`** — Exported constant (`'90vw'`) shared with card components for consistent sizing.
+
+## Usage Example
+
+**Mode A — render-prop:**
+
+```typescript
+<CardsStrip
+  items={bites}
+  itemKey={(item) => item.id}
+  renderCard={(item, ctx) => (
+    <VideoBiteCard key={ctx.cardKey} bite={item} ctx={ctx} />
+  )}
+  title="Video Bites"
+  autoScrollSpeed={60}
+/>
+```
+
+**Mode B — children (organic):**
+
+```typescript
+<CardsStrip
+  title="Featured Tools"
+  cardWidthDesktop={400}
+  cardWidthMobile={320}
+  autoScroll={false}
+  showChevrons
+>
+  {tools.map((tool) => (
+    <ToolCard key={tool.id} tool={tool} />
+  ))}
+</CardsStrip>
+```
+
+> **Children mode warning:** Pass an array of elements — a single `<Fragment>` wrapping all cards becomes one giant cell. Effects and DOM IDs in children must be clone-safe when `autoScroll` is enabled.
+
+## Source
+
+[`cards-strip.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/cards-strip.tsx)