@flamingo-stack/openframe-frontend-core 0.0.296 → 0.0.297

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'

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

@@ -0,0 +1,100 @@
+"use client";
+
+import { useMemo, useState } from 'react';
+import { LinkedInContainer } from './embed-container';
+import { LinkedinIcon } from '../icons-v2-generated/brand-logos/linkedin-icon';
+import { ExternalLink } from 'lucide-react';
+
+/**
+ * Derive LinkedIn's official embed URL from any post URL or URN.
+ * LinkedIn renders public posts at /embed/feed/update/<urn>. Returns '' when no
+ * URN can be derived, so the component falls back to a link instead of a broken
+ * (X-Frame-blocked) iframe.
+ */
+function toLinkedInEmbedUrl(url: string): string {
+  if (!url) return '';
+  if (url.includes('linkedin.com/embed/')) return url.split('?')[0];
+  let m = url.match(/urn:li:(activity|share|ugcPost):(\d+)/i);
+  if (m) return `https://www.linkedin.com/embed/feed/update/urn:li:${m[1]}:${m[2]}`;
+  m = url.match(/activity[-:](\d{15,25})/i);
+  if (m) return `https://www.linkedin.com/embed/feed/update/urn:li:activity:${m[1]}`;
+  m = url.match(/-(\d{15,25})(?:-[A-Za-z0-9_-]+)?\/?(?:\?.*)?$/);
+  if (m) return `https://www.linkedin.com/embed/feed/update/urn:li:activity:${m[1]}`;
+  return '';
+}
+
+interface LinkedInEmbedProps {
+  url: string;
+  /** Fixed iframe height — LinkedIn embeds don't auto-resize. */
+  height?: number;
+}
+
+export function LinkedInEmbedClient({ url, height = 600 }: LinkedInEmbedProps) {
+  const embedUrl = useMemo(() => toLinkedInEmbedUrl(url), [url]);
+  const [loaded, setLoaded] = useState(false);
+
+  // No derivable URN → graceful fallback card with a link (mirrors reddit's error state)
+  if (!embedUrl) {
+    return (
+      <LinkedInContainer>
+        <div className="p-6">
+          <div className="flex items-center space-x-3 text-ods-text-secondary mb-4">
+            <LinkedinIcon className="w-5 h-5 shrink-0" />
+            <span>LinkedIn post</span>
+          </div>
+          <a
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center space-x-2 px-4 py-2 bg-ods-card border border-ods-border text-ods-text-primary rounded-md text-sm font-medium hover:bg-ods-bg-secondary transition-colors"
+          >
+            <LinkedinIcon className="w-4 h-4" />
+            <span>View on LinkedIn</span>
+          </a>
+        </div>
+      </LinkedInContainer>
+    );
+  }
+
+  return (
+    <LinkedInContainer>
+      <div className="relative w-full" style={{ height }}>
+        {!loaded && (
+          <div className="absolute inset-0 p-6 animate-pulse">
+            <div className="flex items-center space-x-3 mb-4">
+              <div className="w-12 h-12 bg-ods-border rounded-full" />
+              <div>
+                <div className="h-4 bg-ods-border rounded w-32 mb-2" />
+                <div className="h-3 bg-ods-border rounded w-24" />
+              </div>
+            </div>
+            <div className="space-y-2">
+              <div className="h-4 bg-ods-border rounded w-full" />
+              <div className="h-4 bg-ods-border rounded w-3/4" />
+            </div>
+          </div>
+        )}
+        <iframe
+          src={embedUrl}
+          title="Embedded LinkedIn post"
+          className="w-full h-full"
+          style={{ border: 0 }}
+          loading="lazy"
+          allowFullScreen
+          onLoad={() => setLoaded(true)}
+        />
+      </div>
+      <div className="px-4 py-3 bg-ods-bg-secondary border-t border-ods-border">
+        <a
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="inline-flex items-center space-x-2 text-ods-accent hover:text-ods-accent/80 transition-colors text-sm font-medium"
+        >
+          <ExternalLink className="w-4 h-4" />
+          <span>View on LinkedIn</span>
+        </a>
+      </div>
+    </LinkedInContainer>
+  );
+}

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

@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Image from '../../embed-shims/next-image';
+import { useRichMarkdownRuntime } from './rich-markdown-runtime';
+
+/**
+ * In-article markdown image.
+ *
+ * Markdown images have unknown intrinsic dimensions — which is what broke the old
+ * approach: a fixed width/height made the Supabase loader `resize=cover` CROP tall
+ * screenshots, and `w-full` then blew them up to the column width. This renders
+ * through the lib's `next/image` shim (full Next.js Image Optimization on the hub,
+ * plain `<img>` everywhere else) and fixes both problems at the source:
+ *
+ *   - `object-contain` flips the hub's Supabase loader (injected via
+ *     `transformImageSrc` from the {@link RichMarkdownRuntimeProvider}) to
+ *     `resize=contain` — aspect preserved, never cropped.
+ *   - We learn the real aspect ratio from a tiny probe (the same
+ *     `transformImageSrc` at 48px when available) and pass matching width/height
+ *     so `next/image`'s aspect-ratio box is correct.
+ *   - CSS (`max-w-full` + `max-h` + auto) caps the on-page size so a tall
+ *     screenshot can't dominate the article, while the browser keeps the true
+ *     aspect ratio.
+ *
+ * Embedders that don't pass `transformImageSrc` get an identity fallback — the
+ * raw `src` is used both for the probe and the display copy.
+ */
+const MAX_H_REM = 32; // ~512px on-page cap
+const DISPLAY_W = 768; // logical width hint; the optimizer handles srcset + retina
+
+export function MarkdownImage({ src, alt }: { src: string; alt?: string }) {
+  const { transformImageSrc } = useRichMarkdownRuntime();
+  const [ratio, setRatio] = useState<number | null>(null); // width / height
+
+  useEffect(() => {
+    let cancelled = false;
+    // Reset on src change so a reused instance doesn't briefly size the new image with
+    // the previous image's ratio.
+    setRatio(null);
+    // Probe a tiny aspect-preserving variant so we learn the real ratio without
+    // downloading the full image; the display copy is then fetched once, at the right size.
+    // When no transformer is wired (embedders), fall back to the raw src.
+    const probeSrc = transformImageSrc(src, { width: 48, resize: 'contain', quality: 20 }) ?? src;
+    const probe = new window.Image();
+    probe.onload = () => {
+      if (!cancelled && probe.naturalWidth && probe.naturalHeight) {
+        setRatio(probe.naturalWidth / probe.naturalHeight);
+      }
+    };
+    probe.onerror = () => {
+      if (!cancelled) setRatio(1.5); // neutral fallback so we still render something
+    };
+    probe.src = probeSrc;
+    return () => {
+      cancelled = true;
+    };
+  }, [src, transformImageSrc]);
+
+  // Reserve a neutral box while probing so the layout doesn't jump when the image appears.
+  if (!ratio) {
+    return (
+      <span
+        className="mx-auto my-2 block w-full max-w-full animate-pulse rounded-lg bg-ods-card"
+        style={{ aspectRatio: '3 / 2', maxHeight: `${MAX_H_REM}rem` }}
+        aria-hidden
+      />
+    );
+  }
+
+  return (
+    <Image
+      src={src}
+      alt={alt ?? 'No image available'}
+      width={DISPLAY_W}
+      height={Math.round(DISPLAY_W / ratio)}
+      sizes="(max-width: 768px) 100vw, 768px"
+      loading="lazy"
+      // `object-contain` → SupabaseOptimizedImage uses `resize=contain` (no crop).
+      // `w-full` (not `w-auto`) gives the img a definite width so it lays out + lazy-loads
+      // even before decode. Height follows via the aspect-ratio box; `maxHeight` caps tall
+      // images and `maxWidth = maxHeight × ratio` shrinks the width in lockstep so the box
+      // stays snug to the image (no letterbox bars).
+      className="mx-auto my-2 block h-auto w-full rounded-lg object-contain"
+      style={{ maxWidth: `calc(${MAX_H_REM}rem * ${ratio})`, maxHeight: `${MAX_H_REM}rem` }}
+    />
+  );
+}