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

package/src/components/docs/.use-docs-resolve-link.md

@@ -0,0 +1,61 @@
+<!-- source-hash: 62535b1bf504403e5b6ae70e45a0f7f7 -->
+Provides a React hook that resolves relative links inside doc bodies by POSTing to a configurable endpoint, returning a `ResolveLinkResult` envelope with graceful error handling.
+
+## Key Components
+
+### `useDocsResolveLink(sourceId, resolveLinkEndpoint?)`
+
+A memoized callback hook that resolves relative hrefs found in doc content to their full navigable targets.
+
+**Parameters:**
+- `sourceId` — identifies the doc source sent in the request body
+- `resolveLinkEndpoint` *(optional)* — per-instance endpoint override; falls back to `ChatRuntime.endpoints.docsResolveLinkUrl`, then `'/api/docs/resolve-link'`
+
+**Endpoint resolution chain:**
+
+```text
+resolveLinkEndpoint prop
+  ?? ChatRuntimeProvider endpoints.docsResolveLinkUrl
+    ?? '/api/docs/resolve-link'
+```
+
+**Returned callback signature:**
+
+```typescript
+(href: string, currentPath: string) => Promise<ResolveLinkResult>
+```
+
+Returns `{ success: false, error }` on HTTP errors or network failures (DNS, CORS, offline), so callers never receive an unhandled rejection.
+
+## Usage Example
+
+```typescript
+import { useDocsResolveLink } from './use-docs-resolve-link'
+
+function DocLinkRenderer({ sourceId }: { sourceId: string }) {
+  const resolveLink = useDocsResolveLink(sourceId)
+
+  const handleLinkClick = async (href: string, currentPath: string) => {
+    const result = await resolveLink(href, currentPath)
+
+    if (!result.success) {
+      console.warn('Link resolution failed:', result.error)
+      return // render broken-link badge
+    }
+
+    // navigate to result.url or open preview
+  }
+}
+```
+
+With a custom endpoint override (per-instance configuration):
+
+```typescript
+const resolveLink = useDocsResolveLink(sourceId, '/api/custom/resolve-link')
+```
+
+## Notes
+
+- Re-memoized only when `sourceId` or the resolved endpoint changes (`useCallback` deps)
+- Non-JSON and non-`ok` responses are normalized to `{ success: false, error }` — no uncaught rejections reach the markdown renderer's click handler
+- Source: [`use-docs-resolve-link.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-docs-resolve-link.ts)

package/src/components/docs/.use-document-tree.md

@@ -0,0 +1,83 @@
+<!-- source-hash: 27cc9c9902e1357e6b671ff69f6e9cc5 -->
+Manages document tree navigation state, content fetching, and sidebar expansion for `DocViewer` components across all doc-source consumers.
+
+## Key Components
+
+### `useDocumentTree(config, initialPath?)`
+Primary hook that orchestrates structure and content loading in parallel, handles URL synchronization, and manages sidebar tree expansion state.
+
+**Config options (`UseDocumentTreeConfig`):**
+
+| Property | Type | Description |
+|---|---|---|
+| `structureEndpoint` | `string` | API endpoint for the document tree structure |
+| `contentEndpoint` | `string` | API endpoint for document content |
+| `baseRoute` | `string` | Base URL path (e.g., `'/knowledge-base'`) |
+| `folderIndexFile` | `string?` | Folder index filename (defaults to `'README.md'`) |
+
+**Returns:**
+
+| State | Type | Description |
+|---|---|---|
+| `structure` | `DocNode[]` | Full document tree |
+| `selectedPath` | `string` | Currently active document path |
+| `content` | `DocContent \| null` | Fetched document content |
+| `isLoadingStructure` | `boolean` | Structure fetch in progress |
+| `isLoadingContent` | `boolean` | Content fetch in progress |
+| `error` | `string \| null` | Error message if fetch failed |
+| `expandedNodes` | `Set<string>` | IDs of expanded sidebar nodes |
+
+### `findFirstDocPath(folder)`
+Internal helper. Depth-first search for the first non-Mermaid file in a folder. Used to auto-display content for folders without a README.
+
+### `scrollToContent()`
+Internal helper. Scrolls the `<article>` element (or document root as fallback) into view after navigation, accounting for the hub header offset.
+
+## Usage Example
+
+```typescript
+import { useDocumentTree } from './use-document-tree'
+
+function KnowledgeBaseViewer({ slug }: { slug?: string }) {
+  const {
+    structure,
+    selectedPath,
+    content,
+    isLoadingStructure,
+    isLoadingContent,
+    error,
+    expandedNodes,
+  } = useDocumentTree(
+    {
+      structureEndpoint: '/api/kb/structure',
+      contentEndpoint: '/api/kb/content',
+      baseRoute: '/knowledge-base',
+      folderIndexFile: 'README.md',
+    },
+    slug,
+  )
+
+  if (isLoadingStructure) return <Skeleton />
+  if (error) return <ErrorMessage message={error} />
+
+  return (
+    <DocViewer
+      structure={structure}
+      selectedPath={selectedPath}
+      content={content}
+      expandedNodes={expandedNodes}
+      isLoadingContent={isLoadingContent}
+    />
+  )
+}
+```
+
+## Navigation Behavior
+
+- **Parallel fetches:** Structure and a speculative content fetch fire simultaneously on mount to minimize time-to-first-content.
+- **No-README folders:** Auto-selects the first child document via `findFirstDocPath`; the sidebar remains the directory browser.
+- **Browser back/forward:** Synced via `popstate` listener.
+- **Client-side router navigation:** Synced via `cleanInitialPath` prop change (covers `history.pushState` which does not fire `popstate`).
+- **Stale fetch guard:** A `lastFetchedPath` ref prevents late in-flight responses from overwriting newer content.
+
+**Source:** [`use-document-tree.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-document-tree.ts)

package/src/components/docs/.use-scroll-spy.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 67580105f9f032b02b2f1fd926ec7677 -->
+A React hook that tracks which document section is currently visible in the viewport based on scroll position, and handles smooth navigation to sections when clicked.
+
+## Key Components
+
+### Constants
+
+- **`SCROLL_OFFSET`** (`100px`) — Unified offset value used for both scroll-target positioning and active-section detection threshold, ensuring the highlight indicator stays in sync with the clicked section's resting position.
+
+### Interfaces
+
+- **`ScrollSpySection`** — Shape of a section entry (`id`, optional `title`, optional `level`)
+- **`UseScrollSpyReturn`** — Hook return type exposing `activeSection` and `handleSectionClick`
+
+### `useScrollSpy(sections)`
+
+The primary export. Accepts an array of `ScrollSpySection` objects and returns:
+
+| Return Value | Type | Description |
+|---|---|---|
+| `activeSection` | `string` | ID of the currently visible section |
+| `handleSectionClick` | `(sectionId: string) => void` | Scrolls to the target section and pins it as active for 800ms |
+
+**Scroll detection** is throttled at 100ms via `setTimeout` to avoid excessive re-renders. The scroll listener is bypassed while a programmatic click-scroll is in progress (`isScrollingFromClick` ref guard).
+
+**Section stability** is maintained by comparing serialized IDs (`sectionIds` memo) to avoid unnecessary effect re-runs when the sections reference changes but content is identical.
+
+## Usage Example
+
+```typescript
+import { useScrollSpy } from "./use-scroll-spy"
+
+const sections = [
+  { id: "introduction", title: "Introduction", level: 1 },
+  { id: "installation", title: "Installation", level: 2 },
+  { id: "configuration", title: "Configuration", level: 2 },
+]
+
+function DocSidebar() {
+  const { activeSection, handleSectionClick } = useScrollSpy(sections)
+
+  return (
+    <nav>
+      {sections.map(section => (
+        <button
+          key={section.id}
+          onClick={() => handleSectionClick(section.id)}
+          style={{ fontWeight: activeSection === section.id ? "bold" : "normal" }}
+        >
+          {section.title}
+        </button>
+      ))}
+    </nav>
+  )
+}
+```
+
+**Source:** [`use-scroll-spy.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-scroll-spy.ts)

package/src/components/embeds/.embed-container.md

@@ -0,0 +1,45 @@
+<!-- source-hash: b283791a77bffec199910b7a53546479 -->
+Provides a base layout container and platform-specific wrapper components that enforce consistent sizing, spacing, and styling for all embedded content types (YouTube, Twitter, Reddit, LinkedIn, link previews).
+
+## Key Components
+
+### Constants & Types
+
+- **`EMBED_SIZES`** — Maps each embed type to a Tailwind `max-w-*` class, controlling the maximum width per platform context.
+- **`EmbedSize`** — Union type derived from `EMBED_SIZES` keys: `"youtube" | "twitter" | "reddit" | "linkedin" | "linkPreview"`.
+
+### Components
+
+- **`EmbedContainer`** — Base container applying shared styles: centered layout, rounded corners, card background, border, and hover shadow accent. Accepts `size`, `children`, and an optional `className`.
+- **`YouTubeContainer`** — Preset wrapper using `max-w-3xl` (768px), suited for widescreen video.
+- **`TwitterContainer`** — Preset wrapper using `max-w-md` (448px), narrow mobile-first layout.
+- **`RedditContainer`** — Preset wrapper using `max-w-xl` (576px), medium width for threads.
+- **`LinkedInContainer`** — Preset wrapper using `max-w-lg` (512px), mobile-first post layout.
+- **`LinkPreviewContainer`** — Preset wrapper using `max-w-lg` (512px), balanced card width.
+
+## Usage Example
+
+```typescript
+import {
+  YouTubeContainer,
+  LinkPreviewContainer,
+  EmbedContainer
+} from './embed-container';
+
+// Use a preset platform container
+<YouTubeContainer>
+  <iframe src="https://www.youtube-nocookie.com/embed/VIDEO_ID" />
+</YouTubeContainer>
+
+// Use a link preview container
+<LinkPreviewContainer className="my-8">
+  <LinkPreviewCard url="https://example.com" />
+</LinkPreviewContainer>
+
+// Use the base container directly with a custom size
+<EmbedContainer size="reddit" className="my-4">
+  <RedditEmbed postId="abc123" />
+</EmbedContainer>
+```
+
+> **Source:** [`embed-container.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embed-container.tsx)

package/src/components/embeds/.embed-iframe.md

@@ -0,0 +1,51 @@
+<!-- source-hash: d907992b7d3c6c815ed4b06b496e2ab0 -->
+A reusable React iframe wrapper component that handles loading state with a skeleton placeholder and prevents memory leaks during unmount or `src` changes.
+
+## Key Components
+
+### `EmbedLoadingSkeleton` (internal)
+A pulsing rectangle placeholder rendered while the iframe content loads. Uses `bg-ods-card` instead of `bg-ods-skeleton` to ensure visibility (the skeleton token resolves to transparent in this build).
+
+### `EmbedIframeProps`
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | — | URL to embed |
+| `title` | `string` | — | Accessible iframe title |
+| `height` | `string` | `calc(100vh - 250px)` | Container height (CSS value) |
+| `className` | `string` | — | Extra classes for outer container |
+| `allow` | `string` | — | iframe `allow` attribute |
+| `referrerPolicy` | `ReferrerPolicy` | — | iframe referrer policy |
+| `loading` | `'eager' \| 'lazy'` | — | iframe loading strategy |
+| `allowFullScreen` | `boolean` | — | Fullscreen permission (ignored if `allow` includes `"fullscreen"`) |
+
+### `EmbedIframe`
+The main exported component. Uses `key={src}` to force full remount on `src` change and sets `iframe.src = 'about:blank'` on cleanup to release the embedded document and avoid memory leaks.
+
+## Usage Example
+
+```typescript
+import { EmbedIframe } from './embed-iframe'
+
+export function DashboardEmbed() {
+  return (
+    <EmbedIframe
+      src="https://app.example.com/embed/dashboard"
+      title="Metrics Dashboard"
+      height="600px"
+      allow="fullscreen"
+      loading="lazy"
+      referrerPolicy="strict-origin-when-cross-origin"
+    />
+  )
+}
+```
+
+## Memory Leak Prevention
+
+Two `useEffect` hooks guard against leaks:
+1. **`src` change** — resets `isLoaded` to `false`, triggering the skeleton.
+2. **Unmount cleanup** — sets `iframe.src = 'about:blank'` inside a `try/catch` (cross-origin iframes may throw on `src` assignment).
+
+---
+
+**Source:** [`embed-iframe.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embed-iframe.tsx)

package/src/components/embeds/.figma-embed.md

@@ -0,0 +1,43 @@
+<!-- source-hash: dfed78fcee0a3efa10dad32dd26a5278 -->
+Renders an interactive Figma embed with a header bar (icon, title, "Open in Figma" link) and an iframe powered by `EmbedIframe`. Supports all Figma surface types (design files, prototypes, FigJam boards, Slides decks) and exposes a present/browse toggle exclusively for Slides URLs.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `FigmaEmbed` | Component | Primary embed component; accepts any Figma URL and renders the full embed UI |
+| `FigmaEmbedProps` | Interface | Props: `url`, `title?`, `height?`, `loading?` |
+| `SlidesViewToggle` | Internal Component | Present/Browse toggle rendered only for Figma Slides URLs |
+| `SlidesView` | Type | `'present' \| 'browse'` — controls Figma Slides viewer mode |
+
+## Usage Example
+
+```typescript
+// Inline article embed (lazy-loaded, constrained height)
+<FigmaEmbed
+  url="https://www.figma.com/design/abc123/My-Design"
+  title="Component Library"
+  height="70vh"
+/>
+
+// Data-room viewer (eager-loaded, full-viewport height)
+<FigmaEmbed
+  url="https://www.figma.com/proto/abc123/My-Prototype?node-id=1-2"
+  title="Interactive Prototype"
+  loading="eager"
+/>
+
+// Figma Slides deck — shows present/browse toggle
+<FigmaEmbed
+  url="https://www.figma.com/deck/abc123/My-Slides"
+  title="Q3 Roadmap"
+  height="60vh"
+/>
+```
+
+## Behavior Notes
+
+- **URL resolution** delegates to `toFigmaEmbedUrl` / `toFigmaOriginalUrl` / `isFigmaSlidesUrl` from `embed-url-converters` — accepts raw file, proto, board, deck, or already-resolved embed URLs.
+- **"Open in Figma"** button is suppressed if the resolved URL fails `https://figma.com` hostname validation.
+- **Slides toggle**: `present` (default) uses Figma's native full-bleed deck viewer with keyboard navigation; `browse` switches to the thumbnail-rail viewer.
+- **Empty state**: renders a centered Figma icon + message when `url` is absent or unresolvable.

package/src/components/embeds/.file-download-card.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 0befd91ec103b7f52d977c737473998b -->
+A centered card UI component that displays metadata for a downloadable file and renders a download button when a URL is available.
+
+## Key Components
+
+### `FileDownloadCard`
+The primary exported component. Renders a styled card showing:
+- **File icon** — `lucide-react` `FileText` icon as a visual indicator
+- **File name** — displays `fileName` or falls back to `"File"`
+- **MIME type** — shown only when `mimeType` is provided
+- **File size** — formatted via `formatFileSize` utility, shown only when `fileSize` is a number
+- **Download button** — rendered only when `fileUrl` is present; opens in a new tab
+
+### `FileDownloadCardProps`
+All props are optional, allowing safe render with partial data:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `fileName` | `string` | Display name of the file |
+| `mimeType` | `string` | MIME type string (e.g. `application/pdf`) |
+| `fileSize` | `number` | File size in bytes; formatted via `formatFileSize` |
+| `fileUrl` | `string` | Download URL; omitting hides the Download button |
+
+## Usage Example
+
+```typescript
+import { FileDownloadCard } from './file-download-card'
+
+// Full card with download button
+<FileDownloadCard
+  fileName="Q4-Report.pdf"
+  mimeType="application/pdf"
+  fileSize={204800}
+  fileUrl="https://cdn.example.com/Q4-Report.pdf"
+/>
+
+// Read-only card — no download button (fileUrl omitted)
+<FileDownloadCard
+  fileName="Pending-Upload.xlsx"
+  mimeType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+  fileSize={51200}
+/>
+```
+
+> This component is the default renderer for `file`-type documents in `<DocsHubPage>`. Override it by passing a custom `file` renderer to `documentTypeRenderers`.
+
+**Source:** [`file-download-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/file-download-card.tsx)

package/src/components/embeds/.google-sheets-viewer.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 7fe71b372dd2b4fea0e2accc89c5d273 -->
+A React client component that renders an embedded Google Sheets viewer with a header bar and an external link button.
+
+## Key Components
+
+### `GoogleSheetsViewerProps`
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `externalUrl` | `string` | ✅ | Google Sheets URL (standard or embed format) |
+| `fileName` | `string` | ❌ | Display name shown in the header; defaults to `"Google Sheet"` |
+| `height` | `string` | ❌ | Iframe height passed to `EmbedIframe` |
+
+### `GoogleSheetsViewer`
+Main exported component. Handles two render states:
+- **Empty state** — renders a centered icon and message when `externalUrl` is falsy
+- **Viewer state** — renders a header row (icon + title + open-in-Sheets button) above an `EmbedIframe`
+
+URL conversion is delegated to two utility helpers:
+- `toGoogleSheetsEmbedUrl` — converts the URL to the `/pub?output=html` embed format for the iframe
+- `toGoogleSheetsOriginalUrl` — normalises the URL back to the standard `docs.google.com/spreadsheets` form for the external link
+
+## Usage Example
+
+```typescript
+import { GoogleSheetsViewer } from '@/components/viewers/google-sheets-viewer'
+
+export default function ReportPage() {
+  return (
+    <GoogleSheetsViewer
+      externalUrl="https://docs.google.com/spreadsheets/d/SHEET_ID/edit"
+      fileName="Q3 Budget Report"
+      height="600px"
+    />
+  )
+}
+```
+
+## Source
+
+[`google-sheets-viewer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/google-sheets-viewer.tsx)

package/src/components/embeds/.index.md

@@ -0,0 +1,58 @@
+<!-- source-hash: c38e7dc463f7a5e6d0be8699a0c2f7db -->
+Public API barrel for the rich-markdown embed component library, re-exporting all embed components, their prop types, container primitives, and the shared runtime context from their respective modules.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `EmbedIframe` | Generic iframe wrapper for arbitrary URL embeds |
+| `PdfViewer` | In-browser PDF rendering component |
+| `GoogleSheetsViewer` | Embedded Google Sheets viewer |
+| `FigmaEmbed` | Figma design file embed |
+| `OGLinkPreview` / `OGLinkErrorBoundary` | Open Graph link preview card with error boundary |
+| `FileDownloadCard` | Downloadable file attachment card |
+| `RedditEmbedClient` | Reddit post/thread embed (satellite) |
+| `TwitterEmbedClient` | Twitter/X post embed (satellite) |
+| `LinkedInEmbedClient` | LinkedIn post embed (satellite) |
+| `MarkdownImage` | Image component used within markdown rendering |
+| `EmbedContainer` / `*Container` | Layout wrappers (`YouTubeContainer`, `TwitterContainer`, etc.) with `EMBED_SIZES` presets |
+| `RichMarkdownRuntimeProvider` / `useRichMarkdownRuntime` | React context provider sharing proxy endpoints and image transformer config across all embed components |
+
+## Usage Example
+
+```typescript
+// Full renderer usage — wrap once at the app boundary
+import {
+  RichMarkdownRuntimeProvider,
+  RedditEmbedClient,
+  OGLinkPreview,
+  EMBED_SIZES,
+} from '@openframe/embed-components'
+
+function App() {
+  return (
+    <RichMarkdownRuntimeProvider
+      proxyEndpoint="/api/proxy"
+      imageTransformer={(url) => `/cdn?url=${encodeURIComponent(url)}`}
+    >
+      <MyPage />
+    </RichMarkdownRuntimeProvider>
+  )
+}
+
+// Composing a satellite embed outside the markdown renderer
+function ReleasePage() {
+  return (
+    <RedditEmbedClient
+      postUrl="https://reddit.com/r/msp/comments/example"
+      size={EMBED_SIZES.medium}
+    />
+  )
+}
+```
+
+> **Satellite embeds** (`Reddit`, `Twitter`, `LinkedIn`) are also wired into `<RichMarkdownRenderer>` internally. When mounting them standalone, wrap with `RichMarkdownRuntimeProvider` only if you need to override proxy or image transformer defaults.
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

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

@@ -0,0 +1,50 @@
+<!-- source-hash: fdf1dfbbf12ccb22608a2cd3f5dcf58c -->
+Client-side React component that renders LinkedIn post embeds as iframes, with URL/URN normalization and graceful fallback handling when a post URL cannot be resolved to an embeddable URN.
+
+## Key Components
+
+### `toLinkedInEmbedUrl(url: string): string`
+Internal utility that normalizes any LinkedIn post URL or URN into LinkedIn's official embed endpoint (`/embed/feed/update/<urn>`). Handles four input patterns:
+- Already-canonical embed URLs
+- Explicit URNs (`urn:li:activity|share|ugcPost:<id>`)
+- Activity IDs embedded in URL slugs (`activity-<id>`)
+- Numeric IDs (15–25 digits) at the end of post URLs
+
+Returns `''` when no URN can be derived, signaling the component to render a fallback card.
+
+### `LinkedInEmbedClient`
+The primary exported component. Accepts a `url` string and optional `height` (default `600px`). Renders one of two states:
+
+| State | Condition | Output |
+|---|---|---|
+| Fallback card | `embedUrl` is empty | Static card with a "View on LinkedIn" link |
+| Embed view | Valid embed URL | Skeleton loader → iframe + external link footer |
+
+## Usage Example
+
+```typescript
+import { LinkedInEmbedClient } from './linkedin-embed-client';
+
+// From a standard post URL
+<LinkedInEmbedClient
+  url="https://www.linkedin.com/posts/example-company_post-title-activity-1234567890123456789-AbCd"
+  height={500}
+/>
+
+// From an explicit URN
+<LinkedInEmbedClient
+  url="urn:li:activity:1234567890123456789"
+/>
+
+// Falls back to a link card if the URL cannot be resolved
+<LinkedInEmbedClient
+  url="https://www.linkedin.com/company/some-page"
+/>
+```
+
+## Notes
+
+- Uses `useMemo` to avoid re-computing the embed URL on every render.
+- The skeleton loader (animated pulse) is shown until the iframe fires `onLoad`.
+- LinkedIn iframes do not support auto-resizing; height must be set explicitly via the `height` prop.
+- All external links use `rel="noopener noreferrer"` for security.

package/src/components/embeds/.markdown-image.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 0ce5f81d0a9d025580e28ea3daa0fb7b -->
+Renders markdown images with correct aspect ratios and size constraints inside rich markdown articles, using a lightweight probe to detect intrinsic dimensions before displaying the full image.
+
+## Key Components
+
+### `MarkdownImage({ src, alt })`
+The primary export. A client component that:
+- **Probes** the image at 48px via `transformImageSrc` to determine the true width/height ratio before fetching the full image
+- **Renders a skeleton placeholder** (`animate-pulse`) while the probe is in-flight, preventing layout jumps
+- **Passes `object-contain`** to the underlying image shim so Supabase's loader uses `resize=contain` (never crops)
+- **Caps display size** at `32rem` tall while maintaining the real aspect ratio — wide images fill the column, tall screenshots don't dominate the page
+
+### Constants
+| Name | Value | Purpose |
+|---|---|---|
+| `MAX_H_REM` | `32` | On-page height cap (~512px) |
+| `DISPLAY_W` | `768` | Logical width hint for srcset generation |
+
+### Dependencies
+- **`useRichMarkdownRuntime`** — supplies `transformImageSrc`, which adapts image URLs for the active optimizer (Supabase on the hub, identity passthrough elsewhere)
+- **`Image` shim** (`embed-shims/next-image`) — full Next.js Image Optimization on the hub, plain `<img>` in other embedders
+
+## Usage Example
+
+```typescript
+// Used automatically by the markdown renderer; not typically called directly.
+// The rich markdown runtime must be provided by an ancestor RichMarkdownRuntimeProvider.
+import { MarkdownImage } from './markdown-image';
+
+// Inside a markdown component map:
+const components = {
+  img: ({ src, alt }: { src: string; alt?: string }) => (
+    <MarkdownImage src={src} alt={alt} />
+  ),
+};
+```
+
+> **Note:** `transformImageSrc` is optional — embedders that omit it receive an identity fallback, so the raw `src` is used for both the probe and display copy.
+
+**Source:** [`markdown-image.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/markdown-image.tsx)

package/src/components/embeds/.og-link-preview.md

@@ -0,0 +1,54 @@
+<!-- source-hash: ca37d68e797966a1bd0503fa8f95bb97 -->
+Renders an Open-Graph link preview card by fetching OG metadata from a configurable scrape endpoint, resolving images through a multi-step fallback chain, and displaying either a compact horizontal or default vertical card layout.
+
+## Key Components
+
+### `OGData` (interface)
+Defines the expected JSON shape returned by the OG scrape endpoint (`/api/og-scraper` by default). Fields include `title`, `description`, `image`, `originalImage`, `url`, `siteName`, `type`, and `favicon`.
+
+### `OGLinkErrorBoundary` (class component)
+A React error boundary scoped to link previews. Catches rendering errors silently and renders a `fallback` prop (typically a plain `<a>` tag) to prevent a broken third-party preview from crashing the parent view. Named distinctly to avoid export collision with the lib's `features/error-boundary`.
+
+### `BuildPlaceholderUrl` (type)
+Callback signature `(title, siteName) => string | null` for generating a placeholder image URL when scraping returns no image. The hub injects its own implementation; embedders can omit this to disable placeholder generation entirely.
+
+### `OGLinkPreview` (React FC)
+Main card component. Key behaviors:
+- **URL validation** — rejects malformed URLs, `localhost`, and RFC1918 ranges without a network request, rendering a plain link instead.
+- **OG fetch** — `GET {apiBaseUrl}{ogEndpointPath}?url=<encoded>` with configurable base and path for cross-origin embed contexts.
+- **Image resolution** — cascades through `og:image` → `originalImage` → `fallbackImage` prop → `buildPlaceholderUrl` result, with per-source error toggles.
+- **Edge color extraction** — calls `useImageEdgeColor` on the resolved image for a letterbox background tint.
+- **Variants** — `compact` (horizontal, 120px) or `default` (vertical with `aspect-video` hero).
+
+### Internal helpers
+- `getDomain` / `domainToTitle` — extract and humanize a hostname for graceful error fallback display.
+- `ExternalLinkIcon` / `Favicon` — small presentational components used inside the card.
+
+## Usage Example
+
+```typescript
+import { OGLinkPreview, OGLinkErrorBoundary } from './og-link-preview'
+
+// Default vertical card (hub / same-origin)
+<OGLinkErrorBoundary fallback={<a href={url}>{url}</a>}>
+  <OGLinkPreview
+    url="https://techcrunch.com/some-article"
+    buildPlaceholderUrl={(title, siteName) =>
+      `/api/og-placeholder?title=${encodeURIComponent(title)}&site=${encodeURIComponent(siteName)}`
+    }
+  />
+</OGLinkErrorBoundary>
+
+// Compact card from an embed context pointing at the hub
+<OGLinkPreview
+  url="https://example.com/press-release"
+  apiBaseUrl="https://hub.example.com"
+  ogEndpointPath="/api/og-scraper"
+  variant="compact"
+  fallbackTitle="Example Press Release"
+  fallbackImage="https://cdn.example.com/hero.jpg"
+  enablePlaceholder={false}
+/>
+```
+
+**Source:** [`og-link-preview.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/og-link-preview.tsx)