@seed-ship/mcp-ui-solid 6.20.0 → 6.22.0

package/src/components/ChartJSRenderer.tsx

@@ -6,6 +6,15 @@
  * ```
  * pnpm add chart.js
  * ```
+ *
+ * Wheel-zoom / drag-pan / pinch (v6.22.0) need a SECOND optional peer, since a
+ * canvas cannot be zoomed with a CSS transform without blurring:
+ * ```
+ * pnpm add chartjs-plugin-zoom
+ * ```
+ * Without it the chart renders exactly as it did before 6.22.0. Where zoom is
+ * offered is the host's call — see `MCPUIConfig.chartZoom`, default
+ * `'expanded'` (fullscreen modal only).
  */
 
 import {
@@ -16,6 +25,7 @@ import {
   createUniqueId,
   onCleanup,
   createSignal,
+  untrack,
   Show,
 } from 'solid-js';
 import type { Accessor, JSX } from 'solid-js';
@@ -24,6 +34,7 @@ import { ExpandableWrapper, useExpanded } from './ExpandableWrapper';
 import { DegradedFallback } from './DegradedFallback';
 import { chartToDataTable } from './chart-data-table';
 import { useTelemetry } from '../context/MCPUITelemetryContext';
+import { useMCPUIConfig } from '../context/MCPUIConfigContext';
 import { formatMCPUIString, useMCPUIStrings } from '../context/MCPUIStringsContext';
 
 // Lazy load Chart.js to avoid bundling if not used
@@ -60,6 +71,184 @@ export async function isChartJSAvailable(): Promise<boolean> {
   }
 }
 
+// ─── Optional zoom peer (v6.22.0) ─────────────────────────────────────────
+//
+// A chart is a CANVAS, so the CSS-transform approach used by `createPanZoom`
+// for DOM surfaces would just magnify a bitmap into a blurry one. Real chart
+// zoom means re-projecting the scales, which only Chart.js itself can do —
+// hence `chartjs-plugin-zoom`, wired here as an OPTIONAL peer dependency
+// alongside `chart.js`, `leaflet` and `@antv/g6`. A host that does not install
+// it gets exactly the chart this renderer built before 6.22.0.
+
+let zoomPluginPromise: Promise<unknown | null> | null = null;
+let zoomPluginRegistered = false;
+
+/**
+ * Import `chartjs-plugin-zoom` once, lazily.
+ *
+ * Resolves to `null` instead of rejecting when the peer is absent: an optional
+ * dependency that is simply not installed is not an error condition, and the
+ * caller must be able to fall through to the unzoomable chart without an error
+ * state or console noise. The `null` is cached with the promise — a peer that
+ * is missing now is still missing on the next chart, and retrying the import
+ * per render would re-log the module-resolution failure every time.
+ *
+ * Only ever called from an effect, never at module scope or during render, so
+ * SSR never reaches `hammerjs` (a plugin dependency that reads `document` as
+ * it loads).
+ *
+ * `@vite-ignore` for the same reason `duckdb.ts` and `MapRenderer.tsx` carry
+ * it on THEIR optional peers: this library is built with the peer externalised,
+ * so the bare specifier survives into the published bundle and a consumer's
+ * bundler resolves it statically — an app that never installed the plugin then
+ * fails its own dependency scan at build time, long before the `.catch()`
+ * below could turn the absence into the supported `null`. The four peers that
+ * anyone using the feature at all has installed (`chart.js`, `leaflet`,
+ * `@antv/g6`, `highlight.js`) stay bare on purpose: they benefit from the
+ * pre-bundling this comment opts out of.
+ */
+const loadZoomPlugin = (): Promise<unknown | null> => {
+  if (!zoomPluginPromise) {
+    zoomPluginPromise = import(/* @vite-ignore */ 'chartjs-plugin-zoom')
+      .then((module: any) => module.default ?? module)
+      .catch(() => null);
+  }
+
+  return zoomPluginPromise;
+};
+
+/**
+ * Load the plugin and register it on the Chart.js singleton, once per process.
+ *
+ * Registration is global and not undoable, which is precisely why it is
+ * deferred to the first surface that actually asks for zoom
+ * (`MCPUIConfig.chartZoom`): with the default `'expanded'`, a chart sitting
+ * inline in a chat feed never even downloads the plugin.
+ *
+ * Chart.js only gives the plugin's hooks to charts constructed AFTER the
+ * `register()` call, so the caller rebuilds its chart once this resolves.
+ *
+ * Resolves to `null` on EVERY failure and never rejects. Its one call site is
+ * a fire-and-forget `.then()` inside an effect, with nowhere to put a rejection
+ * handler that would mean anything to the host: `loadZoomPlugin()` already
+ * swallows the missing optional peer, but `loadChartJS()` below rejects on a
+ * host that installed neither, and that rejection would surface as an
+ * unhandled one. The chart's own render effect reports the missing `chart.js`
+ * through `onError` and the degraded table; zoom just quietly is not offered.
+ */
+const ensureZoomPlugin = async (): Promise<unknown | null> => {
+  try {
+    const plugin = await loadZoomPlugin();
+    if (!plugin) return null;
+
+    if (!zoomPluginRegistered) {
+      const Chart: any = await loadChartJS();
+      // A stubbed or partial Chart build may not expose `register`; treat that
+      // like an absent peer. Returning the plugin here would be worse than
+      // returning nothing: the renderer would hang zoom options off a chart
+      // that has no zoom hooks, and paint a toolbar whose buttons do nothing.
+      if (typeof Chart?.register !== 'function') return null;
+
+      Chart.register(plugin);
+      // Set only now that a registration has actually happened, so a later
+      // call still gets its chance on a Chart build that does expose it.
+      zoomPluginRegistered = true;
+    }
+
+    return plugin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Chart types whose axes zoom meaningfully.
+ *
+ * `pie`, `doughnut`, `polarArea` and `radar` carry no cartesian scales, so the
+ * plugin would capture the wheel and move nothing — strictly worse than not
+ * offering zoom at all.
+ */
+const ZOOMABLE_CHART_TYPES = new Set(['bar', 'line', 'scatter', 'bubble']);
+
+/**
+ * Ratio one press of the chart's zoom buttons applies.
+ *
+ * The same 1.5 the lightbox uses for `+` / `-`: coarse enough that a couple of
+ * presses get somewhere, fine enough to stop on a region of interest.
+ */
+const CHART_ZOOM_BUTTON_FACTOR = 1.5;
+
+/**
+ * Whether a chart instance currently sits off its initial viewport.
+ *
+ * `isZoomedOrPanned()` is the plugin's own API (2.x). The `getZoomLevel()`
+ * branch covers an older plugin build that only exposes the zoom factor, and
+ * the `false` covers a chart created before the plugin was registered.
+ */
+const isChartZoomed = (chart: any): boolean => {
+  if (typeof chart?.isZoomedOrPanned === 'function') return Boolean(chart.isZoomedOrPanned());
+  const level = chart?.getZoomLevel?.();
+  return typeof level === 'number' ? level !== 1 : false;
+};
+
+/** A JSON-ish object — the only shape a zoom option tree is ever built from. */
+const isPlainZoomObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Deep-merge this renderer's zoom block with the consumer's own.
+ *
+ * `ChartComponentParams.options` is the public Chart.js escape hatch, and
+ * `plugins.zoom` is where a host tunes what this renderer cannot guess:
+ * `limits`, wheel `speed`, a pan `modifierKey`, its own callbacks. Spreading
+ * the renderer's block over it would silently drop the lot, so the two trees
+ * are merged branch by branch (`zoom.wheel`, `zoom.pinch`, `zoom.drag`, `pan`,
+ * `limits`, …).
+ *
+ * Two rules, both deliberate:
+ *   - on a plain value the CALLER wins — an explicit `mode: 'x'` is a more
+ *     specific instruction than this renderer's default `'xy'`;
+ *   - on a function both run, renderer first. The only functions the renderer
+ *     puts in that tree are `onZoom` / `onPan`, and they are what keeps the
+ *     reset control in sync with the viewport — letting a caller's callback
+ *     REPLACE them would leave the toolbar lying about the chart, so they are
+ *     composed instead.
+ */
+const mergeZoomOptions = (
+  base: Record<string, unknown>,
+  override: unknown
+): Record<string, unknown> => {
+  if (!isPlainZoomObject(override)) return base;
+
+  const merged: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(override)) {
+    // An explicitly-undefined key is an OMISSION, not an instruction to erase.
+    // A host forwarding an optional prop — `zoom: { onZoom: props.onZoom }`
+    // with nothing passed — would otherwise delete the renderer's own hook,
+    // which is exactly what keeps the reset control honest. This is also the
+    // semantics `mergeProps` gives every other merge in this package.
+    if (value === undefined) continue;
+
+    const ours = merged[key];
+
+    if (isPlainZoomObject(ours) && isPlainZoomObject(value)) {
+      merged[key] = mergeZoomOptions(ours, value);
+    } else if (typeof ours === 'function' && typeof value === 'function') {
+      const rendererHook = ours as (...args: unknown[]) => unknown;
+      const callerHook = value as (...args: unknown[]) => unknown;
+      merged[key] = (...args: unknown[]) => {
+        rendererHook(...args);
+        return callerHook(...args);
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+};
+
 export interface ChartJSRendererProps {
   /**
    * UIComponent with chart params
@@ -108,12 +297,20 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
   const [isLoading, setIsLoading] = createSignal(true);
   const [error, setError] = createSignal<string>();
   const [activeView, setActiveView] = createSignal<'chart' | 'data'>('chart');
+  // Reported by `<ExpandableWrapper onExpandedChange>` rather than read from
+  // `useExpanded()`: this component IS the wrapper's owner, so its own
+  // `useExpanded()` call sits above the wrapper's provider and would only ever
+  // see an outer wrapper (see ExpandableWrapperProps.onExpandedChange).
+  const [isExpanded, setIsExpanded] = createSignal(false);
+  const [zoomPlugin, setZoomPlugin] = createSignal<unknown | null>(null);
+  const [isZoomed, setIsZoomed] = createSignal(false);
   let canvasRef: HTMLCanvasElement | undefined;
   let chartInstance: any;
   let renderVersion = 0;
 
   const params = () => props.component.params as ChartComponentParams;
   const telemetry = useTelemetry();
+  const config = useMCPUIConfig();
   const strings = useMCPUIStrings();
   // The accessible data table is a pure projection: its column headers come
   // from the chrome strings, injected rather than hardcoded in the helper.
@@ -137,6 +334,107 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
   // Lazy-stringified each time the button is clicked.
   const copyDataJSON = () => JSON.stringify({ type: params().type, data: params().data }, null, 2);
 
+  // ── Zoom / pan (v6.22.0) ───────────────────────────────────────────────
+
+  /**
+   * Whether this chart should be capturing the wheel right now: the host
+   * policy (`MCPUIConfig.chartZoom`) crossed with the surface the chart
+   * currently lives on, and with the chart type.
+   *
+   * `'expanded'` (the default) only says yes inside `ExpandableWrapper`'s
+   * fullscreen modal — the one surface that owns its viewport. Inline, the
+   * wheel belongs to the page the chart is scrolling in.
+   */
+  const zoomWanted = createMemo(() => {
+    if (!ZOOMABLE_CHART_TYPES.has(params().type)) return false;
+    // `false` (or `null`) on the host's own `plugins.zoom` is Chart.js's
+    // documented per-chart plugin opt-out. It speaks about THIS chart, so it
+    // beats the host-wide `chartZoom` policy — and gating here rather than at
+    // the options merge keeps one source of truth, so the plugin is never even
+    // downloaded and the toolbar never offers controls that would do nothing.
+    const hostZoom = params().options?.plugins?.zoom;
+    if (hostZoom === false || hostZoom === null) return false;
+    const mode = config.chartZoom;
+    if (mode === 'never') return false;
+    if (mode === 'always') return true;
+    return isExpanded();
+  });
+
+  // Download + register the plugin the first time a surface asks for zoom.
+  // `zoomPlugin` is read untracked: setting it must not re-run this effect.
+  createEffect(() => {
+    if (!zoomWanted() || untrack(zoomPlugin)) return;
+    void ensureZoomPlugin().then((plugin) => {
+      if (plugin) setZoomPlugin(() => plugin);
+    });
+  });
+
+  /**
+   * The plugin's Chart.js options. Built once per renderer instance so that
+   * `zoomOptions()` keeps a STABLE identity: a fresh object each read would
+   * look like a config change and rebuild the chart on every update.
+   */
+  const zoomPluginOptions = {
+    zoom: {
+      wheel: { enabled: true },
+      pinch: { enabled: true },
+      // Drag is reserved for panning below; a drag-to-select zoom would make
+      // the two gestures fight over the same mouse button.
+      drag: { enabled: false },
+      mode: 'xy',
+      onZoom: ({ chart }: { chart: unknown }) => setIsZoomed(isChartZoomed(chart)),
+    },
+    pan: {
+      enabled: true,
+      mode: 'xy',
+      onPan: ({ chart }: { chart: unknown }) => setIsZoomed(isChartZoomed(chart)),
+    },
+  };
+
+  /**
+   * The `plugins.zoom` block to merge into the chart config, or `null`.
+   *
+   * `null` while the peer is absent, which keeps the built config byte-for-byte
+   * what it was before 6.22.0 — and, because the memo then never changes value,
+   * also keeps expanding the modal from rebuilding the chart at all on a host
+   * that did not install the plugin.
+   */
+  const zoomOptions = createMemo(() => (zoomWanted() && zoomPlugin() ? zoomPluginOptions : null));
+
+  /**
+   * Whether the zoom toolbar belongs on screen at all: the chart is zoomable
+   * here (host policy × surface × chart type, and the peer actually loaded),
+   * and the chart is what is currently being shown.
+   */
+  const zoomControlsShown = () =>
+    Boolean(zoomOptions()) && activeView() === 'chart' && !error();
+
+  /**
+   * Zoom the chart by a fixed ratio, about its centre.
+   *
+   * Every gesture the plugin offers — wheel, drag-pan, pinch — is a POINTER
+   * gesture, and the canvas is not focusable, so without these buttons the
+   * whole feature is unreachable by keyboard, switch or voice (WCAG 2.1.1) —
+   * including the reset control, which only exists once a gesture has already
+   * moved the chart. The lightbox settled the same question the same way, with
+   * persistent `+` / `-` controls next to its pointer gestures.
+   *
+   * `chart.zoom()` is `chartjs-plugin-zoom`'s own imperative API; the `?.`
+   * covers a chart built before the plugin was registered. The plugin calls
+   * `onZoom` itself, but the state is written here too so the reset control
+   * appears even on a build whose hook does not fire for a programmatic zoom.
+   */
+  const handleZoomBy = (factor: number) => {
+    chartInstance?.zoom?.(factor);
+    setIsZoomed(isChartZoomed(chartInstance));
+  };
+
+  /** Back to the chart's initial viewport. */
+  const handleResetZoom = () => {
+    chartInstance?.resetZoom?.();
+    setIsZoomed(false);
+  };
+
   // Chart PNG export
   const handleExportPNG = () => {
     if (!canvasRef) return;
@@ -151,8 +449,14 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
   createEffect(async () => {
     if (!canvasRef) return;
 
-    // Access params to track dependencies
+    // Access params to track dependencies. `zoomOptions()` is read here, before
+    // the first `await`, for the same reason: an async effect only tracks what
+    // it reads synchronously, and toggling the expanded state has to rebuild
+    // the chart rather than leave it on a stale config (Chart.js reads the
+    // plugin options at construction and the plugin only hooks charts created
+    // after it was registered).
     const chartParams = params();
+    const zoom = zoomOptions();
     const version = ++renderVersion;
 
     setIsLoading(true);
@@ -171,6 +475,7 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
       }
 
       // Build options, merging time-axis config if present (v3.1.0)
+      const hostZoomOptions = chartParams.options?.plugins?.zoom;
       const baseOptions: any = {
         responsive: true,
         maintainAspectRatio: false,
@@ -182,6 +487,14 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
             position: 'bottom',
             ...chartParams.options?.plugins?.legend,
           },
+          // Present only once the optional peer has loaded AND the current
+          // surface wants zoom. Merged rather than assigned, so a consumer's
+          // own `plugins.zoom` survives; when zoom is off, the spread above
+          // has already left their block exactly as they wrote it.
+          // An explicit `plugins.zoom: false` never reaches here: `zoomWanted`
+          // already returned false for it, so `zoom` is null and the spread
+          // above carries the host's own value through untouched.
+          ...(zoom ? { zoom: mergeZoomOptions(zoom, hostZoomOptions) } : {}),
         },
       };
 
@@ -211,6 +524,9 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
         options: baseOptions,
       });
 
+      // A freshly built chart always sits on its initial viewport, so the
+      // reset control goes away until the user zooms again.
+      setIsZoomed(false);
       setIsLoading(false);
     } catch (err) {
       if (version !== renderVersion) return;
@@ -252,6 +568,7 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
       copyData={copyDataJSON()}
       copyLabel={strings.chartCopy}
       toolbarVariant={props.toolbarVariant}
+      onExpandedChange={setIsExpanded}
     >
       <ContextAwareChartLayout
         render={(isExpanded) => (
@@ -297,6 +614,84 @@ export const ChartJSRenderer: Component<ChartJSRendererProps> = (props) => {
                 {strings.chartDataView}
               </button>
             </div>
+            {/* Zoom controls — permanently visible (not hover-revealed like
+                the export button) for as long as this chart is zoomable at
+                all. Zoom in/out come FIRST and unconditionally: they are the
+                only keyboard route into a feature whose gestures are all
+                pointer gestures, on a canvas that takes no focus. Reset joins
+                them only once the chart is actually off its initial viewport,
+                so the toolbar stays quiet on a chart nobody moved. */}
+            <Show when={zoomControlsShown()}>
+              <div class="inline-flex items-center gap-1">
+                <button
+                  type="button"
+                  onClick={() => handleZoomBy(1 / CHART_ZOOM_BUTTON_FACTOR)}
+                  class="opacity-60 hover:opacity-100 px-2 py-1 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-600 rounded-full hover:bg-gray-100 dark:hover:bg-gray-700 transition-all shadow-sm"
+                  title={strings.zoomOut}
+                  aria-label={strings.zoomOut}
+                >
+                  <svg
+                    class="w-3 h-3 text-gray-500 dark:text-gray-400"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                  >
+                    <path
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                      stroke-width="2"
+                      d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607zM13.5 10.5h-6"
+                    />
+                  </svg>
+                </button>
+
+                <button
+                  type="button"
+                  onClick={() => handleZoomBy(CHART_ZOOM_BUTTON_FACTOR)}
+                  class="opacity-60 hover:opacity-100 px-2 py-1 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-600 rounded-full hover:bg-gray-100 dark:hover:bg-gray-700 transition-all shadow-sm"
+                  title={strings.zoomIn}
+                  aria-label={strings.zoomIn}
+                >
+                  <svg
+                    class="w-3 h-3 text-gray-500 dark:text-gray-400"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                  >
+                    <path
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                      stroke-width="2"
+                      d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607zM10.5 7.5v6m3-3h-6"
+                    />
+                  </svg>
+                </button>
+
+                <Show when={isZoomed()}>
+                  <button
+                    type="button"
+                    onClick={handleResetZoom}
+                    class="opacity-60 hover:opacity-100 px-2 py-1 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-600 rounded-full hover:bg-gray-100 dark:hover:bg-gray-700 transition-all shadow-sm"
+                    title={strings.zoomReset}
+                    aria-label={strings.zoomReset}
+                  >
+                    <svg
+                      class="w-3 h-3 text-gray-500 dark:text-gray-400"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                    >
+                      <path
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        stroke-width="2"
+                        d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"
+                      />
+                    </svg>
+                  </button>
+                </Show>
+              </div>
+            </Show>
             <Show when={exportEnabled()}>
               <button
                 type="button"

package/src/components/ExpandableWrapper.tsx

@@ -113,7 +113,32 @@ export const ExpandableWrapper: Component<ExpandableWrapperProps> = (props) => {
     }
   })
 
+  /**
+   * Did the gesture that produced the current click START on the backdrop?
+   *
+   * `null` means no pointer press was seen — a synthetic or programmatic
+   * click, which stays allowed so keyboard and test-driven closes keep working.
+   */
+  let pressedOnBackdrop: boolean | null = null
+
+  const handleBackdropPointerDown = (e: PointerEvent) => {
+    pressedOnBackdrop = e.target === e.currentTarget
+  }
+
+  /**
+   * Closing on a backdrop click is only safe when the gesture also BEGAN there.
+   *
+   * When a press and its release have different targets the browser dispatches
+   * `click` on their nearest common ancestor — here the backdrop. So a drag
+   * that starts on the content and releases over the 16px margin around the
+   * panel (panning a zoomed chart, selecting text in a table) would otherwise
+   * land on this handler with `e.target === e.currentTarget` and tear the modal
+   * down mid-gesture.
+   */
   const handleBackdropClick = (e: MouseEvent) => {
+    const startedOnBackdrop = pressedOnBackdrop
+    pressedOnBackdrop = null
+    if (startedOnBackdrop === false) return
     if (e.target === e.currentTarget) handleClose()
   }
 
@@ -164,6 +189,7 @@ export const ExpandableWrapper: Component<ExpandableWrapperProps> = (props) => {
             class="fixed inset-0 z-50 flex flex-col bg-black/50 backdrop-blur-sm"
             style={{ animation: 'expandable-fade-in 0.15s ease-out' }}
             onClick={handleBackdropClick}
+            onPointerDown={handleBackdropPointerDown}
             role="dialog"
             data-mcp-ui-portal="dialog"
             aria-modal="true"

package/src/components/IframeFallbackLink.tsx

@@ -0,0 +1,57 @@
+/**
+ * IframeFallbackLink — the way out of a silently blocked embed.
+ *
+ * @since v6.21.0
+ *
+ * An iframe refused by `Cross-Origin-Embedder-Policy` fires no event the
+ * parent page can observe (`onerror` does not fire for a rejected
+ * cross-origin document), so the user is left with a blank frame and no
+ * explanation. This link, rendered under the frame, always works.
+ *
+ * Visibility follows `MCPUIConfig.iframeFallbackLink`; `'auto'` (the default)
+ * shows it only on a cross-origin-isolated page. The URL goes through
+ * `safeUrl` — an unsafe one renders nothing at all.
+ */
+
+import { createMemo, Show, type JSX } from 'solid-js'
+import { safeUrl } from '../utils/safe-url'
+import { useMCPUIStrings } from '../context/MCPUIStringsContext'
+import { useMCPUIConfig } from '../context/MCPUIConfigContext'
+import {
+  createCrossOriginIsolated,
+  shouldShowIframeFallbackLink,
+} from '../utils/iframe-coep'
+
+export interface IframeFallbackLinkProps {
+  /** The embedded URL. Bound to `href` only when `safeUrl` accepts it. */
+  url: string
+  /** Extra classes on the wrapping `<div>`. */
+  class?: string
+}
+
+export function IframeFallbackLink(props: IframeFallbackLinkProps): JSX.Element {
+  const strings = useMCPUIStrings()
+  const config = useMCPUIConfig()
+  const crossOriginIsolated = createCrossOriginIsolated()
+
+  const href = createMemo(() => safeUrl(props.url))
+  const visible = createMemo(
+    () => !!href() && shouldShowIframeFallbackLink(config, crossOriginIsolated())
+  )
+
+  return (
+    <Show when={visible()}>
+      <div class={`px-4 py-2 text-right ${props.class || ''}`}>
+        <a
+          href={href()}
+          target="_blank"
+          rel="noopener noreferrer"
+          data-mcp-ui-action="open-external"
+          class="text-xs text-blue-600 dark:text-blue-400 hover:underline focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 rounded"
+        >
+          {strings.iframeOpenInNewTab}
+        </a>
+      </div>
+    </Show>
+  )
+}