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

package/src/components/LightboxOverlay.tsx

@@ -1,13 +1,32 @@
 /**
  * LightboxOverlay - Fullscreen image viewer
  * Sprint 5: Media Components
+ *
+ * v6.22.0 — zoom & pan. The overlay is a fullscreen `<Portal>`: it OWNS the
+ * viewport, nothing scrolls behind it (the effect below locks `body`), so
+ * hijacking the wheel here is legitimate in a way it would not be for a
+ * component sitting inline in a chat feed. Zoom is therefore always on in the
+ * lightbox and needs no host opt-in.
  */
 
-import { Component, Show, createEffect, onCleanup } from 'solid-js'
+import { Component, Show, createEffect, createMemo, onCleanup } from 'solid-js'
 import { Portal } from 'solid-js/web'
 import type { GalleryImage } from '../types'
 import { safeUrl } from '../utils/safe-url'
-import { useMCPUIStrings } from '../context/MCPUIStringsContext'
+import { createPanZoom, type PanZoomPoint } from '../utils/pan-zoom'
+import { formatMCPUIString, useMCPUIStrings } from '../context/MCPUIStringsContext'
+
+/** Highest magnification of the lightbox — 8× the fitted size. */
+const MAX_ZOOM = 8
+
+/** Ratio one press of a zoom button (or of `+` / `-`) applies. */
+const ZOOM_BUTTON_FACTOR = 1.5
+
+/**
+ * Scale a double-click jumps to. Deliberately modest: a double-click is a
+ * coarse gesture, and the wheel is right there for the rest.
+ */
+const DOUBLE_CLICK_ZOOM = 2
 
 export interface LightboxOverlayProps {
   /**
@@ -33,6 +52,17 @@ export interface LightboxOverlayProps {
 
 export const LightboxOverlay: Component<LightboxOverlayProps> = (props) => {
   const strings = useMCPUIStrings()
+  let imageRef: HTMLImageElement | undefined
+
+  /**
+   * The handlers are bound on the BACKDROP, not on the `<img>`: a pan that
+   * drags the image out from under the cursor must keep receiving the pointer
+   * stream, and a wheel event over the black margin around a portrait image
+   * must still zoom. `target` therefore points the maths back at the image,
+   * which is the element that actually carries the transform.
+   */
+  const panZoom = createPanZoom({ min: 1, max: MAX_ZOOM, target: () => imageRef })
+
   const isOpen = () => props.selectedIndex !== null
   const currentImage = () =>
     props.selectedIndex !== null ? props.images[props.selectedIndex] : null
@@ -52,21 +82,129 @@ export const LightboxOverlay: Component<LightboxOverlayProps> = (props) => {
     }
   }
 
+  /**
+   * Identity of the picture on screen, as a VALUE rather than as an object
+   * reference — `null` while the overlay is closed.
+   *
+   * The index alone does not name a picture. A host that replaces `images`
+   * under a held `selectedIndex` — a gallery whose list streams in, a refilter,
+   * a re-render that rebuilds the array — puts a different photo on screen
+   * without the index ever moving. `url` and `srcset` are what the `<img>`
+   * below actually resolves, so together with the index they are what "the
+   * displayed image changed" has to mean. (`sizes` is left out on purpose: it
+   * re-picks among the candidates of the SAME picture, so it changes the
+   * resolution fetched, never the subject the zoom is framing.)
+   *
+   * A memo, and a string, so the comparison is by value: `ImageGalleryRenderer`
+   * passes `params()?.images || []`, a fresh array on every parent update, and
+   * re-reading that must not by itself count as a new picture — it would throw
+   * away a zoom the user is in the middle of. The index stays in the key so
+   * that navigating between two entries sharing a URL is still the clean slate
+   * the arrows promise.
+   */
+  const displayedImage = createMemo(() => {
+    if (props.selectedIndex === null) return null
+    const image = props.images[props.selectedIndex]
+    return JSON.stringify([props.selectedIndex, image?.url ?? null, image?.srcset ?? null])
+  })
+
+  /**
+   * Every image opens at its fitted size. Without this the transform left over
+   * from the previous picture would be applied to the next one — a 6× zoom on
+   * a corner of a portrait photo, carried onto a landscape one, shows black.
+   * It also settles the "arrows vs. panning" question: navigating away is
+   * always a clean slate rather than a frame half-belonging to two images.
+   *
+   * The dependency is `displayedImage()` and not `selectedIndex`, for the same
+   * reason: a swapped-out `images` array reaches the user as exactly that black
+   * frame — the old picture's scale and offset applied to a new photo — with no
+   * navigation to blame it on.
+   *
+   * `reset()` reads its state through `untrack`, so this effect subscribes to
+   * that one memo and never re-runs on its own write. The scale and offset it
+   * writes are absent from the memo for the same reason: panning must not
+   * reset the pan.
+   *
+   * `cancelGesture()` comes first, and matters most on the CLOSE (`null`): the
+   * pan handlers live on the backdrop, inside the `<Show>` below, but the
+   * controller belongs to this component — which `ImageGalleryRenderer` mounts
+   * once and never unmounts. Close the overlay with a button still held
+   * (Escape mid-drag) and the backdrop is detached before its `pointerup`,
+   * which is then delivered to whatever is underneath and never to these
+   * handlers. Nothing else would end that gesture: `reset()` only writes the
+   * transform, and `onCleanup` belongs to an owner that is still alive. The
+   * overlay would reopen stuck at `cursor: grabbing`, with `isPanning()` true
+   * and the arrow keys dead behind their pan guards.
+   */
+  createEffect(() => {
+    displayedImage()
+    panZoom.cancelGesture()
+    panZoom.reset()
+  })
+
+  /**
+   * Is the keystroke going into something the user is typing in?
+   *
+   * The overlay binds its shortcuts on `document`, so it hears every key in
+   * the page — and it does not trap focus, so the host's own composer can keep
+   * it while the lightbox is open (`Tab` from the thumbnail that opened the
+   * overlay walks on into the host, since the `<Portal>` content is appended
+   * after it). The zoom keys are `-`, `+`, `=` and `0`: characters. Calling
+   * `preventDefault()` on them without this check silently eats them out of
+   * the host's text field — typing a date would zoom the photo instead.
+   *
+   * `Escape` stays global, as it was before the zoom keys existed: it produces
+   * no character, and dismissing the modal is what it is for.
+   */
+  const isEditableTarget = (target: EventTarget | null): boolean => {
+    if (!(target instanceof HTMLElement)) return false
+    if (target.isContentEditable) return true
+    return ['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName)
+  }
+
   // Keyboard navigation
   createEffect(() => {
     if (!isOpen()) return
 
     const handleKeydown = (e: KeyboardEvent) => {
+      // Ctrl/Cmd + `+` / `-` / `0` is the browser's own page zoom; the overlay
+      // must not swallow it.
+      const isZoomChord = e.ctrlKey || e.metaKey
+
+      // A field the user is typing in owns its keys — all of them but the one
+      // that dismisses a modal.
+      if (e.key !== 'Escape' && isEditableTarget(e.target)) return
+
       switch (e.key) {
         case 'Escape':
           props.onClose()
           break
         case 'ArrowLeft':
+          // Mid-drag the arrows would move the picture the user is holding.
+          if (panZoom.isPanning()) break
           handlePrev()
           break
         case 'ArrowRight':
+          if (panZoom.isPanning()) break
           handleNext()
           break
+        case '+':
+        case '=':
+          // `=` is `+` unshifted — the key people actually press.
+          if (isZoomChord) break
+          e.preventDefault()
+          panZoom.zoomBy(ZOOM_BUTTON_FACTOR)
+          break
+        case '-':
+          if (isZoomChord) break
+          e.preventDefault()
+          panZoom.zoomBy(1 / ZOOM_BUTTON_FACTOR)
+          break
+        case '0':
+          if (isZoomChord) break
+          e.preventDefault()
+          panZoom.reset()
+          break
       }
     }
 
@@ -79,12 +217,74 @@ export const LightboxOverlay: Component<LightboxOverlayProps> = (props) => {
     })
   })
 
+  /**
+   * Closing on a backdrop click is the behaviour users expect — but a pan
+   * releases the pointer over the backdrop as often as not, and the browser
+   * then fires a `click` on the common ancestor of the press and the release.
+   * `wasDragged()` is exactly that distinction: it stays true from the moment
+   * the pointer travelled more than a few pixels until the next `pointerdown`,
+   * so the click that closes the overlay is only ever a click that did not move.
+   */
+  const handleBackdropClick = () => {
+    if (panZoom.wasDragged()) return
+    props.onClose()
+  }
+
+  /**
+   * The chrome (close, prev/next, the zoom toolbar) sits on top of the pan
+   * surface. Pressing a button must not open a gesture: while zoomed
+   * `onPointerDown` calls `preventDefault()`, which costs the button its focus,
+   * and a hand that shakes on the way to "next" would pan the image instead.
+   */
+  const handlePointerDown = (event: PointerEvent) => {
+    const target = event.target
+    if (target instanceof Element && target.closest('button')) return
+    panZoom.onPointerDown(event)
+  }
+
+  /**
+   * Viewport point of a mouse event, in the space `zoomTo` anchors on: client
+   * pixels measured from the image's UNTRANSFORMED top-left corner. That corner
+   * is not directly observable — `getBoundingClientRect()` already includes the
+   * transform — but with `transform-origin: 0 0` the rendered left edge is
+   * exactly `corner + offset`, so subtracting the current offset recovers it
+   * whatever the flex centring did.
+   *
+   * `createPanZoom` computes the same point for the wheel but keeps it private;
+   * this is the double-click's copy of it.
+   */
+  const anchorOf = (event: MouseEvent): PanZoomPoint | undefined => {
+    if (!imageRef) return undefined
+    const rect = imageRef.getBoundingClientRect()
+    const offset = panZoom.offset()
+    return {
+      x: event.clientX - (rect.left - offset.x),
+      y: event.clientY - (rect.top - offset.y),
+    }
+  }
+
+  /** Double-click toggles: in at the spot that was double-clicked, or back out. */
+  const handleDoubleClick = (event: MouseEvent) => {
+    event.stopPropagation()
+    if (panZoom.isZoomed()) {
+      panZoom.reset()
+    } else {
+      panZoom.zoomTo(DOUBLE_CLICK_ZOOM, anchorOf(event))
+    }
+  }
+
   return (
     <Show when={isOpen()}>
       <Portal>
         <div
           class="fixed inset-0 z-50 bg-black/90 flex items-center justify-center"
-          onClick={props.onClose}
+          style={panZoom.surfaceStyle()}
+          onClick={handleBackdropClick}
+          onWheel={panZoom.onWheel}
+          onPointerDown={handlePointerDown}
+          onPointerMove={panZoom.onPointerMove}
+          onPointerUp={panZoom.onPointerUp}
+          onPointerCancel={panZoom.onPointerCancel}
           role="dialog"
           aria-modal="true"
           aria-label={strings.lightboxLabel}
@@ -147,14 +347,18 @@ export const LightboxOverlay: Component<LightboxOverlayProps> = (props) => {
             </button>
           </Show>
 
-          {/* Image */}
+          {/* Image — `max-w/max-h` fit it, the transform zooms it from there */}
           <img
+            ref={imageRef}
             src={safeUrl(currentImage()?.url ?? '', { allowDataImage: true })}
             alt={currentImage()?.alt || ''}
             srcset={currentImage()?.srcset}
             sizes={currentImage()?.sizes}
             class="max-w-[90vw] max-h-[90vh] object-contain"
+            style={panZoom.contentStyle()}
+            draggable={false}
             onClick={(e) => e.stopPropagation()}
+            onDblClick={handleDoubleClick}
           />
 
           {/* Caption */}
@@ -168,6 +372,78 @@ export const LightboxOverlay: Component<LightboxOverlayProps> = (props) => {
           <div class="absolute top-4 left-4 text-white/80 bg-black/40 px-3 py-1 rounded-full text-sm">
             {(props.selectedIndex ?? 0) + 1} / {props.images.length}
           </div>
+
+          {/* Zoom controls — the pointer-only gestures made reachable by
+              keyboard and touch. The wrapper swallows the click so the
+              backdrop's close handler never sees it. */}
+          <div
+            class="absolute bottom-4 left-1/2 -translate-x-1/2 flex items-center gap-1 bg-black/50 rounded-full px-2 py-1"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <button
+              class="text-white/80 hover:text-white p-2 rounded-full hover:bg-white/10 transition-colors disabled:opacity-40 disabled:hover:bg-transparent"
+              onClick={() => panZoom.zoomBy(1 / ZOOM_BUTTON_FACTOR)}
+              disabled={panZoom.scale() <= panZoom.min}
+              aria-label={strings.zoomOut}
+              title={strings.zoomOut}
+              type="button"
+            >
+              <svg class="w-5 h-5" 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>
+
+            <span
+              class="text-white/80 text-xs tabular-nums text-center min-w-[4rem]"
+              aria-live="polite"
+            >
+              {formatMCPUIString(strings.zoomLevel, { percent: panZoom.percent() })}
+            </span>
+
+            <button
+              class="text-white/80 hover:text-white p-2 rounded-full hover:bg-white/10 transition-colors disabled:opacity-40 disabled:hover:bg-transparent"
+              onClick={() => panZoom.zoomBy(ZOOM_BUTTON_FACTOR)}
+              disabled={panZoom.scale() >= panZoom.max}
+              aria-label={strings.zoomIn}
+              title={strings.zoomIn}
+              type="button"
+            >
+              <svg class="w-5 h-5" 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>
+
+            {/* Only while there is something to reset — at 100% it would be a
+                button that does nothing. */}
+            <Show when={panZoom.isZoomed()}>
+              <button
+                class="text-white/80 hover:text-white p-2 rounded-full hover:bg-white/10 transition-colors"
+                onClick={() => panZoom.reset()}
+                aria-label={strings.zoomReset}
+                title={strings.zoomReset}
+                type="button"
+              >
+                <svg class="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    stroke-width="2"
+                    d="M16.023 9.348h4.992V4.356m0 4.992l-3.181-3.183a8.25 8.25 0 00-13.803 3.7M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0013.803-3.7"
+                  />
+                </svg>
+              </button>
+            </Show>
+          </div>
         </div>
       </Portal>
     </Show>

package/src/components/UIResourceRenderer.tsx

@@ -10,7 +10,7 @@ import { escapeHtml } from '../utils/escape-html'
 import { safeUrl } from '../utils/safe-url'
 import { SafeHtml } from './SafeHtml'
 import type { UIComponent, UILayout, RendererError, TableVirtualizeOptions } from '../types'
-import { validateComponent, DEFAULT_RESOURCE_LIMITS, getIframeSandbox } from '../services/validation'
+import { validateComponent, DEFAULT_RESOURCE_LIMITS, getIframeSandbox, isTrustedIframeDomain } from '../services/validation'
 import { GenerativeUIErrorBoundary } from './GenerativeUIErrorBoundary'
 import { markRenderStart, markRenderEnd, PERF_PREFIX } from '../utils/perf'
 import { isDebugEnabled } from '../utils/logger'
@@ -27,6 +27,9 @@ import {
   formatMCPUIString,
   useMCPUIStrings,
 } from '../context/MCPUIStringsContext'
+import { useMCPUIConfig } from '../context/MCPUIConfigContext'
+import { shouldSetCredentialless } from '../utils/iframe-coep'
+import { IframeFallbackLink } from './IframeFallbackLink'
 
 /**
  * How `<UIResourceRenderer>` reacts when `validateComponent()` rejects a
@@ -1458,7 +1461,12 @@ function TextRenderer(props: { component: UIComponent }) {
  */
 function IframeRenderer(props: { component: UIComponent }) {
   const strings = useMCPUIStrings()
+  const config = useMCPUIConfig()
   const params = props.component.params as any
+  // v6.21.0 — the host's custom trusted hosts now reach BOTH the sandbox (they
+  // used not to: `getIframeSandbox(params.url)` was called with no options) and
+  // the `credentialless` decision.
+  const trustOptions = () => ({ customTrustedDomains: config.customTrustedIframeDomains })
   return (
     <div class="w-full h-full bg-white dark:bg-gray-800 rounded-lg shadow-sm border border-gray-200 dark:border-gray-700 overflow-hidden flex flex-col">
       <Show when={params.title}>
@@ -1471,9 +1479,22 @@ function IframeRenderer(props: { component: UIComponent }) {
         title={params.title || strings.iframeTitle}
         class="w-full border-0 flex-1"
         style={`height: ${params.height || '400px'}; min-height: 300px;`}
-        sandbox={getIframeSandbox(params.url)}
+        sandbox={getIframeSandbox(params.url, trustOptions())}
+        // `attr:` is required: `credentialless` is in dom-expressions'
+        // `Properties` set, so a plain `credentialless={…}` compiles to a JS
+        // property assignment and never reaches the DOM as an attribute.
+        // `true | undefined` keeps it a BOOLEAN attribute — bare in SSR
+        // markup, removed (not `="false"`) when it does not apply.
+        attr:credentialless={
+          shouldSetCredentialless(params.url, config, {
+            // This iframe's sandbox never carries `allow-same-origin` for an
+            // untrusted host, so it already runs without cookies.
+            sandboxedWithoutSameOrigin: !isTrustedIframeDomain(params.url, trustOptions()),
+          }) || undefined
+        }
         loading="lazy"
       />
+      <IframeFallbackLink url={params.url} class="border-t border-gray-200 dark:border-gray-700" />
     </div>
   )
 }
@@ -1595,6 +1616,7 @@ function ComponentRenderer(props: {
   // opt in see zero behavior change.
   const telemetry = useTelemetry()
   const strings = useMCPUIStrings()
+  const componentConfig = useMCPUIConfig()
 
   onMount(() => {
     markRenderEnd(props.component.id)
@@ -1636,8 +1658,13 @@ function ComponentRenderer(props: {
     }
   })
 
-  // Validate component before rendering
-  const validation = validateComponent(props.component)
+  // Validate component before rendering. The host's allow-list extension
+  // (v6.21.0) has to reach validation too: an unlisted host is replaced by the
+  // validation card before any renderer runs.
+  const validation = validateComponent(props.component, {
+    iframePolicy: componentConfig.iframePolicy,
+    customIframeDomains: componentConfig.customIframeDomains,
+  })
   if (!validation.valid) {
     props.onError?.({
       type: 'validation',

package/src/components/VideoRenderer.tsx

@@ -9,6 +9,9 @@ import { Component, createMemo, Show } from 'solid-js'
 import type { UIComponent, VideoComponentParams } from '../types'
 import { ExpandableWrapper, useExpanded } from './ExpandableWrapper'
 import { useMCPUIStrings } from '../context/MCPUIStringsContext'
+import { useMCPUIConfig } from '../context/MCPUIConfigContext'
+import { shouldSetCredentialless } from '../utils/iframe-coep'
+import { IframeFallbackLink } from './IframeFallbackLink'
 
 export interface VideoRendererProps {
   /**
@@ -76,6 +79,7 @@ function parseVideoUrl(url: string): VideoInfo {
 
 export const VideoRenderer: Component<VideoRendererProps> = (props) => {
   const strings = useMCPUIStrings()
+  const config = useMCPUIConfig()
   const params = () => props.params || (props.component?.params as VideoComponentParams)
   const isExpanded = useExpanded()
 
@@ -181,11 +185,27 @@ export const VideoRenderer: Component<VideoRendererProps> = (props) => {
             class="absolute inset-0 w-full h-full"
             allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
             allowfullscreen
+            // v6.21.0 — youtube-nocookie / player.vimeo are not trusted hosts,
+            // so under COEP `credentialless` is what lets them load at all.
+            // `attr:` + `true | undefined` — see the note in `IframeRenderer`.
+            attr:credentialless={
+              // No sandbox here: a YouTube/Vimeo embed keeps its provider
+              // cookies, so `'auto'` leaves it alone and a COEP host opts in
+              // with `iframeCredentialless: 'always'`.
+              shouldSetCredentialless(embedUrl()!, config, {
+                sandboxedWithoutSameOrigin: false,
+              }) || undefined
+            }
             loading="lazy"
           />
         </Show>
       </div>
 
+      {/* v6.21.0 — a COEP-blocked embed is silent; this link is the way out. */}
+      <Show when={embedUrl()}>
+        <IframeFallbackLink url={params()?.url || ''} />
+      </Show>
+
       {/* Caption */}
       <Show when={params()?.caption}>
         <div class="px-4 py-3 border-t border-gray-200 dark:border-gray-700 flex-shrink-0">

package/src/context/MCPUIConfigContext.tsx

@@ -0,0 +1,202 @@
+/**
+ * MCPUIConfigContext — host-level rendering policy: the library's iframes
+ * (v6.21.0) and, since v6.22.0, where a chart may capture the wheel.
+ *
+ * @since v6.21.0
+ *
+ * ## Why
+ *
+ * A host that serves `Cross-Origin-Embedder-Policy: credentialless` makes the
+ * browser refuse every cross-origin iframe whose own document does not send a
+ * COEP header — which is YouTube, Vimeo, Google Docs, Notion and nearly all of
+ * `DEFAULT_IFRAME_DOMAINS`. The escape hatch is the boolean HTML attribute
+ * `credentialless` on the `<iframe>` itself: the document then loads, but
+ * without access to the cookies and storage of its own origin.
+ *
+ * That trade-off is free for a public video or chart and fatal for an
+ * authenticated embed, so the library keys it on the distinction it already
+ * makes: `TRUSTED_IFRAME_DOMAINS` (the hosts that receive `allow-same-origin`
+ * because they need their own cookies) do NOT get the attribute; everything
+ * else does. This context lets a host override that, add its own trusted
+ * hosts, and control the "open in a new tab" fallback link.
+ *
+ * ## Scope — policy only, NOT strings
+ *
+ * Text lives in `MCPUIStrings` (`MCPUIStringsContext`). This context carries
+ * only behavioural switches, and like the strings context every renderer works
+ * standalone: with no provider mounted, `DEFAULT_MCPUI_CONFIG` applies.
+ *
+ * @example
+ * ```tsx
+ * import { MCPUIConfigProvider } from '@seed-ship/mcp-ui-solid'
+ *
+ * <MCPUIConfigProvider config={{ customTrustedIframeDomains: ['embed.acme.com'] }}>
+ *   <App />
+ * </MCPUIConfigProvider>
+ * ```
+ */
+
+import { createContext, mergeProps, useContext, type JSX } from 'solid-js'
+import type { IframePolicy } from '../types'
+
+/**
+ * Host-level rendering policy. Every field has a default — a provider passes
+ * a partial override.
+ *
+ * ## Why every field is optional
+ *
+ * This interface grows a key every time the library gains a policy switch,
+ * and those releases are MINOR. Were the fields required, adding one would
+ * break the build of any consumer holding a COMPLETE `MCPUIConfig` value —
+ * a typed constant, a helper that returns one, or a direct
+ * `<MCPUIConfigContext.Provider value={…}>` — because their object would
+ * suddenly miss a key. Nothing about their behaviour changed; only `tsc`
+ * would fail. Optional fields make each new key additive.
+ *
+ * The completeness guarantee moves from the type to the two values that
+ * actually need it, exactly as `MCPUIStrings` does it:
+ * `DEFAULT_MCPUI_CONFIG` is `Required<MCPUIConfig>`, so forgetting a default
+ * is a compile error HERE, and {@link useMCPUIConfig} returns
+ * `Required<MCPUIConfig>`, so every renderer still reads a fully resolved
+ * value and never has to null-check a policy.
+ */
+export interface MCPUIConfig {
+  /**
+   * When the library puts the boolean `credentialless` attribute on an
+   * `<iframe>` it renders.
+   *
+   * - `'auto'` (default) — on every iframe whose host is NOT in
+   *   `TRUSTED_IFRAME_DOMAINS` (plus `customTrustedIframeDomains`). Those
+   *   hosts already ran without cookies, since their sandbox has no
+   *   `allow-same-origin`; the attribute is what unblocks them under COEP.
+   * - `'always'` — on every iframe, trusted hosts included. An authenticated
+   *   embed will then render its login screen.
+   * - `'never'` — never. The right value for a host that sends no COEP header
+   *   and does not want its embeds to lose their cookies.
+   *
+   * Chrome/Edge 110+ honour the attribute; Firefox ignores it (iframes stay
+   * blocked while the host sends COEP); Safari ignores the COEP value itself,
+   * so nothing is blocked there in the first place.
+   */
+  iframeCredentialless?: 'auto' | 'always' | 'never'
+
+  /**
+   * Extra hosts treated as trusted, on top of `TRUSTED_IFRAME_DOMAINS`:
+   * no `credentialless` attribute, and `allow-same-origin` in the sandbox.
+   * A subdomain of a listed host matches too.
+   *
+   * This only RECLASSIFIES a host the allow-list already accepts. To render an
+   * iframe whose host is outside `DEFAULT_IFRAME_DOMAINS`, add it to
+   * {@link MCPUIConfig.customIframeDomains} with `iframePolicy: 'extend'`.
+   */
+  customTrustedIframeDomains?: string[]
+
+  /**
+   * How `UIResourceRenderer` validates an `iframe` component's host:
+   * `'strict'` (default) accepts `DEFAULT_IFRAME_DOMAINS` only, `'extend'`
+   * also accepts {@link MCPUIConfig.customIframeDomains}.
+   */
+  iframePolicy?: IframePolicy
+
+  /**
+   * Extra hosts the allow-list accepts when `iframePolicy` is `'extend'`.
+   * Without this, a component pointing at an unlisted host is replaced by the
+   * validation card before any renderer runs.
+   */
+  customIframeDomains?: string[]
+
+  /**
+   * When the library renders an "open in a new tab" link under an embed
+   * (`strings.iframeOpenInNewTab`).
+   *
+   * A COEP-blocked iframe fires no event the parent page can observe, so
+   * without this the user sees an unexplained blank frame.
+   *
+   * - `'auto'` (default) — only when the page is cross-origin isolated
+   *   (`window.crossOriginIsolated`). That flag needs COOP `same-origin` AND
+   *   COEP, so a host that sends COEP alone still blocks embeds while the
+   *   flag is false: set `'always'` there. Read after mount, never during
+   *   render, so SSR markup and hydration agree.
+   * - `'always'` / `'never'` — unconditional.
+   */
+  iframeFallbackLink?: 'auto' | 'always' | 'never'
+
+  /**
+   * Where `ChartJSRenderer` enables wheel-zoom / drag-pan / pinch on a chart
+   * (through the optional `chartjs-plugin-zoom` peer dependency — absent, the
+   * chart renders exactly as it does without this setting).
+   *
+   * Hijacking the mouse wheel on a component sitting inline in a scrolling
+   * chat feed is hostile: the user scrolls the conversation and the chart eats
+   * the gesture. So zoom belongs to a surface that OWNS its viewport, which
+   * here is `ExpandableWrapper`'s fullscreen modal.
+   *
+   * - `'expanded'` (default) — only inside the fullscreen modal.
+   * - `'always'` — inline as well. For a host that lays charts out in a
+   *   dashboard rather than in a feed, where the wheel has nothing to steal.
+   * - `'never'` — off everywhere; the plugin is never registered.
+   *
+   * @since 6.22.0
+   */
+  chartZoom?: 'expanded' | 'always' | 'never'
+}
+
+/**
+ * Defaults. Chosen so a host that sends no COEP header sees no change from
+ * 6.20.0 apart from the fallback link, which `'auto'` keeps hidden there —
+ * and, since 6.22.0, so no inline component ever captures the wheel
+ * (`chartZoom: 'expanded'`).
+ *
+ * Typed `Required<MCPUIConfig>`: the interface's fields are optional so that
+ * adding one stays backward compatible, and this annotation is what keeps a
+ * new key from shipping without a default.
+ */
+export const DEFAULT_MCPUI_CONFIG: Required<MCPUIConfig> = {
+  iframeCredentialless: 'auto',
+  customTrustedIframeDomains: [],
+  iframePolicy: 'strict',
+  customIframeDomains: [],
+  iframeFallbackLink: 'auto',
+  chartZoom: 'expanded',
+}
+
+/**
+ * Deliberately typed with the PARTIAL `MCPUIConfig`, not `Required<…>`: a
+ * host that bypasses `MCPUIConfigProvider` and feeds this provider directly
+ * may pass whichever keys it cares about, and `useMCPUIConfig` fills the
+ * rest. Widening it this way only ever accepts more than before.
+ */
+export const MCPUIConfigContext = createContext<MCPUIConfig>(DEFAULT_MCPUI_CONFIG)
+
+/**
+ * Reads the active host config, resolved: every key is present, whether it
+ * came from the provider or from `DEFAULT_MCPUI_CONFIG`. Returns the defaults
+ * outright when no `<MCPUIConfigProvider>` is mounted above.
+ */
+export function useMCPUIConfig(): Required<MCPUIConfig> {
+  return mergeProps(DEFAULT_MCPUI_CONFIG, useContext(MCPUIConfigContext))
+}
+
+export interface MCPUIConfigProviderProps {
+  /**
+   * Partial override of the host config. Any key left unset falls back to
+   * `DEFAULT_MCPUI_CONFIG`.
+   */
+  config?: Partial<MCPUIConfig>
+  children: JSX.Element
+}
+
+/**
+ * Provides the host config to every MCP-UI renderer below it.
+ * Merges the partial `config` override over the defaults.
+ */
+export function MCPUIConfigProvider(props: MCPUIConfigProviderProps): JSX.Element {
+  // The function source keeps replacement `config` objects reactive while
+  // mergeProps fills any omitted key without taking a one-time snapshot.
+  const value = mergeProps(DEFAULT_MCPUI_CONFIG, () => props.config)
+  return (
+    <MCPUIConfigContext.Provider value={value}>
+      {props.children}
+    </MCPUIConfigContext.Provider>
+  )
+}