@flamingo-stack/openframe-frontend-core 0.0.295 → 0.0.296-snapshot.20260621021605

package/src/components/docs/docs-hub-page.tsx

@@ -0,0 +1,149 @@
+import React from 'react'
+import { DocViewer, type DocViewerProps } from './doc-viewer'
+import { MarkdownSkeleton, EmbedSkeleton } from './skeletons'
+import { PdfViewer } from '../embeds/pdf-viewer'
+import { GoogleSheetsViewer } from '../embeds/google-sheets-viewer'
+import { FigmaEmbed } from '../embeds/figma-embed'
+import { FileDownloadCard } from '../embeds/file-download-card'
+import type {
+  DocContent,
+  DocRenderHandlers,
+  DocumentType,
+} from '../../types/doc-source'
+
+type DocRenderer = (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode
+
+/**
+ * Per-document-type renderer map. `markdown` is required (the lib does NOT
+ * ship a default markdown renderer — embedders pick their own library +
+ * sanitization to avoid an XSS surface in the lib).
+ *
+ * `pdf` / `google_sheet` / `figma` / `file` are optional — the lib provides
+ * defaults from `components/embeds`. Override only when you want different
+ * props than the default (e.g. a custom PDF toolbar, embedded credentials).
+ */
+export type DocumentTypeRenderers = { markdown: DocRenderer } & Partial<
+  Record<DocumentType, DocRenderer>
+>
+
+export interface DocsHubPageProps
+  extends Omit<DocViewerProps, 'renderContent' | 'renderSkeleton' | 'showAIChat'> {
+  /** Per-document-type renderer map. `markdown` is REQUIRED. */
+  documentTypeRenderers: DocumentTypeRenderers
+
+  /** Renderer for unknown / future document types. Defaults to a lib-styled
+   *  "Unsupported document type" message. */
+  fallbackRenderer?: DocRenderer
+
+  /** Loading skeleton picker. Defaults: `markdown` / `undefined` →
+   *  `<MarkdownSkeleton>`, everything else → `<EmbedSkeleton>`. */
+  renderSkeleton?: (documentType: DocumentType | undefined) => React.ReactNode
+
+  /** Defaults to `true` (the embeddable wrapper favors the chat-enabled
+   *  experience). Only mounts the in-source RAG search bar
+   *  (`<DocSearchBar>`) — does NOT require `ChatRuntimeContext`. */
+  showAIChat?: boolean
+}
+
+const DEFAULT_TITLE = 'Documents'
+
+const defaultFallbackRenderer: DocRenderer = () => (
+  <div className="text-center py-16">
+    <p className="text-ods-text-secondary">Unsupported document type</p>
+  </div>
+)
+
+// When the DAL hasn't populated the URL field for a rich-content type, the
+// embed-viewer components render a broken iframe (empty src). Fall back to
+// the same lib-styled "Unsupported document type" panel the explicit
+// fallback uses — the surface is honest about the missing data instead of
+// pretending to load. `FileDownloadCard` handles its own missing-URL state
+// (hides the Download button), so it doesn't need this guard.
+const defaultPdfRenderer: DocRenderer = (content, handlers) =>
+  content.fileUrl ? (
+    <PdfViewer src={content.fileUrl} fileName={content.fileName} />
+  ) : (
+    defaultFallbackRenderer(content, handlers)
+  )
+
+const defaultGoogleSheetRenderer: DocRenderer = (content, handlers) =>
+  content.externalUrl ? (
+    <GoogleSheetsViewer externalUrl={content.externalUrl} fileName={content.fileName} />
+  ) : (
+    defaultFallbackRenderer(content, handlers)
+  )
+
+const defaultFigmaRenderer: DocRenderer = (content, handlers) =>
+  content.externalUrl ? (
+    <FigmaEmbed url={content.externalUrl} title={content.fileName} loading="eager" />
+  ) : (
+    defaultFallbackRenderer(content, handlers)
+  )
+
+const defaultFileRenderer: DocRenderer = (content) => (
+  <FileDownloadCard
+    fileName={content.fileName}
+    mimeType={content.mimeType}
+    fileSize={content.fileSize}
+    fileUrl={content.fileUrl}
+  />
+)
+
+const defaultRenderSkeleton = (documentType: DocumentType | undefined) =>
+  !documentType || documentType === 'markdown' ? (
+    <MarkdownSkeleton />
+  ) : (
+    // Forward the documentType so the embed skeleton renders the right
+    // shape (PDF=2 buttons, sheets/figma=1 button, file=centered card).
+    <EmbedSkeleton documentType={documentType} />
+  )
+
+/**
+ * Embeddable docs-hub page. Bundles `<DocViewer>` with safe defaults so the
+ * minimum embed is a one-line mount (consumer only has to supply
+ * `documentTypeRenderers.markdown`).
+ *
+ * Used by the hub at `/knowledge-base` and `/data-room`, and by third-party
+ * React apps that embed the docs experience behind their own proxy. See
+ * `docs/EMBEDDING_DOCS_HUB.md` for the embedder setup.
+ *
+ * SEO note: this component is `'use client'` (via the docs barrel) — server-
+ * side SEO is the host's responsibility. The hub's `<DocSeoContent>` is the
+ * canonical implementation embedders can reference.
+ */
+export function DocsHubPage({
+  title = DEFAULT_TITLE,
+  documentTypeRenderers,
+  fallbackRenderer = defaultFallbackRenderer,
+  renderSkeleton = defaultRenderSkeleton,
+  showAIChat = true,
+  className = 'min-h-screen',
+  sidebarLabel = 'DOCUMENTATION',
+  ...docViewerProps
+}: DocsHubPageProps) {
+  const resolvedRenderers: DocumentTypeRenderers = {
+    markdown: documentTypeRenderers.markdown,
+    pdf: documentTypeRenderers.pdf ?? defaultPdfRenderer,
+    google_sheet: documentTypeRenderers.google_sheet ?? defaultGoogleSheetRenderer,
+    figma: documentTypeRenderers.figma ?? defaultFigmaRenderer,
+    file: documentTypeRenderers.file ?? defaultFileRenderer,
+  }
+
+  const renderContent: DocViewerProps['renderContent'] = (content, handlers) => {
+    const type = (content.documentType ?? 'markdown') as DocumentType
+    const renderer = resolvedRenderers[type] ?? fallbackRenderer
+    return renderer(content, handlers)
+  }
+
+  return (
+    <DocViewer
+      {...docViewerProps}
+      title={title}
+      showAIChat={showAIChat}
+      className={className}
+      sidebarLabel={sidebarLabel}
+      renderContent={renderContent}
+      renderSkeleton={renderSkeleton}
+    />
+  )
+}

package/src/components/docs/index.ts

@@ -3,6 +3,11 @@
 export { DocViewer } from './doc-viewer'
 export type { DocViewerProps } from './doc-viewer'
 
+export { DocsHubPage } from './docs-hub-page'
+export type { DocsHubPageProps, DocumentTypeRenderers } from './docs-hub-page'
+
+export { MarkdownSkeleton, EmbedSkeleton } from './skeletons'
+
 export { useDocumentTree } from './use-document-tree'
 export type { UseDocumentTreeConfig } from './use-document-tree'
 
@@ -10,3 +15,15 @@ export { useScrollSpy } from './use-scroll-spy'
 
 export { DocNavigationProvider, useDocNavigation } from './doc-navigation-context'
 export type { DocNavigator } from './doc-navigation-context'
+
+// Re-export the doc-source types embedders need to implement the
+// `/api/docs/sources/[sourceId]/{structure,content}` + `/api/docs/resolve-link`
+// API contract.
+export type {
+  DocNode,
+  DocContent,
+  DocRenderHandlers,
+  DocSourceId,
+  DocumentType,
+  ResolveLinkResult,
+} from '../../types/doc-source'

package/src/components/docs/skeletons.tsx

@@ -0,0 +1,138 @@
+import React from 'react'
+
+/**
+ * Text-style skeleton — matches a rendered markdown article layout.
+ * Used by `<DocsHubPage>` as the default for `markdown` (and unknown
+ * document types). Embedders can override via `renderSkeleton`.
+ */
+export function MarkdownSkeleton() {
+  return (
+    <div className="space-y-7 mt-6">
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-3/4 animate-pulse" />
+      </div>
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-5/6 animate-pulse" />
+      </div>
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-2/3 animate-pulse" />
+      </div>
+      <div className="h-[88px] bg-ods-card border border-ods-border rounded-lg animate-pulse" />
+      <div className="h-7 bg-ods-border rounded w-1/3 animate-pulse" />
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-[72%] animate-pulse" />
+      </div>
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-[58%] animate-pulse" />
+      </div>
+      <div className="h-7 bg-ods-border rounded w-2/5 animate-pulse" />
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-[90%] animate-pulse" />
+      </div>
+      <div className="space-y-[14px]">
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-full animate-pulse" />
+        <div className="h-[16px] bg-ods-border rounded w-[70%] animate-pulse" />
+      </div>
+      <div className="h-[88px] bg-ods-card border border-ods-border rounded-lg animate-pulse" />
+    </div>
+  )
+}
+
+/**
+ * Embed-style skeleton — matches the iframe loading state for `pdf`,
+ * `google_sheet`, `figma`, and `file` document types. Used by
+ * `<DocsHubPage>` as the default for non-markdown documentTypes.
+ *
+ * The skeleton is documentType-aware so its layout matches the actual
+ * viewer that will replace it:
+ *   - `pdf`                  → header with title + TWO buttons (Preview, Download)
+ *   - `google_sheet`/`figma` → header with title + ONE button/toggle
+ *   - `file`                 → centered FileDownloadCard-style box
+ *   - undefined / others     → generic (1-button header)
+ *
+ * IMPORTANT: bars use `bg-ods-border` (NOT `bg-ods-skeleton`). The
+ * `--ods-skeleton` token resolves to TRANSPARENT in this build, leaving
+ * the skeleton box visually empty — the embed skeleton was the loudest
+ * surface affected (a full-height iframe area showing nothing). Same fix
+ * the chat-message-row skeleton already documents in its inline comment.
+ */
+export interface EmbedSkeletonProps {
+  /** When provided, the header layout matches the eventual viewer's
+   *  button count + arrangement, so the layout doesn't shift on load. */
+  documentType?: 'pdf' | 'google_sheet' | 'figma' | 'file' | string
+}
+
+export function EmbedSkeleton({ documentType }: EmbedSkeletonProps = {}) {
+  // Centered card shape for the `file` documentType — matches
+  // `<FileDownloadCard>`'s `flex flex-col items-center justify-center py-16`
+  // + bordered card with icon, name, type/size row, Download button.
+  if (documentType === 'file') {
+    return (
+      <div className="flex flex-col items-center justify-center py-16">
+        <div className="bg-ods-card border border-ods-border rounded-xl p-8 max-w-md w-full text-center space-y-4">
+          <div className="w-16 h-16 rounded mx-auto bg-ods-border animate-pulse" />
+          <div className="space-y-2">
+            <div className="h-5 w-2/3 mx-auto rounded bg-ods-border animate-pulse" />
+            <div className="h-4 w-1/2 mx-auto rounded bg-ods-border animate-pulse" />
+          </div>
+          <div className="h-10 w-full rounded bg-ods-border animate-pulse" />
+        </div>
+      </div>
+    )
+  }
+
+  // PDF viewer has TWO buttons (Preview + Download); Sheets / Figma
+  // render ONE (Open / view-toggle). Default to one for unknown types.
+  const buttonCount = documentType === 'pdf' ? 2 : 1
+
+  return (
+    <div className="space-y-4">
+      {/* Header — matches the actual viewer's
+       *  `flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between`
+       *  (mobile-stacked, desktop-row). */}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        {/* Left: icon + title */}
+        <div className="flex items-center gap-2 min-w-0 flex-1">
+          <div className="w-5 h-5 shrink-0 rounded bg-ods-border animate-pulse" />
+          <div className="h-6 w-2/3 rounded bg-ods-border animate-pulse" />
+        </div>
+        {/* Right: 1 or 2 buttons. Mobile = full-width; desktop = auto. */}
+        <div className="flex items-center gap-2 w-full sm:w-auto">
+          {Array.from({ length: buttonCount }).map((_, i) => (
+            <div
+              key={i}
+              className="h-10 w-full sm:w-32 rounded bg-ods-border animate-pulse flex-1 sm:flex-initial"
+            />
+          ))}
+        </div>
+      </div>
+      {/* Body — clean iframe-sized rectangle, no fake inner placeholder
+       *  cruft. Matches the viewer's default `calc(100vh - 250px)` height. */}
+      <div
+        className="w-full rounded-lg border border-ods-border bg-ods-card animate-pulse"
+        style={{ height: 'calc(100vh - 250px)' }}
+      />
+    </div>
+  )
+}

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

@@ -0,0 +1,52 @@
+import { useCallback } from 'react'
+import { useChatRuntime } from '../../contexts/chat-runtime-context'
+import type { ResolveLinkResult } from '../../types/doc-source'
+
+/**
+ * `useDocsResolveLink(sourceId, override?)` — POST `/api/docs/resolve-link`
+ * (or the override / `ChatRuntime.endpoints.docsResolveLinkUrl`) for a
+ * relative href inside a doc body, returning a `ResolveLinkResult`
+ * envelope.
+ *
+ * The endpoint chain (`override ?? runtime.endpoints.docsResolveLinkUrl
+ * ?? '/api/docs/resolve-link'`) mirrors `searchEndpoint` resolution in
+ * `<DocViewer>` so embedders configure both the same way: per-instance
+ * prop OR ambient `ChatRuntimeProvider`.
+ *
+ * The full fetch + JSON-parse pipeline is wrapped in try/catch so a
+ * network throw (DNS / CORS / offline) or a non-JSON response surfaces
+ * as `{ success: false, error }` — the markdown renderer's broken-link
+ * badge handles that branch instead of swallowing an unhandled rejection
+ * past the click handler.
+ */
+export function useDocsResolveLink(
+  sourceId: string,
+  resolveLinkEndpoint?: string | null,
+) {
+  const chatRuntime = useChatRuntime()
+  const resolvedResolveLinkEndpoint =
+    resolveLinkEndpoint ?? chatRuntime?.endpoints.docsResolveLinkUrl ?? '/api/docs/resolve-link'
+
+  return useCallback(
+    async (href: string, currentPath: string): Promise<ResolveLinkResult> => {
+      try {
+        const response = await fetch(resolvedResolveLinkEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ link: href, currentPath, source: sourceId }),
+        })
+        if (!response.ok) {
+          return { success: false, error: `Resolve failed: ${response.status}` }
+        }
+        const json = await response.json()
+        return (json.data ?? json) as ResolveLinkResult
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Resolve failed',
+        }
+      }
+    },
+    [resolvedResolveLinkEndpoint, sourceId],
+  )
+}

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

@@ -102,6 +102,27 @@ export function useDocumentTree(
     return () => window.removeEventListener('popstate', handlePopState)
   }, [normalizedBaseRoute, folderIndexFile])
 
+  // External-URL → state sync. The popstate listener above catches browser
+  // back/forward, but client-side routers (react-router, Next App Router…)
+  // change the URL via `history.pushState` which does NOT fire popstate.
+  // The host re-renders the viewer with a new `initialPath` prop instead, so
+  // we mirror the popstate logic here against the (memoized) `cleanInitialPath`.
+  // Without this, a chat-card click that soft-navigates via react-router
+  // updates the URL but the viewer stays on the previously-selected doc.
+  useEffect(() => {
+    if (cleanInitialPath === selectedPathRef.current) return
+    setSelectedPath(cleanInitialPath)
+    if (cleanInitialPath) {
+      const parentPath = cleanInitialPath.includes('/')
+        ? cleanInitialPath.substring(0, cleanInitialPath.lastIndexOf('/'))
+        : cleanInitialPath
+      setExpandedNodes(new Set(getDocAncestorNodeIds(parentPath)))
+    }
+    // Match popstate's scroll-to-content delay; the targeted content fetch
+    // dispatched by the selectedPath effect lands before this fires.
+    setTimeout(scrollToContent, 150)
+  }, [cleanInitialPath])
+
   useEffect(() => {
     if (!isInitialized) {
       // Kick off the speculative content fetch IN PARALLEL with the structure

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

@@ -0,0 +1,80 @@
+import React from 'react';
+import { cn } from '../../utils/cn';
+
+// Base container sizes for different embed types
+export const EMBED_SIZES = {
+  youtube: 'max-w-3xl',    // 768px - Video content needs more space
+  twitter: 'max-w-md',     // 448px - Narrow tweets, mobile-first
+  reddit: 'max-w-xl',      // 576px - Medium width for discussion threads
+  linkedin: 'max-w-lg',    // 512px - LinkedIn post embed, mobile-first
+  linkPreview: 'max-w-lg'  // 512px - Balanced width for cards
+} as const;
+
+export type EmbedSize = keyof typeof EMBED_SIZES;
+
+interface EmbedContainerProps {
+  size: EmbedSize;
+  children: React.ReactNode;
+  className?: string;
+}
+
+// Base container for all embeds
+export function EmbedContainer({
+  size,
+  children,
+  className = ""
+}: EmbedContainerProps) {
+  return (
+    <div className={cn(
+      "mx-auto rounded-lg overflow-hidden",
+      "bg-ods-card border border-ods-border",
+      "transition-all duration-200 ease-in-out",
+      "hover:border-ods-accent/30 hover:shadow-lg hover:shadow-ods-accent/10",
+      EMBED_SIZES[size],
+      className
+    )}>
+      {children}
+    </div>
+  );
+}
+
+// Specific containers for each platform
+export function YouTubeContainer({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <EmbedContainer size="youtube" className={cn("my-6", className)}>
+      {children}
+    </EmbedContainer>
+  );
+}
+
+export function TwitterContainer({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <EmbedContainer size="twitter" className={cn("my-6", className)}>
+      {children}
+    </EmbedContainer>
+  );
+}
+
+export function RedditContainer({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <EmbedContainer size="reddit" className={cn("my-6", className)}>
+      {children}
+    </EmbedContainer>
+  );
+}
+
+export function LinkPreviewContainer({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <EmbedContainer size="linkPreview" className={cn("my-6", className)}>
+      {children}
+    </EmbedContainer>
+  );
+}
+
+export function LinkedInContainer({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <EmbedContainer size="linkedin" className={cn("my-6", className)}>
+      {children}
+    </EmbedContainer>
+  );
+}

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

@@ -2,19 +2,17 @@
 
 import React, { useState, useCallback, useRef, useEffect } from 'react'
 
-/** Loading skeleton for iframe embeds — matches project skeleton pattern */
+/** Loading skeleton for iframe embeds — clean iframe-sized rectangle.
+ *  Uses `bg-ods-card` (visible token) rather than `bg-ods-skeleton`
+ *  which resolves to transparent in this build (the same gotcha
+ *  documented in `chat-message-row.tsx`'s skeleton). No fake inner
+ *  placeholder cruft — a real loading iframe shows a blank rectangle. */
 function EmbedLoadingSkeleton({ height }: { height?: string }) {
   return (
     <div
-      className="w-full rounded-lg border border-ods-border overflow-hidden bg-ods-skeleton animate-pulse"
+      className="w-full rounded-lg border border-ods-border overflow-hidden bg-ods-card animate-pulse"
       style={{ height: height || 'calc(100vh - 250px)' }}
-    >
-      <div className="flex flex-col items-center justify-center h-full gap-4">
-        <div className="w-12 h-12 rounded-lg bg-ods-card" />
-        <div className="h-4 w-48 rounded bg-ods-card" />
-        <div className="h-3 w-32 rounded bg-ods-card" />
-      </div>
-    </div>
+    />
   )
 }
 

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

@@ -0,0 +1,54 @@
+import React from 'react'
+import { Button } from '../ui'
+import { FileText, Download } from 'lucide-react'
+import { formatFileSize } from '../../utils'
+
+export interface FileDownloadCardProps {
+  fileName?: string
+  mimeType?: string
+  fileSize?: number
+  fileUrl?: string
+}
+
+/**
+ * Generic downloadable-file card for the `file` document type. Used by
+ * `<DocsHubPage>`'s default `documentTypeRenderers.file`. Embedders can
+ * override the default by passing their own `file` renderer.
+ *
+ * When `fileUrl` is missing, the Download button is omitted (the card still
+ * renders the filename + type + size so the user knows what they were
+ * about to download).
+ */
+export function FileDownloadCard({
+  fileName,
+  mimeType,
+  fileSize,
+  fileUrl,
+}: FileDownloadCardProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-16">
+      <div className="bg-ods-card border border-ods-border rounded-xl p-8 max-w-md w-full text-center space-y-4">
+        <FileText className="w-16 h-16 text-ods-text-secondary mx-auto" />
+        <div>
+          <h3 className="text-lg font-semibold text-ods-text-primary">
+            {fileName || 'File'}
+          </h3>
+          <div className="flex items-center justify-center gap-3 mt-2 text-sm text-ods-text-secondary">
+            {mimeType && <span>{mimeType}</span>}
+            {typeof fileSize === 'number' && <span>{formatFileSize(fileSize)}</span>}
+          </div>
+        </div>
+        {fileUrl && (
+          <Button
+            variant="accent"
+            href={fileUrl}
+            openInNewTab
+            leftIcon={<Download className="w-4 h-4" />}
+          >
+            Download File
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/embeds/index.ts

@@ -16,3 +16,33 @@ export type {
   OGData,
   BuildPlaceholderUrl,
 } from './og-link-preview'
+
+export { FileDownloadCard } from './file-download-card'
+export type { FileDownloadCardProps } from './file-download-card'
+
+// Satellite embeds wired into `<RichMarkdownRenderer>` (`components/ui`).
+// Exported individually so embedders can compose them outside the renderer
+// (e.g. a release page that wants a single reddit card without parsing
+// markdown). The runtime knobs (proxy endpoints, image transformer) are
+// shared via `RichMarkdownRuntimeProvider` — call sites that mount a
+// satellite directly should wrap with the provider when they need
+// overrides; otherwise the defaults match the hub's existing endpoints.
+export { RedditEmbedClient } from './reddit-embed-client'
+export { TwitterEmbedClient } from './twitter-embed-client'
+export { LinkedInEmbedClient } from './linkedin-embed-client'
+export { MarkdownImage } from './markdown-image'
+export {
+  EmbedContainer,
+  YouTubeContainer,
+  TwitterContainer,
+  RedditContainer,
+  LinkPreviewContainer,
+  LinkedInContainer,
+  EMBED_SIZES,
+  type EmbedSize,
+} from './embed-container'
+export {
+  RichMarkdownRuntimeProvider,
+  useRichMarkdownRuntime,
+  type RichMarkdownRuntime,
+} from './rich-markdown-runtime'