@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/components/ui/markdown/rich/embed-overrides.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+/**
+ * Rich-composition component overrides: the embed layer (Video SSOT,
+ * Reddit/Twitter/LinkedIn embeds, OG link previews, Figma, MarkdownImage).
+ *
+ * These imports are deliberately isolated in this file — keeping them out
+ * of the engine and the simple composition keeps the CHAT bundle free of
+ * embed code (a runtime `variant` prop could not be tree-shaken; a
+ * separate composition module can).
+ */
+import React from 'react';
+import type { Components } from 'react-markdown';
+import { RedditEmbedClient } from '../../../embeds/reddit-embed-client';
+import { TwitterEmbedClient } from '../../../embeds/twitter-embed-client';
+import { LinkedInEmbedClient } from '../../../embeds/linkedin-embed-client';
+import { Video } from '../../../features/video';
+import { OGLinkPreview, OGLinkErrorBoundary } from '../../../embeds/og-link-preview';
+import { FigmaEmbed } from '../../../embeds/figma-embed';
+import { MarkdownImage } from '../../../embeds/markdown-image';
+import { buildStandardLeafRenderers, hasRenderableSrc } from '../base-components';
+import type { TextSizeElement } from '../text-size';
+
+/** Depth-first search of a hast node for the first `<a href>` matching `hostRe`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function findFirstHref(node: any, hostRe: RegExp): string | null {
+  if (!node) return null;
+  if (node.tagName === 'a') {
+    const href = node.properties?.href;
+    if (typeof href === 'string' && hostRe.test(href)) return href;
+  }
+  for (const child of node.children ?? []) {
+    const found = findFirstHref(child, hostRe);
+    if (found) return found;
+  }
+  return null;
+}
+
+export interface BuildRichEmbedOverridesOptions {
+  ogApiBaseUrl: string;
+  ogEndpointPath: string;
+  textSizes: Record<TextSizeElement, string>;
+}
+
+/**
+ * Overrides spread LAST onto the engine's base map: `code` (fence-language
+ * embeds), `div` (shortcode-expanded embeds), `img` (MarkdownImage with
+ * runtime transformImageSrc), `video` (raw tags → Video SSOT).
+ */
+export function buildRichEmbedOverrides({
+  ogApiBaseUrl,
+  ogEndpointPath,
+  textSizes,
+}: BuildRichEmbedOverridesOptions): Partial<Components> {
+  // Standard `code` / `blockquote` / `div` come from the base SSOT — this
+  // module owns ONLY the embed special cases and delegates every
+  // fall-through, so the shared markup can never drift between the two
+  // compositions.
+  //
+  // The delegations below CALL those renderers as plain functions rather
+  // than rendering them as components (that is what the `as any` casts are
+  // for). That is only sound because `buildStandardLeafRenderers` is
+  // documented HOOK-FREE — if a hook ever appears in one of them, these
+  // call sites must become real elements (`<Standard.code {...props} />`)
+  // first.
+  const standard = buildStandardLeafRenderers({ textSizes });
+
+  return {
+    // Fence-language embeds (```youtube-embed etc.); everything else
+    // (mermaid, highlighted blocks, inline code) falls through to `standard`.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    code: (codeProps: any) => {
+      const { inline, className: codeClassName, children } = codeProps;
+      const match = /language-(\w+)/.exec(codeClassName || '');
+      const language = match ? match[1] : '';
+      const fenceText = () => String(children).replace(/\n$/, '').trim();
+
+      if (!inline && language === 'youtube-embed') {
+        return <Video kind="youtube" url={fenceText()} />;
+      }
+      if (!inline && language === 'reddit-embed') {
+        return <RedditEmbedClient url={fenceText()} />;
+      }
+      if (!inline && language === 'tweet-embed') {
+        return <TwitterEmbedClient url={fenceText()} />;
+      }
+      if (!inline && language === 'link-preview') {
+        return (
+          <OGLinkPreview
+            url={fenceText()}
+            variant="compact"
+            enablePlaceholder={false}
+            apiBaseUrl={ogApiBaseUrl}
+            ogEndpointPath={ogEndpointPath}
+          />
+        );
+      }
+      if (!inline && language === 'figma-embed') {
+        return <FigmaEmbed url={fenceText()} height="70vh" />;
+      }
+      if (!inline && language === 'linkedin-embed') {
+        return <LinkedInEmbedClient url={fenceText()} />;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return (standard.code as any)(codeProps);
+    },
+
+    // Shortcode-expanded embeds: <div class="youtube-embed" data-video-id>…
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    div: (divProps: any) => {
+      const { className, ...props } = divProps;
+      if (className === 'youtube-embed') {
+        return <Video kind="youtube" url={props['data-video-id']} />;
+      }
+      if (className === 'reddit-embed') {
+        return <RedditEmbedClient url={props['data-post-url']} />;
+      }
+      if (className === 'tweet-embed') {
+        return <TwitterEmbedClient url={props['data-tweet-url']} />;
+      }
+      if (className === 'link-preview') {
+        const url = props['data-url'];
+        if (!url || typeof url !== 'string') {
+          console.warn('Invalid URL for link preview:', url);
+          return <div className="text-ods-text-secondary text-sm">Invalid link</div>;
+        }
+        try {
+          new URL(url);
+          return (
+            <OGLinkErrorBoundary fallback={<div className="text-ods-text-secondary text-sm">Link preview unavailable</div>}>
+              <OGLinkPreview
+                url={url}
+                variant="compact"
+                enablePlaceholder={false}
+                apiBaseUrl={ogApiBaseUrl}
+                ogEndpointPath={ogEndpointPath}
+              />
+            </OGLinkErrorBoundary>
+          );
+        } catch (e) {
+          console.warn('Malformed URL for link preview:', url, e);
+          return <div className="text-ods-text-secondary text-sm">Malformed URL: {url}</div>;
+        }
+      }
+      if (className === 'figma-embed') {
+        return <FigmaEmbed url={props['data-figma-url']} height="70vh" />;
+      }
+      if (className === 'linkedin-embed') {
+        return <LinkedInEmbedClient url={props['data-post-url']} />;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return (standard.div as any)(divProps);
+    },
+
+    // Reddit's OWN embed markup lives in 58 published blog posts as
+    // `<blockquote class="reddit-embed-bq">…<a href="post-url">` paired with
+    // a `<script src="embed.reddit.com/widgets.js">` loader. The sanitize
+    // stack strips the script (correctly), so the composition rehydrates the
+    // blockquote itself: extract the post URL from the first reddit link and
+    // render the RedditEmbedClient SSOT. Non-reddit blockquotes fall through
+    // to the engine's base blockquote.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    blockquote: (bqProps: any) => {
+      const { node, className } = bqProps;
+      const classNames: string = Array.isArray(className) ? className.join(' ') : (className ?? '');
+      if (classNames.includes('reddit-embed-bq')) {
+        const postUrl = findFirstHref(node, /reddit\.com/);
+        if (postUrl) return <RedditEmbedClient url={postUrl} />;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return (standard.blockquote as any)(bqProps);
+    },
+
+    // In-article images: MarkdownImage reads `transformImageSrc` from the
+    // rich-markdown runtime (Supabase optimization on the hub, identity
+    // elsewhere). Guard against empty `![]()`.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    img: ({ src, alt }: any) => {
+      // Empty-`![]()` guard shared with the base `img` renderer.
+      if (!hasRenderableSrc(src)) return null;
+      return <MarkdownImage src={src.trim()} alt={alt} />;
+    },
+
+    // Raw <video> tags in stored content (blog publisher injection) route
+    // to the <Video> SSOT (MuxPlayer) so HLS manifests play everywhere.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    video: ({ src, poster, className }: any) => {
+      if (!hasRenderableSrc(src)) return null;
+      return (
+        <div className={`overflow-hidden ${className || 'w-full my-8 rounded-lg'}`}>
+          <div className="w-full aspect-video">
+            <Video kind="file" url={src.trim()} poster={typeof poster === 'string' ? poster : undefined} />
+          </div>
+        </div>
+      );
+    },
+  };
+}

package/src/components/ui/markdown/rich/rich-markdown-renderer.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+/**
+ * RichMarkdownRenderer — the content composition over the unified
+ * `MarkdownEngine`: RuntimeProvider + shortcodes + embed overrides +
+ * fetch-based internal-link resolver + `article` typography.
+ *
+ * This IS the real component (the old 1223-line standalone implementation
+ * was deleted in the unification). Public prop surface is unchanged, so
+ * every hub/app call site compiles untouched. Deltas vs the old
+ * implementation are the ones reviewed in the unification plan: the
+ * sanitize stack + tag-escape pre-pass now apply to content surfaces
+ * (`extraAllowedHtmlTags={['video','source']}` keeps authored video
+ * working), the engine is memoized, and the dead light-mode branches are
+ * gone.
+ */
+import React, { memo, useCallback, useMemo } from 'react';
+import { MarkdownEngine, NO_BROKEN_LINKS, type MarkdownEngineProps } from '../engine';
+import type { ResolveLinkResult } from '../../../../types/doc-source';
+import {
+  RichMarkdownRuntimeProvider,
+  useRichMarkdownRuntime,
+  type RichMarkdownRuntime,
+} from '../../../embeds/rich-markdown-runtime';
+import { resolveTextSizeConfig } from '../text-size';
+import { buildRichEmbedOverrides } from './embed-overrides';
+import { processShortcodes } from './shortcodes';
+
+/** Raw-HTML tags authored content needs beyond the chat-safe baseline. */
+const RICH_EXTRA_TAGS = ['video', 'source'];
+
+/**
+ * The engine props this composition OWNS and therefore does not forward:
+ * shortcode preprocessing, the embed component map, the `article` text
+ * preset, the fetch link resolver, the rich tag allowlist, and streaming
+ * (authored content is never streamed).
+ */
+type RichOwnedEngineProps =
+  | 'extraAllowedHtmlTags'
+  | 'preprocessContent'
+  | 'componentOverrides'
+  | 'textSize'
+  | 'onResolveLink'
+  | 'additionalRemarkPlugins'
+  | 'streaming';
+
+/**
+ * Derived from `MarkdownEngineProps` rather than hand-copied. The previous
+ * shape restated 7 engine props here and a THIRD time in `InnerProps`, so
+ * every engine prop doc/type change had to be mirrored in three places (and
+ * a missed mirror type-checks fine while silently dropping the prop).
+ */
+export interface RichMarkdownRendererProps
+  extends Partial<RichMarkdownRuntime>,
+    Omit<MarkdownEngineProps, RichOwnedEngineProps> {
+  /** Source for resolving internal links (default: 'openframe-docs'). Registry id from DOC_SOURCES. */
+  resolveSource?: string;
+  /** Path of the internal link-resolver endpoint. Default '/api/docs/resolve-link'. */
+  resolveLinkEndpointUrl?: string;
+}
+
+const RichMarkdownRendererImpl: React.FC<RichMarkdownRendererProps> = ({
+  content,
+  className = '',
+  sectionIds,
+  onInternalLinkClick,
+  brokenLinks = NO_BROKEN_LINKS,
+  currentPath,
+  resolveSource = 'openframe-docs',
+  resolveLinkEndpointUrl = '/api/docs/resolve-link',
+  demoteMarkdownH1ToH2 = false,
+  // Runtime overrides; provider fills the defaults
+  redditProxyUrl,
+  twitterProxyUrl,
+  ogScraperUrl,
+  transformImageSrc,
+}) => {
+  return (
+    <RichMarkdownRuntimeProvider
+      redditProxyUrl={redditProxyUrl}
+      twitterProxyUrl={twitterProxyUrl}
+      ogScraperUrl={ogScraperUrl}
+      transformImageSrc={transformImageSrc}
+    >
+      <RichMarkdownInner
+        content={content}
+        className={className}
+        sectionIds={sectionIds}
+        onInternalLinkClick={onInternalLinkClick}
+        brokenLinks={brokenLinks}
+        currentPath={currentPath}
+        resolveSource={resolveSource}
+        resolveLinkEndpointUrl={resolveLinkEndpointUrl}
+        demoteMarkdownH1ToH2={demoteMarkdownH1ToH2}
+      />
+    </RichMarkdownRuntimeProvider>
+  );
+};
+
+/**
+ * "The outer component already applied these defaults", ENCODED IN THE TYPE:
+ * the runtime props are consumed by the provider (so they are gone here),
+ * and the three defaulted props are `Required` — a missed default upstream
+ * is a type error rather than a silent `undefined`.
+ */
+type InnerProps = Omit<RichMarkdownRendererProps, keyof RichMarkdownRuntime> &
+  Required<
+    Pick<
+      RichMarkdownRendererProps,
+      'resolveSource' | 'resolveLinkEndpointUrl' | 'demoteMarkdownH1ToH2'
+    >
+  >;
+
+const RichMarkdownInner: React.FC<InnerProps> = ({
+  content,
+  className = '',
+  sectionIds,
+  onInternalLinkClick,
+  brokenLinks,
+  currentPath,
+  resolveSource,
+  resolveLinkEndpointUrl,
+  demoteMarkdownH1ToH2,
+}) => {
+  const { ogScraperUrl } = useRichMarkdownRuntime();
+
+  // The OG link-preview endpoint is `${apiBaseUrl}${ogEndpointPath}` —
+  // split the runtime URL once. Full URLs route through the cross-origin
+  // proxy; path-only values are used as the path with an empty base.
+  const { ogApiBaseUrl, ogEndpointPath } = useMemo(() => {
+    try {
+      const u = new URL(ogScraperUrl);
+      return {
+        ogApiBaseUrl: `${u.protocol}//${u.host}`,
+        ogEndpointPath: u.pathname,
+      };
+    } catch {
+      return { ogApiBaseUrl: '', ogEndpointPath: ogScraperUrl };
+    }
+  }, [ogScraperUrl]);
+
+  // ONE link-resolution code path: the engine's callback seam. This is the
+  // fetch implementation the old Rich renderer had inline in its <a>
+  // handler — the engine's base `a` component now drives it.
+  const onResolveLink = useCallback(
+    async (href: string, path: string): Promise<ResolveLinkResult> => {
+      const response = await fetch(resolveLinkEndpointUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ link: href, currentPath: path, source: resolveSource }),
+      });
+      return response.json();
+    },
+    [resolveLinkEndpointUrl, resolveSource],
+  );
+
+  const textSizes = useMemo(() => resolveTextSizeConfig('article'), []);
+
+  const componentOverrides = useMemo(
+    () => buildRichEmbedOverrides({ ogApiBaseUrl, ogEndpointPath, textSizes }),
+    [ogApiBaseUrl, ogEndpointPath, textSizes],
+  );
+
+  return (
+    <MarkdownEngine
+      content={content}
+      className={className}
+      sectionIds={sectionIds}
+      demoteMarkdownH1ToH2={demoteMarkdownH1ToH2}
+      brokenLinks={brokenLinks}
+      currentPath={currentPath}
+      onInternalLinkClick={onInternalLinkClick}
+      onResolveLink={onResolveLink}
+      preprocessContent={processShortcodes}
+      componentOverrides={componentOverrides}
+      textSize="article"
+      extraAllowedHtmlTags={RICH_EXTRA_TAGS}
+    />
+  );
+};
+
+/** Memoized — see the engine's memo rationale. */
+export const RichMarkdownRenderer = memo(RichMarkdownRendererImpl);
+

package/src/components/ui/markdown/rich/shortcodes.ts

@@ -0,0 +1,170 @@
+/**
+ * Shortcode + auto-URL-embed preprocessing for the rich (content)
+ * composition. Moved verbatim from the old RichMarkdownRenderer — the
+ * `{{youtube:...}}` / `{% youtube %}` / thumbnail-link / auto-URL grammar
+ * is authored-content SSOT; chat surfaces never run this.
+ */
+
+export const processShortcodes = (content: string): string => {
+  let processedContent = content;
+
+  // Escape values interpolated into the raw HTML `data-*` attributes generated below.
+  // With rehypeRaw enabled, an unescaped `"`/`<`/`>` in a URL or id could break out of
+  // the attribute and inject markup, so every interpolated embed value goes through this.
+  const escapeAttr = (value: string) =>
+    value
+      .replace(/&/g, '&amp;')
+      .replace(/"/g, '&quot;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+
+  // First, process explicit shortcodes
+  processedContent = processedContent
+    // YouTube embeds: {{youtube:VIDEO_ID}}
+    .replace(/\{\{youtube:([^}]+)\}\}/g, (match, videoId) => {
+      return `\n\n<div class="youtube-embed" data-video-id="${escapeAttr(videoId.trim())}"></div>\n\n`;
+    })
+    // Markdoc-style YouTube: {% youtube id="VIDEO_ID" /%} or {% youtube id="VIDEO_ID" title="..." /%}
+    .replace(/\{%\s*youtube\s+id="([^"]+)"(?:\s+title="[^"]*")?\s*\/?%\}/g, (match, videoId) => {
+      return `\n\n<div class="youtube-embed" data-video-id="${escapeAttr(videoId.trim())}"></div>\n\n`;
+    })
+    /**
+     * SHORTCODE: YouTube Thumbnail Link (RECOMMENDED - GitHub + Flamingo Compatible)
+     *
+     * SYNTAX: [![Title](https://img.youtube.com/vi/VIDEO_ID/QUALITY.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)
+     *   - On GitHub: renders as a clickable thumbnail image linking to YouTube
+     *   - On Flamingo: converts to a full embedded YouTube player
+     * Use this format for docs that must work on BOTH GitHub and Flamingo;
+     * {{youtube:ID}} / {% youtube id="ID" /%} are Flamingo-only.
+     */
+    .replace(/\[!\[([^\]]*)\]\(https?:\/\/img\.youtube\.com\/vi\/([a-zA-Z0-9_-]+)\/[^)]+\)\]\(https?:\/\/(?:www\.)?(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]+)[^)]*\)/g,
+      (match, altText, thumbId, videoId) => {
+        return `\n\n<div class="youtube-embed" data-video-id="${videoId}"></div>\n\n`;
+      })
+    // Reddit embeds: {{reddit:POST_URL}}
+    .replace(/\{\{reddit:([^}]+)\}\}/g, (match, urlOrId) => {
+      const postUrl = urlOrId.trim();
+      const fullUrl = postUrl.startsWith('http') ? postUrl : `https://reddit.com/r/${postUrl}`;
+      return `\n\n<div class="reddit-embed" data-post-url="${escapeAttr(fullUrl)}"></div>\n\n`;
+    })
+    // Twitter/X embeds: {{tweet:TWEET_URL}} or {{twitter:TWEET_URL}}
+    .replace(/\{\{(?:tweet|twitter):([^}]+)\}\}/g, (match, urlOrId) => {
+      const tweetInput = urlOrId.trim();
+      const tweetUrl = tweetInput.startsWith('http')
+        ? tweetInput
+        : `https://twitter.com/twitter/status/${tweetInput}`;
+      return `\n\n<div class="tweet-embed" data-tweet-url="${escapeAttr(tweetUrl)}"></div>\n\n`;
+    })
+    // Figma embeds: {{figma:URL}}
+    .replace(/\{\{figma:([^}]+)\}\}/g, (match, url) => {
+      return `\n\n<div class="figma-embed" data-figma-url="${escapeAttr(url.trim())}"></div>\n\n`;
+    })
+    // LinkedIn embeds: {{linkedin:POST_URL}}
+    .replace(/\{\{linkedin:([^}]+)\}\}/g, (match, url) => {
+      return `\n\n<div class="linkedin-embed" data-post-url="${escapeAttr(url.trim())}"></div>\n\n`;
+    })
+    // Link previews: {{link:URL}}
+    .replace(/\{\{link:([^}]+)\}\}/g, (match, url) => {
+      return `\n\n<div class="link-preview" data-url="${escapeAttr(url.trim())}"></div>\n\n`;
+    });
+
+  // Next, auto-detect standalone URLs (but NOT those already in markdown links or code blocks)
+
+  // Step 1: Temporarily replace code blocks to protect them
+  const codeBlocks: string[] = [];
+  processedContent = processedContent.replace(/```[\s\S]*?```|`[^`]+`/g, (match) => {
+    const placeholder = `__CODE_BLOCK_${codeBlocks.length}__`;
+    codeBlocks.push(match);
+    return placeholder;
+  });
+
+  // Step 2: Temporarily replace markdown links to protect them
+  const markdownLinks: string[] = [];
+  processedContent = processedContent.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match) => {
+    const placeholder = `__MARKDOWN_LINK_${markdownLinks.length}__`;
+    markdownLinks.push(match);
+    return placeholder;
+  });
+
+  // Step 2.5: Temporarily replace table rows to protect URLs inside tables
+  const tableRows: string[] = [];
+  processedContent = processedContent.replace(/^\|.+\|$/gm, (match) => {
+    const placeholder = `__TABLE_ROW_${tableRows.length}__`;
+    tableRows.push(match);
+    return placeholder;
+  });
+
+  // Step 3: Auto-detect standalone URLs and convert to appropriate embeds
+  processedContent = processedContent
+    // YouTube URLs (standalone only)
+    .replace(/(?:^|\s)(https?:\/\/(?:www\.)?(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]+))(?:\s|$)/g,
+      (match, fullUrl, videoId) => {
+        return match.replace(fullUrl, `\n\n<div class="youtube-embed" data-video-id="${videoId}"></div>\n\n`);
+      })
+    // Reddit URLs (standalone only)
+    .replace(/(?:^|\s)(https?:\/\/(?:www\.)?reddit\.com\/[^\s]+)(?:\s|$)/g,
+      (match, redditUrl) => {
+        return match.replace(redditUrl, `\n\n<div class="reddit-embed" data-post-url="${escapeAttr(redditUrl)}"></div>\n\n`);
+      })
+    // Twitter/X URLs (standalone only)
+    .replace(/(?:^|\s)(https?:\/\/(?:www\.)?(?:twitter\.com|x\.com)\/[^\/\s]+\/status\/\d+)(?:\s|$)/g,
+      (match, tweetUrl) => {
+        return match.replace(tweetUrl, `\n\n<div class="tweet-embed" data-tweet-url="${escapeAttr(tweetUrl)}"></div>\n\n`);
+      })
+    // Figma URLs (standalone only) - design/file/proto/board/deck/slides → interactive embed
+    .replace(/(?:^|\s)(https?:\/\/(?:www\.|embed\.)?figma\.com\/(?:design|file|proto|board|deck|slides)\/[^\s]+)(?:\s|$)/g,
+      (match, figmaUrl) => {
+        return match.replace(figmaUrl, `\n\n<div class="figma-embed" data-figma-url="${escapeAttr(figmaUrl)}"></div>\n\n`);
+      })
+    // LinkedIn post URLs (standalone only) → native post embed
+    .replace(/(?:^|\s)(https?:\/\/(?:www\.)?linkedin\.com\/(?:posts|feed\/update|embed\/feed\/update)\/[^\s]+)(?:\s|$)/g,
+      (match, liUrl) => {
+        return match.replace(liUrl, `\n\n<div class="linkedin-embed" data-post-url="${escapeAttr(liUrl)}"></div>\n\n`);
+      })
+    // Other external URLs (standalone only) - convert to link previews
+    .replace(/(?:^|\s)(https?:\/\/[^\s]+)(?:\s|$)/g,
+      (match, url) => {
+        try {
+          const urlObj = new URL(url);
+          const hostname = urlObj.hostname.toLowerCase();
+
+          // Exact host match (or a subdomain of it) — substring checks like
+          // `hostname.includes('x.com')` false-positive on "zabbix.com".
+          const hostIs = (domain: string) =>
+            hostname === domain || hostname.endsWith(`.${domain}`);
+          // Non-video YouTube URLs (channels, playlists, `@handle`) fall
+          // through to the og-scraper; only video URLs become inline players.
+          const isYouTubeVideo =
+            (hostIs('youtube.com') && urlObj.searchParams.has('v')) || hostIs('youtu.be');
+          // LinkedIn non-post URLs (profiles, companies) fall through to the
+          // og-scraper too; only interactive post embeds have handlers above.
+          if (isYouTubeVideo ||
+              hostIs('reddit.com') || hostIs('twitter.com') || hostIs('x.com') ||
+              hostIs('figma.com')) {
+            return match;
+          }
+
+          return match.replace(url, `\n\n<div class="link-preview" data-url="${escapeAttr(url)}"></div>\n\n`);
+        } catch (e) {
+          console.warn('Failed to parse URL for link preview:', url, e);
+          return match;
+        }
+      });
+
+  // Step 3.5: Restore table rows
+  tableRows.forEach((row, index) => {
+    processedContent = processedContent.replace(`__TABLE_ROW_${index}__`, row);
+  });
+
+  // Step 4: Restore markdown links
+  markdownLinks.forEach((link, index) => {
+    processedContent = processedContent.replace(`__MARKDOWN_LINK_${index}__`, link);
+  });
+
+  // Step 5: Restore code blocks (MUST be last to prevent link preview in code)
+  codeBlocks.forEach((block, index) => {
+    processedContent = processedContent.replace(`__CODE_BLOCK_${index}__`, block);
+  });
+
+  return processedContent;
+};