@seed-ship/mcp-ui-solid 6.21.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/context/MCPUIConfigContext.tsx

@@ -1,5 +1,6 @@
 /**
- * MCPUIConfigContext — host-level rendering policy for the library's iframes.
+ * 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
  *
@@ -41,6 +42,23 @@ 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 {
   /**
@@ -60,7 +78,7 @@ export interface MCPUIConfig {
    * 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'
+  iframeCredentialless?: 'auto' | 'always' | 'never'
 
   /**
    * Extra hosts treated as trusted, on top of `TRUSTED_IFRAME_DOMAINS`:
@@ -71,21 +89,21 @@ export interface MCPUIConfig {
    * iframe whose host is outside `DEFAULT_IFRAME_DOMAINS`, add it to
    * {@link MCPUIConfig.customIframeDomains} with `iframePolicy: 'extend'`.
    */
-  customTrustedIframeDomains: string[]
+  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
+  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[]
+  customIframeDomains?: string[]
 
   /**
    * When the library renders an "open in a new tab" link under an embed
@@ -101,28 +119,61 @@ export interface MCPUIConfig {
    *   render, so SSR markup and hydration agree.
    * - `'always'` / `'never'` — unconditional.
    */
-  iframeFallbackLink: 'auto' | 'always' | 'never'
+  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.
+ * 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: MCPUIConfig = {
+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. Returns `DEFAULT_MCPUI_CONFIG` when no
- * `<MCPUIConfigProvider>` is mounted above.
+ * 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(): MCPUIConfig {
+export function useMCPUIConfig(): Required<MCPUIConfig> {
   return mergeProps(DEFAULT_MCPUI_CONFIG, useContext(MCPUIConfigContext))
 }
 

package/src/context/MCPUIStringsContext.tsx

@@ -274,6 +274,30 @@ export interface MCPUIStrings {
   /** `aria-label` of the lightbox "next image" button. */
   lightboxNext?: string
 
+  // ── Zoom controls (lightbox, chart) ────────────────────────
+  /**
+   * `aria-label` / `title` of the "zoom in" button.
+   * @since 6.22.0
+   */
+  zoomIn?: string
+  /**
+   * `aria-label` / `title` of the "zoom out" button.
+   * @since 6.22.0
+   */
+  zoomOut?: string
+  /**
+   * `aria-label` / `title` of the "reset zoom" button — the one the chart
+   * toolbar only shows while the chart is actually zoomed.
+   * @since 6.22.0
+   */
+  zoomReset?: string
+  /**
+   * Zoom-level readout next to the zoom buttons.
+   * Template — `{percent}` = the scale as a whole percentage (`100` at rest).
+   * @since 6.22.0
+   */
+  zoomLevel?: string
+
   // ── ModalRenderer ──────────────────────────────────────────
   /** `aria-label` of the modal close button. */
   modalClose?: string
@@ -1095,6 +1119,12 @@ export const DEFAULT_MCPUI_STRINGS: Required<MCPUIStrings> = {
 
   // ── 6.21.0 — iframe COEP fallback ──────────────────────────
   iframeOpenInNewTab: 'Open in a new tab',
+
+  // ── 6.22.0 — zoom / pan controls ───────────────────────────
+  zoomIn: 'Zoom in',
+  zoomOut: 'Zoom out',
+  zoomReset: 'Reset zoom',
+  zoomLevel: 'Zoom {percent}%',
 }
 
 /**

package/src/hooks/index.ts

@@ -59,6 +59,19 @@ export type {
   UseAutocompleteReturn,
 } from './useAutocomplete'
 
+// Pan/zoom primitive (v6.22.0). It lives under `src/utils` because it is pure
+// arithmetic plus two signals, but it is reactive and registers an onCleanup,
+// so it is used exactly like a hook — hence this re-export on the `./hooks`
+// subpath as well as on the root barrel.
+export { createPanZoom } from '../utils/pan-zoom'
+export type {
+  PanZoomOptions,
+  PanZoomController,
+  PanZoomState,
+  PanZoomPoint,
+  PanZoomCursor,
+} from '../utils/pan-zoom'
+
 // Data Validator hooks (v3.1.0 — anti-hallucination)
 export { useDataValidator } from './useDataValidator'
 export type {

package/src/index.ts

@@ -128,6 +128,22 @@ export type {
   DuplicateMountReporter,
 } from './utils/duplicate-mount-registry'
 
+// Cursor-anchored zoom + drag-pan primitive (v6.22.0 — lightbox, expanded views)
+export {
+  createPanZoom,
+  clampScale,
+  contentPointAt,
+  viewportPointOf,
+  zoomAtAnchor,
+} from './utils/pan-zoom'
+export type {
+  PanZoomOptions,
+  PanZoomController,
+  PanZoomState,
+  PanZoomPoint,
+  PanZoomCursor,
+} from './utils/pan-zoom'
+
 // Chrome i18n — library's own strings, EN defaults (v6.6.0 — D2/R4)
 export {
   MCPUIStringsProvider,

package/src/utils/iframe-coep.ts

@@ -26,10 +26,15 @@ import type { MCPUIConfig } from '../context/MCPUIConfigContext'
  * cookies and a COEP host must opt in with `'always'`.
  *
  * An unparsable URL is not trusted, so it gets the attribute.
+ *
+ * Takes a RESOLVED config (`Required<MCPUIConfig>` — what `useMCPUIConfig()`
+ * and `DEFAULT_MCPUI_CONFIG` hand out). `MCPUIConfig`'s own fields are
+ * optional so new keys stay backward compatible, and reading an unresolved
+ * one here would silently re-implement the defaults next to their source.
  */
 export function shouldSetCredentialless(
   url: string,
-  config: MCPUIConfig,
+  config: Required<MCPUIConfig>,
   options: { sandboxedWithoutSameOrigin: boolean }
 ): boolean {
   const mode = config.iframeCredentialless
@@ -62,9 +67,11 @@ export function createCrossOriginIsolated(): Accessor<boolean> {
  * `'auto'` shows it only on a cross-origin-isolated page — exactly where COEP
  * can block the frame, and where the blocking is silent (a refused
  * cross-origin document fires no `error` event the parent can observe).
+ *
+ * Takes a resolved config, for the reason given on `shouldSetCredentialless`.
  */
 export function shouldShowIframeFallbackLink(
-  config: MCPUIConfig,
+  config: Required<MCPUIConfig>,
   crossOriginIsolated: boolean
 ): boolean {
   const mode = config.iframeFallbackLink