@seed-ship/mcp-ui-solid 6.21.0 → 6.23.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

@@ -67,6 +67,8 @@ import { RenderProvider } from './RenderContext'
 import { useAction } from '../hooks/useAction'
 import { createResponsiveGrid } from '../hooks/createResponsiveGrid'
 import { marked } from 'marked'
+import { useMCPUIMath, type MathRenderer } from '../context/MCPUIMathContext'
+import { parseMathMarkdown } from '../utils/math-markdown'
 
 /**
  * Copy button component with visual feedback
@@ -443,6 +445,9 @@ export function highlightQuery(html: string, query: string): string {
   const walker = document.createTreeWalker(template.content, NodeFilter.SHOW_TEXT)
   const textNodes: Text[] = []
   for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    // A HTML <mark> inside MathML can change or break its layout/semantics.
+    // Keep formulas intact; ordinary text around them remains searchable.
+    if (node.parentElement?.closest('math')) continue
     textNodes.push(node as Text)
   }
 
@@ -595,7 +600,7 @@ function transformCellCitations(text: string, ctx: CitationCtx): string {
   )
 }
 
-export function renderCellValue(value: any, citationCtx?: CitationCtx): string {
+export function renderCellValue(value: any, citationCtx?: CitationCtx, mathRenderer?: MathRenderer): string {
   // Handle null/undefined
   if (value === null || value === undefined) {
     return '-'
@@ -646,6 +651,18 @@ export function renderCellValue(value: any, citationCtx?: CitationCtx): string {
     return '-'
   }
 
+  // Math must be tokenized before Markdown or citation rewrites can consume
+  // TeX underscores or bracket arguments (e.g. \sqrt[3]{x}). The opt-in path
+  // transforms citations only in ordinary text tokens, never math/code/URLs.
+  if (mathRenderer && strValue.includes('$')) {
+    return parseMathMarkdown(
+      strValue,
+      mathRenderer,
+      'cellMarkdown',
+      citationCtx ? (text) => transformCellCitations(text, citationCtx) : undefined,
+    )
+  }
+
   // Detect and convert markdown links: [text](url) — runs FIRST because
   // the citation transform's negative lookahead `(?!\()` would also skip
   // these, but handling them here keeps the existing return path.
@@ -706,6 +723,7 @@ function TableRenderer(props: {
   const tableParams = props.component.params as any
   let scrollContainerRef: HTMLDivElement | undefined
   const strings = useMCPUIStrings()
+  const mathRenderer = useMCPUIMath()
 
   // v5.7.0 — opt-in citation chip rendering inside cells. When `citationMap`
   // is present in params, build a CitationCtx once and thread it through
@@ -1006,7 +1024,7 @@ function TableRenderer(props: {
             <For each={tableParams.columns}>
               {(column: any) => (
                 <td class="px-6 py-4 text-sm text-gray-700 dark:text-gray-200 whitespace-normal break-words leading-relaxed first:pl-6 last:pr-6">
-                  <SafeHtml html={() => highlightQuery(renderCellValue(row[column.key], citationCtx), debouncedQuery())} />
+                  <SafeHtml html={() => highlightQuery(renderCellValue(row[column.key], citationCtx, mathRenderer()), debouncedQuery())} />
                 </td>
               )}
             </For>
@@ -1045,7 +1063,7 @@ function TableRenderer(props: {
                 <For each={tableParams.columns}>
                   {(column: any) => (
                     <td class="px-6 py-4 text-sm text-gray-700 dark:text-gray-200 whitespace-normal break-words leading-relaxed first:pl-6 last:pr-6">
-                      <SafeHtml html={() => highlightQuery(renderCellValue(row[column.key], citationCtx), debouncedQuery())} />
+                      <SafeHtml html={() => highlightQuery(renderCellValue(row[column.key], citationCtx, mathRenderer()), debouncedQuery())} />
                     </td>
                   )}
                 </For>
@@ -1362,6 +1380,7 @@ function extractImageFromMarkdown(
  */
 function TextRenderer(props: { component: UIComponent }) {
   const strings = useMCPUIStrings()
+  const mathRenderer = useMCPUIMath()
   const textParams = props.component.params as any
 
   // Check if this is an image markdown that should be rendered as image
@@ -1399,6 +1418,8 @@ function TextRenderer(props: { component: UIComponent }) {
       return escapeHtml(String(raw))
     }
     if (textParams.markdown && !imageData()) {
+      const renderMath = mathRenderer()
+      if (renderMath) return parseMathMarkdown(String(raw), renderMath, 'prose')
       return sanitizeHtml(marked.parse(raw, { async: false }) as string, SANITIZE_PROFILES.prose)
     }
     return sanitizeHtml(String(raw), SANITIZE_PROFILES.prose)

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,8 +42,35 @@ import type { IframePolicy } from '../types'
 /**
  * Host-level rendering policy. Every field has a default — a provider passes
  * a partial override.
+ *
+ * ## Two names, because there are two jobs
+ *
+ * This type grows a key every time the library gains a policy switch, and
+ * those releases are MINOR — so neither AUTHORING a config nor READING one
+ * may break when a key appears. Those two demands pull in opposite
+ * directions, and one name cannot serve both:
+ *
+ * - an author must be allowed to omit the new key, so the fields they write
+ *   have to be OPTIONAL;
+ * - a reader assigning `const p: IframePolicy = config.iframePolicy` must not
+ *   suddenly face `undefined`, so the fields they read have to be REQUIRED.
+ *
+ * Hence {@link MCPUIConfigInput} (what a host writes — every field optional)
+ * and {@link MCPUIConfig} (what the library hands back — every field
+ * resolved). `MCPUIConfig` is derived from the input type, so the two can
+ * never drift and a key is declared exactly once.
+ *
+ * Which one you name depends on the surface:
+ *
+ * - `<MCPUIConfigProvider config={…}>` takes `MCPUIConfigInput` — name that
+ *   type for a partial you build, and it merges the rest;
+ * - `<MCPUIConfigContext.Provider value={…}>` takes the RESOLVED
+ *   `MCPUIConfig`, because that context is read as well as written, so a
+ *   direct provider hands over `{ ...DEFAULT_MCPUI_CONFIG, ...mine }`;
+ * - anything you RECEIVE is `MCPUIConfig`, which is what
+ *   {@link useMCPUIConfig} returns.
  */
-export interface MCPUIConfig {
+export interface MCPUIConfigInput {
   /**
    * When the library puts the boolean `credentialless` attribute on an
    * `<iframe>` it renders.
@@ -60,7 +88,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`:
@@ -69,23 +97,23 @@ export interface MCPUIConfig {
    *
    * 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'`.
+   * {@link MCPUIConfigInput.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}.
+   * also accepts {@link MCPUIConfigInput.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,12 +129,47 @@ 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'
 }
 
+/**
+ * The resolved host policy: every key present. This is what the library hands
+ * back, so a reader never null-checks a policy.
+ *
+ * Extends `Required<`{@link MCPUIConfigInput}`>` rather than declaring the
+ * fields again, so a key exists in exactly one place and the two views cannot
+ * drift. It remains an interface so existing consumers can extend or augment
+ * the public contract as they could before 6.22.0.
+ */
+export interface MCPUIConfig extends Required<MCPUIConfigInput> {}
+
 /**
  * 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 `MCPUIConfig` (i.e. resolved): that annotation is what stops a new
+ * key from shipping without a default.
  */
 export const DEFAULT_MCPUI_CONFIG: MCPUIConfig = {
   iframeCredentialless: 'auto',
@@ -114,13 +177,30 @@ export const DEFAULT_MCPUI_CONFIG: MCPUIConfig = {
   iframePolicy: 'strict',
   customIframeDomains: [],
   iframeFallbackLink: 'auto',
+  chartZoom: 'expanded',
 }
 
+/**
+ * Typed with the RESOLVED view, because this context is read as well as
+ * written: it is exported, so a consumer may call
+ * `useContext(MCPUIConfigContext)` directly, and typing it as the input view
+ * would hand them `IframePolicy | undefined` — exactly the regression this
+ * whole split exists to undo.
+ *
+ * The cost lands on the rarer side: a host feeding this context directly
+ * passes a COMPLETE value, `{ ...DEFAULT_MCPUI_CONFIG, ...mine }`. Anyone who
+ * wants to pass only the keys they care about uses `MCPUIConfigProvider`,
+ * whose `config` prop takes `Partial<`{@link MCPUIConfig}`>` and does that
+ * merge. That preserves optional properties added through declaration
+ * merging; {@link MCPUIConfigInput} remains the unaugmented built-in input
+ * shape a host can name for ordinary authored configs.
+ */
 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 {
   return mergeProps(DEFAULT_MCPUI_CONFIG, useContext(MCPUIConfigContext))

package/src/context/MCPUIMathContext.tsx

@@ -0,0 +1,32 @@
+import { createContext, useContext, type Accessor, type JSX } from 'solid-js'
+
+export interface MathRenderOptions {
+  displayMode: boolean
+}
+
+/** A synchronous, host-supplied renderer. Returned markup is always sanitized by MCP-UI. */
+export type MathRenderer = (tex: string, options: MathRenderOptions) => string | null
+
+const MCPUIMathContext = createContext<Accessor<MathRenderer | undefined>>(() => undefined)
+
+export interface MCPUIMathProviderProps {
+  /** Omit or pass null to explicitly disable an inherited renderer. */
+  renderMath?: MathRenderer | null
+  children: JSX.Element
+}
+
+export function MCPUIMathProvider(props: MCPUIMathProviderProps): JSX.Element {
+  return (
+    <MCPUIMathContext.Provider value={() => props.renderMath ?? undefined}>
+      {props.children}
+    </MCPUIMathContext.Provider>
+  )
+}
+
+/**
+ * Returns a reactive accessor for the nearest math renderer. Call the accessor
+ * at use time; its value changes when a provider swaps or disables its renderer.
+ */
+export function useMCPUIMath(): Accessor<MathRenderer | undefined> {
+  return useContext(MCPUIMathContext)
+}