@seed-ship/mcp-ui-solid 6.21.0 → 6.23.0

package/CHANGELOG.md

@@ -5,6 +5,179 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.23.0] - 2026-09-18
+
+### Added
+
+- Opt-in `MCPUIMathProvider` and `MathRenderer` for markdown text and table
+  cells, including virtualized tables; separate optional `/plugins/katex`
+  adapter. No new required config fields and no KaTeX import from the root.
+- Bounded dollar-delimited math parsing, currency guards, isolated Marked
+  instances, sanitized MathML-only rendering and literal fallback. Styles,
+  annotation subtrees, executable markup and trusted TeX commands stay blocked.
+- SSR keeps escaped source until the existing client hydration upgrade;
+  original text/data is retained for copy and export. No CSS or font install.
+- Optional KaTeX peer pinned to 0.18.4 to preserve Node 20 installation
+  compatibility; later 0.18.x releases currently require Node >=22.12 via
+  Commander. Cell links retain the existing new-tab, rel and styling policy.
+
+## [6.22.1] - 2026-09-18
+
+Fixes a typing regression 6.22.0 introduced. Runtime behaviour is identical.
+
+### The mistake
+
+6.22.0 made every `MCPUIConfig` field optional so that adding a policy key
+would stop breaking consumers who *author* a complete config. That fixed one
+direction and broke the other: `MCPUIConfig` is a published type, so anyone who
+*reads* one — `const policy: IframePolicy = config.iframePolicy` — suddenly
+faced `… | undefined` and stopped compiling under `strictNullChecks`. Trading
+one compile break for the opposite one is not a fix.
+
+The two demands genuinely conflict, and one name cannot serve both: an author
+must be allowed to omit a key, a reader must never meet `undefined`.
+
+### The fix — two names
+
+- **`MCPUIConfigInput`** (new, exported): what a host writes. Every field
+  optional, so a new policy key is always additive. This is what
+  `MCPUIConfigProvider`'s `config` prop takes. Note it is NOT what
+  `MCPUIConfigContext.Provider` takes — see below.
+- **`MCPUIConfig`**: what the library hands back — an interface extending
+  `Required<MCPUIConfigInput>`, every key present, which is the 6.21.0 meaning
+  restored. Keeping it an interface also preserves consumer extension and
+  declaration merging. `useMCPUIConfig()`, `DEFAULT_MCPUI_CONFIG` and
+  `MCPUIConfigContext` carry it.
+
+`MCPUIConfigContext` keeps the resolved type on purpose: it is exported, so
+`useContext(MCPUIConfigContext)` is a public read surface and typing it with the
+input view would leave a direct reader on `IframePolicy | undefined` — the very
+regression being undone. A host that bypasses `MCPUIConfigProvider` therefore
+passes a complete value, `{ ...DEFAULT_MCPUI_CONFIG, ...mine }`; passing only
+some keys is what the provider's `config` prop is for. `useMCPUIConfig()` still
+merges at runtime, so an untyped host cannot break a renderer.
+
+Derived rather than declared twice, so a key is written once and the two views
+cannot drift. The guard test now pins **both** halves: every `MCPUIConfigInput`
+field stays optional, and `MCPUIConfig` stays an interface extending
+`Required<…>`. The contract typecheck also pins interface extension and
+declaration merging. Both sides were verified to fail when their corresponding
+regression is reintroduced.
+
+### How this got through
+
+Through 6.22.0, `pnpm typecheck` ran the main `tsconfig.json` alone, and that
+config excludes `**/*.test.ts(x)`: a type-level claim written in a test file
+failed nothing. 6.22.0 shipped both a broken `MCPUIConfig` and a fixture
+annotated with the wrong type, and neither `typecheck` nor `test` said a word.
+`typecheck` now runs a second pass, `tsconfig.contracts.json`, which
+type-checks the handful of test files whose `satisfies` and annotations *are*
+the test. Including every test file instead would surface 53 unrelated errors,
+so that stays a separate piece of work.
+
+### Upgrading
+
+Reading is exactly as it was in 6.21.0, whether through `useMCPUIConfig()`,
+`useContext(MCPUIConfigContext)` or a value typed `MCPUIConfig`.
+`MCPUIConfigProvider`'s `config` prop still accepts everything it accepted
+before, `Partial<MCPUIConfig>` included.
+
+Two authoring patterns stop compiling, coming from 6.21.0 or from 6.22.0:
+
+- **A config annotated `MCPUIConfig`.** From 6.22.0 a partial one fails; from
+  6.21.0 a complete one fails too, since it lacks `chartZoom`. Annotate it
+  `MCPUIConfigInput` instead.
+- **A value handed straight to `<MCPUIConfigContext.Provider>`**, annotated or
+  not: an inline literal fails the same way. Spread the defaults,
+  `{ ...DEFAULT_MCPUI_CONFIG, ...mine }`, or pass the keys to
+  `<MCPUIConfigProvider config={…}>`, which does that merge for you.
+
+Both replacements keep compiling when the library adds its next policy key.
+
+## [6.22.0] - 2026-09-18
+
+Wheel zoom and drag pan on the surfaces that could not be read when the content
+was dense: the image lightbox, and Chart.js charts in their expanded view.
+
+### The rule this follows
+
+**Wheel zoom is only ever enabled on a surface that owns its viewport** — a
+fullscreen overlay or the expanded modal. A component sitting inline in a
+scrolling page must not swallow the wheel, or a user scrolling the page finds
+themselves zooming a chart instead. That is why chart zoom defaults to the
+expanded view only, and why inline zoom is opt-in.
+
+### Added
+
+- **`createPanZoom(options)`** (`src/utils/pan-zoom.ts`, exported from the root
+  and from the `./hooks` subpath) — a dependency-free cursor-anchored zoom and
+  drag-pan primitive: the point under the pointer stays under the pointer.
+  Handles two-finger pinch, clamps to `min`/`max`, and exposes
+  `cancelGesture()` for the case where the surface carrying the handlers is
+  torn down while a pointer is still down. The pure helpers behind it
+  (`clampScale`, `contentPointAt`, `viewportPointOf`, `zoomAtAnchor`) are
+  exported too.
+- **`LightboxOverlay` zooms.** Wheel, drag to pan, double-click to toggle,
+  pinch on touch, and the keyboard shortcuts `+` / `-` / `0` alongside the
+  existing Escape and arrows. Zoom controls carry a level readout, and the zoom
+  resets when the displayed image changes.
+- **Chart.js zoom and pan**, through `chartjs-plugin-zoom` as a new **optional**
+  peer dependency. Absent, charts render exactly as before — no warning, no
+  broken UI. A reset button appears in the toolbar only while the chart is
+  actually zoomed. A chart's own `options.plugins.zoom` is preserved: the
+  renderer's block is deep-merged into it, the caller's explicit values win
+  (`limits`, wheel `speed`, a pan `modifierKey`, `mode`), and a caller's
+  `onZoom` / `onPan` is *composed* with the renderer's rather than replacing
+  it, so the reset control stays in sync with the viewport either way. A key
+  the caller left `undefined` is read as an omission, not as an erasure. And
+  `options.plugins.zoom: false` — Chart.js's documented per-chart plugin
+  opt-out — beats `chartZoom`: the plugin is never downloaded and the toolbar
+  offers no controls.
+- **`MCPUIConfig.chartZoom`**: `'expanded'` (default), `'always'` or `'never'`.
+- Four string keys: `zoomIn`, `zoomOut`, `zoomReset`, `zoomLevel`
+  (`'Zoom {percent}%'`). Chrome key count 271 → 275.
+
+### Changed
+
+> **Superseded by 6.22.1.** Making the fields of the published `MCPUIConfig`
+> optional broke every consumer that *reads* one. 6.22.1 moves the optional
+> fields to a new `MCPUIConfigInput` and restores `MCPUIConfig` as the
+> resolved type. The entry below describes 6.22.0 as published.
+
+- **Every `MCPUIConfig` field is now optional**, as `MCPUIStrings` has always
+  been. `MCPUIConfig` grows a key in a minor release each time the library
+  gains a policy switch — `iframeFallbackLink` in 6.21.0, `chartZoom` here —
+  and while the fields were required, each addition broke the build of anyone
+  holding a *complete* config: a typed constant, a helper returning one, or a
+  direct `<MCPUIConfigContext.Provider value={…}>`. Nothing about their
+  behaviour had changed; only `tsc` failed. Adding a key is additive now.
+
+  The completeness guarantee moved onto the values: `DEFAULT_MCPUI_CONFIG` is
+  typed `Required<MCPUIConfig>` (a new key without a default is a compile error
+  in the library), and `useMCPUIConfig()` returns `Required<MCPUIConfig>`, so
+  every renderer still reads a fully resolved policy and never null-checks one.
+  `MCPUIConfigContext` itself stays typed `MCPUIConfig`, which makes providing
+  it directly *more* permissive than before. Backward compatible in both
+  directions: a consumer already passing a field still type-checks.
+
+### Fixed
+
+- **`ExpandableWrapper` no longer closes on a drag released over its backdrop.**
+  When a press and its release have different targets the browser dispatches
+  `click` on their nearest common ancestor — the backdrop — so panning a zoomed
+  chart, or selecting text in an expanded table, and releasing over the 16px
+  margin around the panel tore the modal down mid-gesture. The close now
+  requires the gesture to have *begun* on the backdrop. This was reachable
+  before this release for any drag inside an expanded view; chart panning just
+  made it easy to hit.
+
+### Not affected
+
+Maps and graphs already zoomed: `MapRenderer` enables Leaflet's
+`scrollWheelZoom` and `GraphRenderer` registers G6's `zoom-canvas` /
+`drag-canvas`. Iframes (including a diagram served from `mermaid.ink`) are
+cross-origin documents and cannot be transformed by the host at all.
+
 ## [6.21.0] - 2026-09-17
 
 The library's iframes now work on a host that serves

package/README.md

@@ -5,6 +5,65 @@ SolidJS components + chat toolkit for MCP-generated UI. Part of the [MCP UI ecos
 [![npm version](https://img.shields.io/npm/v/@seed-ship/mcp-ui-solid.svg)](https://www.npmjs.com/package/@seed-ship/mcp-ui-solid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## What's New in v6.23.0
+
+Opt-in LaTeX in markdown text components and table cells, with the same
+currency guards and sanitized MathML output. No change without a provider;
+`MCPUIConfig` is unchanged. See [Math rendering](#math-rendering).
+
+## Math rendering
+
+Install the optional peer only if the host wants the supplied KaTeX adapter:
+
+```bash
+pnpm add --save-exact katex@0.18.4
+```
+
+```tsx
+import { MCPUIMathProvider, UIResourceRenderer } from '@seed-ship/mcp-ui-solid'
+import { renderKatexMath } from '@seed-ship/mcp-ui-solid/plugins/katex'
+
+<MCPUIMathProvider renderMath={renderKatexMath}>
+  <UIResourceRenderer content={resource} />
+</MCPUIMathProvider>
+```
+
+The adapter's optional peer is pinned to 0.18.4 to retain Node 20 installation
+compatibility. KaTeX 0.18.5–0.18.7 pull in Commander 15 (Node >=22.12);
+do not replace the pin with a caret range on Node 20.
+
+The provider applies to `text` with `markdown: true` and string-valued table
+cells, including virtualized rows. It recognizes `$...$` inline and `$$...$$`
+display formulas in their own paragraph (not embedded mid-sentence).
+Code spans/fences and link destinations are not formulas;
+currency such as `$5` and `$5-$10` remains text. Malformed/incomplete formulas
+degrade to their source. Copy/export continues to use the original data.
+Dollar syntax can be ambiguous: `$5$` is a formula. Escape a literal dollar
+as `\$` when composing currency and formulas; numeric math such as `$2 + 3$`
+remains supported. Math-enabled cell links keep their existing new-tab behavior.
+
+The adapter emits **MathML only**: no KaTeX stylesheet, fonts, CDN requests,
+HTML layout or inline styles. Native MathML rendering varies by browser and
+may differ from the chat's HTML+MathML layout. There is no automatic loading:
+the explicit plugin import is the opt-in dependency boundary; hosts can load
+that module before mounting the provider if they want a separate chunk.
+
+Alternatively pass a synchronous `MathRenderer` function returning MathML
+(`(tex, { displayMode }) => string | null`). The library still sanitizes it;
+return `null` or throw to retain literal source. Passing `null` (or omitting
+`renderMath`) on a nested provider disables inherited math. Arbitrary Marked
+extensions and sanitizer overrides are deliberately not public API.
+
+On the server, escaped source is emitted without calling the renderer. The
+existing `SafeHtml` client upgrade renders sanitized formulas after hydration.
+Processing is bounded to 100,000 source characters, 4,096 per expression and
+128 expressions per parse; oversized input stays escaped text. The adapter
+also limits macro expansion and dimensions, disables trusted commands, and
+does not share macro definitions across formulas. TeX annotation subtrees are
+removed rather than exposing duplicate source after sanitization.
+
+See the [design and integration handoff](./docs/briefs/LATEX-MATHML-2026-09-18.md).
+
 ## What's New in v6.21.0
 
 - **Iframes work under `Cross-Origin-Embedder-Policy: credentialless`.** Both
@@ -1029,6 +1088,48 @@ import { MCPUIConfigProvider } from '@seed-ship/mcp-ui-solid'
 </MCPUIConfigProvider>
 ```
 
+When you keep a partial configuration in a variable, name the authored,
+all-optional view explicitly:
+
+```tsx
+import {
+  MCPUIConfigProvider,
+  type MCPUIConfigInput,
+} from '@seed-ship/mcp-ui-solid'
+
+const config: MCPUIConfigInput = {
+  iframeCredentialless: 'always',
+  chartZoom: 'never',
+}
+
+<MCPUIConfigProvider config={config}>
+  <App />
+</MCPUIConfigProvider>
+```
+
+Prefer `MCPUIConfigProvider` for partial overrides. The exported raw context is
+also a public read surface, so its `Provider` requires the complete, resolved
+`MCPUIConfig` value. If an integration must provide that context directly,
+spread the defaults first:
+
+```tsx
+import {
+  DEFAULT_MCPUI_CONFIG,
+  MCPUIConfigContext,
+} from '@seed-ship/mcp-ui-solid'
+
+<MCPUIConfigContext.Provider
+  value={{ ...DEFAULT_MCPUI_CONFIG, iframeCredentialless: 'always' }}
+>
+  <App />
+</MCPUIConfigContext.Provider>
+```
+
+`MCPUIConfigInput` contains the library's built-in authoring fields.
+`MCPUIConfig` remains an interface for consumers that extend or augment the
+resolved contract; `MCPUIConfigProvider` also accepts those augmented fields
+as partial inline overrides.
+
 | Option | Values | Default | What it does |
 |--------|--------|---------|--------------|
 | `iframeCredentialless` | `'auto'` \| `'always'` \| `'never'` | `'auto'` | `'auto'`: the attribute on the `iframe` component when its host is **not** in `TRUSTED_IFRAME_DOMAINS` (+ `customTrustedIframeDomains`) — those frames already run without cookies. The video embed is excluded, since it has none of that sandboxing. `'always'`: every iframe, video and trusted hosts included — what a COEP host wants. `'never'`: none. |
@@ -1966,6 +2067,7 @@ import type {
   IframePolicy, ValidationOptions,
   CitationCtx, CitationEntry, DuplicateMountInfo, DuplicateMountReporter,
   MCPUIStrings, MCPUIConfig, // v6.21.0
+  MCPUIConfigInput, // v6.22.1 — the authored, all-optional view
   TelemetryEvent, TelemetrySink, TelemetryOptions, TelemetryDispatcher,
   DataValidation, HallucinatedNumber, DataValidationOptions,
   VerifiedTextContent, DataPreviewContent, MapSectionContent,