From 07b4fbc5fb423614aaa7e4ffc0ef31f873dc27b2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 20 Apr 2026 00:06:26 +0000
Subject: [PATCH 1/3] Initial plan


From 0f817f15d80578b93c6154ed152dc075f3b6616a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 20 Apr 2026 00:12:41 +0000
Subject: [PATCH 2/3] feat: add oEmbed support

Agent-Logs-Url: https://github.com/streamich/react-embed/sessions/03024238-5624-486d-bf5d-3fe9b9dd6a42

Co-authored-by: streamich <9773803+streamich@users.noreply.github.com>
---
 src/ReactEmbed.tsx                 |   1 +
 src/blocks/oembed/fetchOEmbed.ts   | 105 ++++++++++++++++
 src/blocks/oembed/index.tsx        | 192 +++++++++++++++++++++++++++++
 src/index.tsx                      |   2 +
 src/routeToBlock.ts                |   3 +
 src/stories/ReactEmbed.stories.tsx |  33 +++++
 6 files changed, 336 insertions(+)
 create mode 100644 src/blocks/oembed/fetchOEmbed.ts
 create mode 100644 src/blocks/oembed/index.tsx

diff --git a/src/ReactEmbed.tsx b/src/ReactEmbed.tsx
index 0ec1ed065..e010ca913 100644
--- a/src/ReactEmbed.tsx
+++ b/src/ReactEmbed.tsx
@@ -34,6 +34,7 @@ const defaultBlocks: Blocks = {
   imgur: React.lazy(() => import('./blocks/imgur')),
   instagram: React.lazy(() => import('./blocks/instagram')),
   jsfiddle: React.lazy(() => import('./blocks/jsfiddle')),
+  oembed: React.lazy(() => import('./blocks/oembed')),
   pdf: React.lazy(() => import('./blocks/pdf')),
   reactPlayer: React.lazy(() => import('./blocks/react-player')),
   replit: React.lazy(() => import('./blocks/replit')),
diff --git a/src/blocks/oembed/fetchOEmbed.ts b/src/blocks/oembed/fetchOEmbed.ts
new file mode 100644
index 000000000..3c169aafc
--- /dev/null
+++ b/src/blocks/oembed/fetchOEmbed.ts
@@ -0,0 +1,105 @@
+/** oEmbed response as defined by https://oembed.com */
+export interface OEmbedResponse {
+  type: 'photo' | 'video' | 'link' | 'rich';
+  version: string;
+  title?: string;
+  author_name?: string;
+  author_url?: string;
+  provider_name?: string;
+  provider_url?: string;
+  cache_age?: number | string;
+  thumbnail_url?: string;
+  thumbnail_width?: number;
+  thumbnail_height?: number;
+  width?: number;
+  height?: number;
+  /** HTML markup for video/rich types */
+  html?: string;
+  /** Direct URL for photo type */
+  url?: string;
+}
+
+interface Provider {
+  patterns: RegExp[];
+  endpoint: string;
+}
+
+const PROVIDERS: Provider[] = [
+  {
+    patterns: [/youtube\.com/, /youtu\.be/],
+    endpoint: 'https://www.youtube.com/oembed',
+  },
+  {
+    patterns: [/vimeo\.com/],
+    endpoint: 'https://vimeo.com/api/oembed.json',
+  },
+  {
+    patterns: [/twitter\.com/, /x\.com/],
+    endpoint: 'https://publish.twitter.com/oembed',
+  },
+  {
+    patterns: [/soundcloud\.com/],
+    endpoint: 'https://soundcloud.com/oembed',
+  },
+  {
+    patterns: [/instagram\.com/],
+    endpoint: 'https://api.instagram.com/oembed/',
+  },
+  {
+    patterns: [/flickr\.com/],
+    endpoint: 'https://www.flickr.com/services/oembed/',
+  },
+  {
+    patterns: [/open\.spotify\.com/],
+    endpoint: 'https://open.spotify.com/oembed',
+  },
+  {
+    patterns: [/reddit\.com/],
+    endpoint: 'https://www.reddit.com/oembed',
+  },
+  {
+    patterns: [/tiktok\.com/],
+    endpoint: 'https://www.tiktok.com/oembed',
+  },
+  {
+    patterns: [/codepen\.io/],
+    endpoint: 'https://codepen.io/api/oembed',
+  },
+  {
+    patterns: [/dailymotion\.com/],
+    endpoint: 'https://www.dailymotion.com/services/oembed',
+  },
+  {
+    patterns: [/giphy\.com/],
+    endpoint: 'https://giphy.com/services/oembed',
+  },
+];
+
+/**
+ * Returns the oEmbed JSON endpoint URL for a given page URL,
+ * or `null` if no provider is registered for that URL.
+ */
+export function getOEmbedEndpoint(url: string): string | null {
+  for (const provider of PROVIDERS) {
+    if (provider.patterns.some((p) => p.test(url))) {
+      return `${provider.endpoint}?url=${encodeURIComponent(url)}&format=json`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Fetches oEmbed metadata for the given page URL.
+ * Throws if no provider is found or the request fails (e.g. due to CORS).
+ */
+export async function fetchOEmbed(url: string, signal?: AbortSignal): Promise<OEmbedResponse> {
+  const endpoint = getOEmbedEndpoint(url);
+  if (!endpoint) {
+    throw new Error(`No oEmbed provider found for URL: ${url}`);
+  }
+  const response = await fetch(endpoint, {signal});
+  if (!response.ok) {
+    throw new Error(`oEmbed request failed with status ${response.status}`);
+  }
+  return response.json() as Promise<OEmbedResponse>;
+}
diff --git a/src/blocks/oembed/index.tsx b/src/blocks/oembed/index.tsx
new file mode 100644
index 000000000..2a3ea8e83
--- /dev/null
+++ b/src/blocks/oembed/index.tsx
@@ -0,0 +1,192 @@
+import * as React from 'react';
+import {BlockProps} from '../..';
+import {fetchOEmbed, OEmbedResponse} from './fetchOEmbed';
+
+export {fetchOEmbed, getOEmbedEndpoint} from './fetchOEmbed';
+export type {OEmbedResponse} from './fetchOEmbed';
+
+export interface OEmbedBlockOptions {
+  /**
+   * When `true`, the raw HTML provided by the oEmbed provider (e.g. an
+   * `<iframe>`) is injected via `dangerouslySetInnerHTML`.  Defaults to
+   * `false` – a safe info-card is rendered instead.
+   */
+  renderHtml?: boolean;
+}
+
+// ─── styles ──────────────────────────────────────────────────────────────────
+
+const cardStyle: React.CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  maxWidth: '100%',
+  overflow: 'hidden',
+  borderRadius: '8px',
+  border: '1px solid #E5E9F2',
+  fontFamily: 'sans-serif',
+  background: '#fff',
+};
+
+const cardStyleDark: React.CSSProperties = {
+  ...cardStyle,
+  border: '1px solid #2e3440',
+  background: '#2e3440',
+  color: '#eceff4',
+};
+
+const thumbnailStyle: React.CSSProperties = {
+  display: 'block',
+  width: '100%',
+  objectFit: 'cover',
+  maxHeight: '240px',
+};
+
+const bodyStyle: React.CSSProperties = {
+  padding: '12px 16px',
+};
+
+const providerStyle: React.CSSProperties = {
+  fontSize: '11px',
+  fontWeight: 600,
+  textTransform: 'uppercase',
+  letterSpacing: '0.05em',
+  color: '#8a9ab0',
+  marginBottom: '4px',
+};
+
+const titleStyle: React.CSSProperties = {
+  fontSize: '15px',
+  fontWeight: 600,
+  margin: '0 0 4px',
+  lineHeight: 1.4,
+};
+
+const authorStyle: React.CSSProperties = {
+  fontSize: '12px',
+  color: '#8a9ab0',
+  margin: 0,
+};
+
+const anchorStyle: React.CSSProperties = {
+  color: 'inherit',
+  textDecoration: 'none',
+};
+
+// ─── card renderer ────────────────────────────────────────────────────────────
+
+function OEmbedCard({data, isDark}: {data: OEmbedResponse; isDark: boolean}) {
+  const style = isDark ? cardStyleDark : cardStyle;
+
+  const thumbnail =
+    data.type === 'photo' ? (
+      <img src={data.url || data.thumbnail_url} alt={data.title || ''} style={thumbnailStyle} />
+    ) : data.thumbnail_url ? (
+      <img src={data.thumbnail_url} alt={data.title || ''} style={thumbnailStyle} />
+    ) : null;
+
+  return (
+    <div style={style}>
+      {thumbnail}
+      <div style={bodyStyle}>
+        {data.provider_name && (
+          <p style={providerStyle}>
+            {data.provider_url ? (
+              <a href={data.provider_url} target="_blank" rel="noopener noreferrer" style={anchorStyle}>
+                {data.provider_name}
+              </a>
+            ) : (
+              data.provider_name
+            )}
+          </p>
+        )}
+        {data.title && (
+          <p style={titleStyle}>
+            {data.author_url ? (
+              <a href={data.author_url} target="_blank" rel="noopener noreferrer" style={anchorStyle}>
+                {data.title}
+              </a>
+            ) : (
+              data.title
+            )}
+          </p>
+        )}
+        {data.author_name && (
+          <p style={authorStyle}>
+            {data.author_url ? (
+              <a href={data.author_url} target="_blank" rel="noopener noreferrer" style={anchorStyle}>
+                {data.author_name}
+              </a>
+            ) : (
+              data.author_name
+            )}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ─── block component ──────────────────────────────────────────────────────────
+
+interface OEmbedBlockState {
+  data: OEmbedResponse | null;
+  loading: boolean;
+  error: Error | null;
+}
+
+class OEmbedBlock extends React.PureComponent<BlockProps & {renderHtml: boolean}, OEmbedBlockState> {
+  state: OEmbedBlockState = {data: null, loading: true, error: null};
+  controller = new AbortController();
+
+  componentDidMount() {
+    const {signal} = this.controller;
+    fetchOEmbed(this.props.url, signal)
+      .then((data) => {
+        if (!signal.aborted) this.setState({data, loading: false});
+      })
+      .catch((error) => {
+        if (!signal.aborted) this.setState({error, loading: false});
+      });
+  }
+
+  componentWillUnmount() {
+    this.controller.abort();
+  }
+
+  render() {
+    const {renderWrap, renderVoid, renderHtml, isDark} = this.props;
+    const {data, loading, error} = this.state;
+
+    if (loading) return renderWrap(null);
+    if (error || !data) return renderVoid(error || undefined);
+
+    if (renderHtml && data.html) {
+      // Opt-in: inject the provider's own HTML (e.g. an <iframe>)
+      return renderWrap(<div dangerouslySetInnerHTML={{__html: data.html}} />);
+    }
+
+    return renderWrap(<OEmbedCard data={data} isDark={isDark} />);
+  }
+}
+
+// ─── public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Creates an oEmbed block component.
+ *
+ * ```tsx
+ * // Default – renders a safe info-card
+ * <ReactEmbed url="https://vimeo.com/54763818" />
+ *
+ * // Opt-in HTML rendering (injects the provider's <iframe>)
+ * const blocks = { ...defaultBlocks, oembed: createOEmbedBlock({ renderHtml: true }) };
+ * <ReactEmbed url="https://vimeo.com/54763818" blocks={blocks} />
+ * ```
+ */
+export function createOEmbedBlock(options: OEmbedBlockOptions = {}): React.ComponentType<BlockProps> {
+  const {renderHtml = false} = options;
+  const Block: React.FC<BlockProps> = (props) => <OEmbedBlock {...props} renderHtml={renderHtml} />;
+  return Block;
+}
+
+export default createOEmbedBlock();
diff --git a/src/index.tsx b/src/index.tsx
index 00c96388d..6177f3ad0 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -2,6 +2,8 @@ import * as React from 'react';
 import {ReactEmbedProps} from './ReactEmbed';
 
 export * from './ReactEmbed';
+export {fetchOEmbed, getOEmbedEndpoint, createOEmbedBlock} from './blocks/oembed';
+export type {OEmbedResponse, OEmbedBlockOptions} from './blocks/oembed';
 
 const Resource = React.lazy(() => import('./ReactEmbed') as any);
 
diff --git a/src/routeToBlock.ts b/src/routeToBlock.ts
index 4611693fb..43a07739c 100644
--- a/src/routeToBlock.ts
+++ b/src/routeToBlock.ts
@@ -2,6 +2,7 @@ import {Blocks, ReactEmbedRouter, ParsedUrl} from '.';
 import canPlaySimplePlayer from './blocks/react-simple-player/canPlay';
 import canPlay from './blocks/react-player/canPlay';
 import canPlayPdf from './blocks/pdf/canPlay';
+import {getOEmbedEndpoint} from './blocks/oembed/fetchOEmbed';
 
 const routeTwitter: ReactEmbedRouter = (blocks, {pathname}) => {
   const steps = pathname.split('/');
@@ -102,6 +103,8 @@ const routeToBlock: ReactEmbedRouter = (blocks: Blocks, parsed: ParsedUrl) => {
         return [blocks.simplePlayer, ''];
       } else if (canPlay(url)) {
         return [blocks.reactPlayer, ''];
+      } else if (getOEmbedEndpoint(url)) {
+        return [blocks.oembed, ''];
       } else {
         return undefined;
       }
diff --git a/src/stories/ReactEmbed.stories.tsx b/src/stories/ReactEmbed.stories.tsx
index a4b31fd1c..b5a8f6d32 100644
--- a/src/stories/ReactEmbed.stories.tsx
+++ b/src/stories/ReactEmbed.stories.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react';
 import Embed from '..';
+import {createOEmbedBlock} from '../blocks/oembed';
 import {Box} from './Box';
 
 const urls = [
@@ -124,3 +125,35 @@ export const Wrapper = {
     ),
   },
 };
+
+const oEmbedUrls = [
+  'https://vimeo.com/54763818',
+  'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl',
+  'https://www.flickr.com/photos/bees/2362225867/',
+  'https://codepen.io/anon/pen/YzPXoeb',
+];
+
+export const OEmbedCard = {
+  args: {
+    url: oEmbedUrls[0],
+  },
+  argTypes: {
+    url: {
+      options: oEmbedUrls,
+      control: {type: 'select'},
+    },
+  },
+};
+
+export const OEmbedHtml = {
+  args: {
+    url: oEmbedUrls[0],
+    blocks: {oembed: createOEmbedBlock({renderHtml: true})},
+  },
+  argTypes: {
+    url: {
+      options: oEmbedUrls,
+      control: {type: 'select'},
+    },
+  },
+};

From 75a00a83c2136a7717c5156c13f043abc0e0f7ab Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 20 Apr 2026 01:06:30 +0000
Subject: [PATCH 3/3] feat(oembed): tuple provider type, more providers,
 well-known path probing

Agent-Logs-Url: https://github.com/streamich/react-embed/sessions/d8e7c380-2dda-4223-9240-b18011beb43d

Co-authored-by: streamich <9773803+streamich@users.noreply.github.com>
---
 src/blocks/oembed/fetchOEmbed.ts   | 135 +++++++++++++++--------------
 src/blocks/oembed/index.tsx        |  55 ++++++------
 src/index.tsx                      |   2 +-
 src/stories/ReactEmbed.stories.tsx |   4 +-
 4 files changed, 101 insertions(+), 95 deletions(-)

diff --git a/src/blocks/oembed/fetchOEmbed.ts b/src/blocks/oembed/fetchOEmbed.ts
index 3c169aafc..5e60f15c2 100644
--- a/src/blocks/oembed/fetchOEmbed.ts
+++ b/src/blocks/oembed/fetchOEmbed.ts
@@ -19,70 +19,57 @@ export interface OEmbedResponse {
   url?: string;
 }
 
-interface Provider {
-  patterns: RegExp[];
-  endpoint: string;
-}
+/** A registered oEmbed provider: [hostnames[], endpointBase] */
+export type Provider = [patterns: string[], endpoint: string];
 
 const PROVIDERS: Provider[] = [
-  {
-    patterns: [/youtube\.com/, /youtu\.be/],
-    endpoint: 'https://www.youtube.com/oembed',
-  },
-  {
-    patterns: [/vimeo\.com/],
-    endpoint: 'https://vimeo.com/api/oembed.json',
-  },
-  {
-    patterns: [/twitter\.com/, /x\.com/],
-    endpoint: 'https://publish.twitter.com/oembed',
-  },
-  {
-    patterns: [/soundcloud\.com/],
-    endpoint: 'https://soundcloud.com/oembed',
-  },
-  {
-    patterns: [/instagram\.com/],
-    endpoint: 'https://api.instagram.com/oembed/',
-  },
-  {
-    patterns: [/flickr\.com/],
-    endpoint: 'https://www.flickr.com/services/oembed/',
-  },
-  {
-    patterns: [/open\.spotify\.com/],
-    endpoint: 'https://open.spotify.com/oembed',
-  },
-  {
-    patterns: [/reddit\.com/],
-    endpoint: 'https://www.reddit.com/oembed',
-  },
-  {
-    patterns: [/tiktok\.com/],
-    endpoint: 'https://www.tiktok.com/oembed',
-  },
-  {
-    patterns: [/codepen\.io/],
-    endpoint: 'https://codepen.io/api/oembed',
-  },
-  {
-    patterns: [/dailymotion\.com/],
-    endpoint: 'https://www.dailymotion.com/services/oembed',
-  },
-  {
-    patterns: [/giphy\.com/],
-    endpoint: 'https://giphy.com/services/oembed',
-  },
+  [['www.youtube.com', 'youtube.com', 'youtu.be'], 'https://www.youtube.com/oembed'],
+  [['vimeo.com', 'player.vimeo.com'], 'https://vimeo.com/api/oembed.json'],
+  [['twitter.com', 'x.com', 'mobile.twitter.com'], 'https://publish.twitter.com/oembed'],
+  [['soundcloud.com'], 'https://soundcloud.com/oembed'],
+  [['www.instagram.com', 'instagram.com'], 'https://api.instagram.com/oembed/'],
+  [['www.flickr.com', 'flickr.com', 'flic.kr'], 'https://www.flickr.com/services/oembed/'],
+  [['open.spotify.com'], 'https://open.spotify.com/oembed'],
+  [['www.reddit.com', 'reddit.com'], 'https://www.reddit.com/oembed'],
+  [['www.tiktok.com', 'tiktok.com', 'vm.tiktok.com'], 'https://www.tiktok.com/oembed'],
+  [['codepen.io'], 'https://codepen.io/api/oembed'],
+  [['www.dailymotion.com', 'dailymotion.com'], 'https://www.dailymotion.com/services/oembed'],
+  [['giphy.com', 'gph.is', 'media.giphy.com'], 'https://giphy.com/services/oembed'],
+  [['www.slideshare.net', 'slideshare.net'], 'https://www.slideshare.net/api/oembed/2'],
+  [['speakerdeck.com'], 'https://speakerdeck.com/oembed.json'],
+  [['www.mixcloud.com', 'mixcloud.com'], 'https://www.mixcloud.com/oembed/'],
+  [['www.deviantart.com', 'deviantart.com', 'fav.me', 'sta.sh'], 'https://backend.deviantart.com/oembed'],
+  [['www.ted.com', 'ted.com'], 'https://www.ted.com/services/v1/oembed.json'],
+  [['www.tumblr.com', 'tumblr.com'], 'https://www.tumblr.com/oembed/1.0'],
+  [['www.kickstarter.com', 'kickstarter.com', 'kck.st'], 'https://www.kickstarter.com/services/oembed'],
+  [['www.meetup.com', 'meetup.com'], 'https://api.meetup.com/oembed'],
+  [['500px.com'], 'https://api.500px.com/v1/photos/oembed'],
+  [['www.twitch.tv', 'twitch.tv', 'clips.twitch.tv'], 'https://www.twitch.tv/oembed'],
+  [['music.apple.com'], 'https://music.apple.com/oembed'],
+  [['www.pinterest.com', 'pinterest.com', 'pin.it'], 'https://www.pinterest.com/oembed.json'],
+  [['www.deezer.com', 'deezer.com'], 'https://api.deezer.com/oembed'],
+  [['bandcamp.com'], 'https://bandcamp.com/oembed'],
+  [['www.wistia.com', 'wistia.com', 'wi.st', 'fast.wistia.net'], 'https://fast.wistia.com/oembed.json'],
+  [['www.loom.com', 'loom.com'], 'https://www.loom.com/v1/oembed'],
+  [['www.canva.com', 'canva.com'], 'https://www.canva.com/api/oembed'],
 ];
 
+const WELL_KNOWN_PATHS = ['/oembed', '/oembed.json', '/api/oembed', '/services/oembed'];
+
 /**
- * Returns the oEmbed JSON endpoint URL for a given page URL,
- * or `null` if no provider is registered for that URL.
+ * Returns the oEmbed JSON endpoint URL for a given page URL, or `null` if no
+ * registered provider matches the hostname.
  */
 export function getOEmbedEndpoint(url: string): string | null {
-  for (const provider of PROVIDERS) {
-    if (provider.patterns.some((p) => p.test(url))) {
-      return `${provider.endpoint}?url=${encodeURIComponent(url)}&format=json`;
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  for (const [patterns, endpoint] of PROVIDERS) {
+    if (patterns.includes(hostname)) {
+      return `${endpoint}?url=${encodeURIComponent(url)}&format=json`;
     }
   }
   return null;
@@ -90,16 +77,34 @@ export function getOEmbedEndpoint(url: string): string | null {
 
 /**
  * Fetches oEmbed metadata for the given page URL.
- * Throws if no provider is found or the request fails (e.g. due to CORS).
+ *
+ * If no registered provider matches, probes well-known oEmbed paths on the
+ * same origin (`/oembed`, `/oembed.json`, `/api/oembed`, `/services/oembed`).
+ * Throws if every attempt fails or is blocked by CORS.
  */
 export async function fetchOEmbed(url: string, signal?: AbortSignal): Promise<OEmbedResponse> {
-  const endpoint = getOEmbedEndpoint(url);
-  if (!endpoint) {
-    throw new Error(`No oEmbed provider found for URL: ${url}`);
+  const knownEndpoint = getOEmbedEndpoint(url);
+  if (knownEndpoint) {
+    const response = await fetch(knownEndpoint, {signal});
+    if (!response.ok) throw new Error(`oEmbed request failed with status ${response.status}`);
+    return response.json() as Promise<OEmbedResponse>;
   }
-  const response = await fetch(endpoint, {signal});
-  if (!response.ok) {
-    throw new Error(`oEmbed request failed with status ${response.status}`);
+
+  // Probe well-known paths on the provider's own origin
+  let origin: string;
+  try {
+    origin = new URL(url).origin;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  for (const path of WELL_KNOWN_PATHS) {
+    const probeUrl = `${origin}${path}?url=${encodeURIComponent(url)}&format=json`;
+    try {
+      const response = await fetch(probeUrl, {signal});
+      if (response.ok) return response.json() as Promise<OEmbedResponse>;
+    } catch {
+      // CORS or network error – try next path
+    }
   }
-  return response.json() as Promise<OEmbedResponse>;
+  throw new Error(`No oEmbed provider found for URL: ${url}`);
 }
diff --git a/src/blocks/oembed/index.tsx b/src/blocks/oembed/index.tsx
index 2a3ea8e83..deaa43353 100644
--- a/src/blocks/oembed/index.tsx
+++ b/src/blocks/oembed/index.tsx
@@ -3,7 +3,7 @@ import {BlockProps} from '../..';
 import {fetchOEmbed, OEmbedResponse} from './fetchOEmbed';
 
 export {fetchOEmbed, getOEmbedEndpoint} from './fetchOEmbed';
-export type {OEmbedResponse} from './fetchOEmbed';
+export type {OEmbedResponse, Provider} from './fetchOEmbed';
 
 export interface OEmbedBlockOptions {
   /**
@@ -14,8 +14,6 @@ export interface OEmbedBlockOptions {
   renderHtml?: boolean;
 }
 
-// ─── styles ──────────────────────────────────────────────────────────────────
-
 const cardStyle: React.CSSProperties = {
   display: 'flex',
   flexDirection: 'column',
@@ -72,14 +70,13 @@ const anchorStyle: React.CSSProperties = {
   textDecoration: 'none',
 };
 
-// ─── card renderer ────────────────────────────────────────────────────────────
-
-function OEmbedCard({data, isDark}: {data: OEmbedResponse; isDark: boolean}) {
+function OEmbedCard({data, isDark, url}: {data: OEmbedResponse; isDark: boolean; url: string}) {
   const style = isDark ? cardStyleDark : cardStyle;
+  const photoSrc = data.url || data.thumbnail_url;
 
   const thumbnail =
     data.type === 'photo' ? (
-      <img src={data.url || data.thumbnail_url} alt={data.title || ''} style={thumbnailStyle} />
+      photoSrc ? <img src={photoSrc} alt={data.title || ''} style={thumbnailStyle} /> : null
     ) : data.thumbnail_url ? (
       <img src={data.thumbnail_url} alt={data.title || ''} style={thumbnailStyle} />
     ) : null;
@@ -101,13 +98,9 @@ function OEmbedCard({data, isDark}: {data: OEmbedResponse; isDark: boolean}) {
         )}
         {data.title && (
           <p style={titleStyle}>
-            {data.author_url ? (
-              <a href={data.author_url} target="_blank" rel="noopener noreferrer" style={anchorStyle}>
-                {data.title}
-              </a>
-            ) : (
-              data.title
-            )}
+            <a href={url} target="_blank" rel="noopener noreferrer" style={anchorStyle}>
+              {data.title}
+            </a>
           </p>
         )}
         {data.author_name && (
@@ -126,8 +119,6 @@ function OEmbedCard({data, isDark}: {data: OEmbedResponse; isDark: boolean}) {
   );
 }
 
-// ─── block component ──────────────────────────────────────────────────────────
-
 interface OEmbedBlockState {
   data: OEmbedResponse | null;
   loading: boolean;
@@ -138,49 +129,59 @@ class OEmbedBlock extends React.PureComponent<BlockProps & {renderHtml: boolean}
   state: OEmbedBlockState = {data: null, loading: true, error: null};
   controller = new AbortController();
 
-  componentDidMount() {
+  fetchData() {
     const {signal} = this.controller;
     fetchOEmbed(this.props.url, signal)
       .then((data) => {
-        if (!signal.aborted) this.setState({data, loading: false});
+        if (!signal.aborted) this.setState({data, loading: false, error: null});
       })
       .catch((error) => {
-        if (!signal.aborted) this.setState({error, loading: false});
+        if (!signal.aborted) this.setState({data: null, error, loading: false});
       });
   }
 
+  componentDidMount() {
+    this.fetchData();
+  }
+
+  componentDidUpdate(prevProps: BlockProps & {renderHtml: boolean}) {
+    if (prevProps.url !== this.props.url) {
+      this.controller.abort();
+      this.controller = new AbortController();
+      this.setState({data: null, loading: true, error: null}, () => this.fetchData());
+    }
+  }
+
   componentWillUnmount() {
     this.controller.abort();
   }
 
   render() {
-    const {renderWrap, renderVoid, renderHtml, isDark} = this.props;
+    const {renderWrap, renderVoid, renderHtml, isDark, url} = this.props;
     const {data, loading, error} = this.state;
 
     if (loading) return renderWrap(null);
     if (error || !data) return renderVoid(error || undefined);
 
     if (renderHtml && data.html) {
-      // Opt-in: inject the provider's own HTML (e.g. an <iframe>)
+      // Opt-in: inject the provider's own HTML (e.g. an <iframe>). Caller accepts XSS risk.
       return renderWrap(<div dangerouslySetInnerHTML={{__html: data.html}} />);
     }
 
-    return renderWrap(<OEmbedCard data={data} isDark={isDark} />);
+    return renderWrap(<OEmbedCard data={data} isDark={isDark} url={url} />);
   }
 }
 
-// ─── public API ──────────────────────────────────────────────────────────────
-
 /**
  * Creates an oEmbed block component.
  *
  * ```tsx
  * // Default – renders a safe info-card
- * <ReactEmbed url="https://vimeo.com/54763818" />
+ * <ReactEmbed url="https://www.flickr.com/photos/bees/2362225867/" />
  *
- * // Opt-in HTML rendering (injects the provider's <iframe>)
+ * // Opt-in HTML rendering (injects the provider's <iframe>; caller accepts XSS risk)
  * const blocks = { ...defaultBlocks, oembed: createOEmbedBlock({ renderHtml: true }) };
- * <ReactEmbed url="https://vimeo.com/54763818" blocks={blocks} />
+ * <ReactEmbed url="https://www.flickr.com/photos/bees/2362225867/" blocks={blocks} />
  * ```
  */
 export function createOEmbedBlock(options: OEmbedBlockOptions = {}): React.ComponentType<BlockProps> {
diff --git a/src/index.tsx b/src/index.tsx
index 6177f3ad0..c033efc3d 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -3,7 +3,7 @@ import {ReactEmbedProps} from './ReactEmbed';
 
 export * from './ReactEmbed';
 export {fetchOEmbed, getOEmbedEndpoint, createOEmbedBlock} from './blocks/oembed';
-export type {OEmbedResponse, OEmbedBlockOptions} from './blocks/oembed';
+export type {OEmbedResponse, OEmbedBlockOptions, Provider} from './blocks/oembed';
 
 const Resource = React.lazy(() => import('./ReactEmbed') as any);
 
diff --git a/src/stories/ReactEmbed.stories.tsx b/src/stories/ReactEmbed.stories.tsx
index b5a8f6d32..7894b42a9 100644
--- a/src/stories/ReactEmbed.stories.tsx
+++ b/src/stories/ReactEmbed.stories.tsx
@@ -127,10 +127,10 @@ export const Wrapper = {
 };
 
 const oEmbedUrls = [
-  'https://vimeo.com/54763818',
-  'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl',
   'https://www.flickr.com/photos/bees/2362225867/',
+  'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl',
   'https://codepen.io/anon/pen/YzPXoeb',
+  'https://speakerdeck.com/holman/git-and-github-secrets',
 ];
 
 export const OEmbedCard = {