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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-ship/mcp-ui-solid",
-  "version": "6.22.0",
+  "version": "6.23.0",
   "description": "SolidJS components for rendering MCP-generated UI resources",
   "type": "module",
   "files": [
@@ -44,6 +44,9 @@
       ],
       "plugins/duckdb": [
         "./dist/plugins/duckdb.d.ts"
+      ],
+      "plugins/katex": [
+        "./dist/plugins/katex.d.ts"
       ]
     }
   },
@@ -147,6 +150,17 @@
         "default": "./dist/plugins/duckdb.cjs"
       }
     },
+    "./plugins/katex": {
+      "solid": "./src/plugins/katex.ts",
+      "import": {
+        "types": "./dist/plugins/katex.d.ts",
+        "default": "./dist/plugins/katex.js"
+      },
+      "require": {
+        "types": "./dist/plugins/katex.d.cts",
+        "default": "./dist/plugins/katex.cjs"
+      }
+    },
     "./src/*": "./src/*"
   },
   "_size-limit-note": "size-limit is a regression guardrail, not a hard cap — it flags accidental bundle bloat. It measures the pre-built dist/index.js and sums the FULL graph reachable from each entry, including lazy import() chunks (leaflet, @antv/g6, chart.js) a consumer fetches on demand, NOT at import time — so the figures are worst-case totals, not eager load cost. Since v6.6.0 the 'Streaming renderer' entry delegates to UIResourceRenderer (Gap 1 parity), so its graph equals the full renderer set; its budget is set to 1 MB (generous headroom — the real eager cost is far lower). The 'Hooks only' and 'Full bundle' limits are pre-existing and unchanged by v6.6.0. size-limit is informational only — it does not gate CI.",
@@ -176,6 +190,7 @@
     "chart.js": "^4.0.0",
     "chartjs-plugin-zoom": "^2.0.0",
     "highlight.js": "^11.9.0",
+    "katex": "0.18.4",
     "leaflet": "^1.9.4",
     "leaflet.markercluster": "^1.5.0",
     "protomaps-leaflet": "^4.0.0",
@@ -197,6 +212,9 @@
     "highlight.js": {
       "optional": true
     },
+    "katex": {
+      "optional": true
+    },
     "leaflet": {
       "optional": true
     },
@@ -232,6 +250,7 @@
     "chart.js": "^4.5.1",
     "eslint": "^8.56.0",
     "jsdom": "^27.2.0",
+    "katex": "0.18.4",
     "leaflet.markercluster": "^1.5.3",
     "size-limit": "^12.0.0",
     "solid-js": "^1.9.11",
@@ -262,7 +281,7 @@
   },
   "scripts": {
     "build": "vite build && pnpm build:types",
-    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --composite false && pnpm build:types:copy",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --composite false && pnpm build:types:copy && cp dist/plugins/katex.d.ts dist/plugins/katex.d.cts",
     "build:types:copy": "printf \"export * from './components/index';\\nexport { default } from './components/index';\\n\" > dist/components.d.ts && printf \"export * from './hooks/index';\\n\" > dist/hooks.d.ts && printf \"export * from './types/index';\\n\" > dist/types.d.ts && printf \"export * from './adapters/index';\\n\" > dist/adapters.d.ts && pnpm build:types:cts",
     "build:types:cts": "cp dist/index.d.ts dist/index.d.cts && cp dist/components.d.ts dist/components.d.cts 2>/dev/null || true && cp dist/hooks.d.ts dist/hooks.d.cts 2>/dev/null || true && cp dist/types.d.ts dist/types.d.cts 2>/dev/null || true && cp dist/validation.d.ts dist/validation.d.cts 2>/dev/null || true && cp dist/types-export.d.ts dist/types-export.d.cts 2>/dev/null || true && cp dist/adapters.d.ts dist/adapters.d.cts 2>/dev/null || true && cp dist/adapters/presentation.d.ts dist/adapters/presentation.d.cts 2>/dev/null || true && cp dist/plugins/duckdb.d.ts dist/plugins/duckdb.d.cts 2>/dev/null || true",
     "dev": "vite build --watch",
@@ -270,7 +289,7 @@
     "test:watch": "vitest",
     "test:browser": "vitest --mode browser",
     "lint": "eslint src",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.contracts.json",
     "clean": "rm -rf dist",
     "size": "size-limit",
     "size:analyze": "size-limit --why"

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

@@ -43,24 +43,34 @@ 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.
+ * ## 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.
@@ -87,14 +97,14 @@ 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[]
 
   /**
    * 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
 
@@ -141,17 +151,27 @@ export interface MCPUIConfig {
   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 —
  * 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.
+ * Typed `MCPUIConfig` (i.e. resolved): that annotation is what stops a new
+ * key from shipping without a default.
  */
-export const DEFAULT_MCPUI_CONFIG: Required<MCPUIConfig> = {
+export const DEFAULT_MCPUI_CONFIG: MCPUIConfig = {
   iframeCredentialless: 'auto',
   customTrustedIframeDomains: [],
   iframePolicy: 'strict',
@@ -161,10 +181,19 @@ export const DEFAULT_MCPUI_CONFIG: Required<MCPUIConfig> = {
 }
 
 /**
- * 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.
+ * 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)
 
@@ -173,7 +202,7 @@ export const MCPUIConfigContext = createContext<MCPUIConfig>(DEFAULT_MCPUI_CONFI
  * came from the provider or from `DEFAULT_MCPUI_CONFIG`. Returns the defaults
  * outright when no `<MCPUIConfigProvider>` is mounted above.
  */
-export function useMCPUIConfig(): Required<MCPUIConfig> {
+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)
+}

package/src/index.ts

@@ -167,6 +167,7 @@ export {
 } from './context/MCPUIConfigContext'
 export type {
   MCPUIConfig,
+  MCPUIConfigInput,
   MCPUIConfigProviderProps,
 } from './context/MCPUIConfigContext'
 
@@ -389,6 +390,9 @@ export {
   DEGRADED_PROJECTION_LABELS,
 } from './utils/degraded-projections'
 export type { DegradedProjectionLabels } from './utils/degraded-projections'
+export { MCPUIMathProvider } from './context/MCPUIMathContext'
+export type { MathRenderer, MathRenderOptions, MCPUIMathProviderProps } from './context/MCPUIMathContext'
+
 export { chartToDataTable, CHART_DATA_TABLE_LABELS } from './components/chart-data-table'
 export type { ChartDataTableLabels } from './components/chart-data-table'
 

package/src/plugins/katex.ts

@@ -0,0 +1,25 @@
+import katex from 'katex'
+import type { MathRenderer } from '../context/MCPUIMathContext'
+
+/**
+ * Optional KaTeX adapter. It emits MathML only: no HTML layout tree, inline
+ * styles, fonts, stylesheet, shared macro state, or trusted TeX commands.
+ */
+export const renderKatexMath: MathRenderer = (tex, { displayMode }) => {
+  try {
+    return katex.renderToString(tex, {
+      displayMode,
+      output: 'mathml',
+      // Invalid TeX must return null so the core can preserve the complete
+      // source token, including its delimiters, instead of showing KaTeX's
+      // red error MathML and silently consuming the dollars.
+      throwOnError: true,
+      trust: false,
+      maxExpand: 1000,
+      maxSize: 20,
+      macros: {},
+    })
+  } catch {
+    return null
+  }
+}

package/src/utils/iframe-coep.ts

@@ -27,14 +27,15 @@ import type { MCPUIConfig } from '../context/MCPUIConfigContext'
  *
  * 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.
+ * Takes a RESOLVED config — `MCPUIConfig`, which is what `useMCPUIConfig()`
+ * and `DEFAULT_MCPUI_CONFIG` hand out, every key present. The authored view is
+ * `MCPUIConfigInput`, whose fields are optional so that a new key stays
+ * backward compatible; accepting one of those here would mean re-implementing
+ * the defaults next to their source, and silently drifting from them.
  */
 export function shouldSetCredentialless(
   url: string,
-  config: Required<MCPUIConfig>,
+  config: MCPUIConfig,
   options: { sandboxedWithoutSameOrigin: boolean }
 ): boolean {
   const mode = config.iframeCredentialless
@@ -71,7 +72,7 @@ export function createCrossOriginIsolated(): Accessor<boolean> {
  * Takes a resolved config, for the reason given on `shouldSetCredentialless`.
  */
 export function shouldShowIframeFallbackLink(
-  config: Required<MCPUIConfig>,
+  config: MCPUIConfig,
   crossOriginIsolated: boolean
 ): boolean {
   const mode = config.iframeFallbackLink

package/src/utils/math-markdown.ts

@@ -0,0 +1,222 @@
+import type { Config } from 'dompurify'
+import { Marked, Renderer, type MarkedExtension, type Tokens } from 'marked'
+import type { MathRenderer } from '../context/MCPUIMathContext'
+import { escapeHtml } from './escape-html'
+import { canSanitizeHtml, sanitizeHtml } from './sanitize-html'
+
+export type MathMarkdownProfile = 'prose' | 'cellMarkdown'
+export type MarkdownTextTransform = (escapedText: string) => string
+
+export const MATH_MARKDOWN_LIMITS = {
+  sourceLength: 100_000,
+  expressionLength: 4_096,
+  expressionCount: 128,
+} as const
+
+const MATH_TAGS = [
+  'math', 'semantics', 'mrow', 'mi', 'mo', 'mn', 'mtext', 'mspace', 'ms',
+  'msup', 'msub', 'msubsup', 'mfrac', 'msqrt', 'mroot', 'mtable', 'mtr',
+  'mtd', 'mover', 'munder', 'munderover', 'mpadded', 'mphantom', 'mstyle', 'menclose',
+] as const
+
+const MATH_ATTRS = [
+  'xmlns', 'display', 'class', 'mathvariant', 'stretchy', 'fence', 'separator',
+  'lspace', 'rspace', 'accent', 'accentunder', 'columnalign', 'rowalign',
+  'columnspacing', 'rowspacing', 'columnlines', 'rowlines', 'frame', 'notation',
+  'width', 'height', 'depth', 'voffset', 'scriptlevel', 'displaystyle',
+] as const
+
+const STRICT_MATHML_CONFIG = {
+  ALLOWED_TAGS: [...MATH_TAGS, 'span'],
+  ALLOWED_ATTR: [...MATH_ATTRS],
+  FORBID_TAGS: ['annotation', 'annotation-xml', 'style', 'a'],
+  // DOMPurify normally keeps the text of forbidden tags. TeX annotations can
+  // be large and duplicate the accessible MathML, so remove their subtree.
+  ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+  FORBID_ATTR: ['style'],
+} as Config
+
+const CELL_MARKDOWN_TAGS = [
+  'a', 'strong', 'em', 'b', 'i', 'code', 'span', 'br', 'button', 'svg', 'path',
+  'p', 'ul', 'ol', 'li', 'pre', 'blockquote', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  ...MATH_TAGS,
+]
+
+const FINAL_PROFILES: Record<MathMarkdownProfile, Config> = {
+  prose: {
+    ADD_TAGS: [...MATH_TAGS],
+    ADD_ATTR: [...MATH_ATTRS, 'target', 'rel'],
+    FORBID_TAGS: ['annotation', 'annotation-xml', 'style', 'form', 'textarea', 'select', 'button', 'iframe', 'object', 'embed'],
+    ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+    FORBID_ATTR: ['style'],
+  } as Config,
+  cellMarkdown: {
+    ALLOWED_TAGS: CELL_MARKDOWN_TAGS,
+    ALLOWED_ATTR: [
+      'href', 'target', 'rel', 'class', 'data-citation-page', 'data-citation-source',
+      'data-citation-doc', 'data-citation-verified', 'title', 'fill', 'stroke',
+      'viewBox', 'stroke-linecap', 'stroke-linejoin', 'stroke-width', 'd',
+      ...MATH_ATTRS,
+    ],
+    FORBID_TAGS: ['annotation', 'annotation-xml', 'style'],
+    ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+    FORBID_ATTR: ['style'],
+  } as Config,
+}
+
+interface MathToken extends Tokens.Generic {
+  type: 'mcpDisplayMath' | 'mcpInlineMath'
+  raw: string
+  tex: string
+  displayMode: boolean
+  render: boolean
+}
+
+function isCurrencyLike(raw: string, tex: string, following: string): boolean {
+  if (/^\$\s|\s\$$/.test(raw)) return true
+  if (/^\d+(?:[.,]\d+)?-\s*$/.test(tex)) return true
+  if (/^\d/.test(tex) && /^\d/.test(following)) return true
+
+  // A currency opener can otherwise pair with the opening delimiter of a
+  // later expression ("$5 then ($x$)"). Reinterpret that first candidate
+  // only when it starts with a bounded numeric amount and its apparent closer
+  // is immediately followed by a complete later inline body. This deliberately
+  // leaves inherently ambiguous standalone forms ($5$, $2 + 3$, $2\pi$) as
+  // math and does not depend on the prose between the two delimiters.
+  const amount = /^\d+(?:[.,]\d{1,2})?(?=$|[\s,;:!?()[\]+*/-])/.exec(tex)?.[0]
+  if (!amount) return false
+
+  // A standalone numeric token is valid math even when followed by prose or
+  // another expression ("$5$, then $x$"). Reassignment requires content
+  // beyond the amount itself.
+  const trailing = tex.slice(amount.length)
+  if (!trailing) return false
+
+  // During streaming, the later formula may not have closed yet. An unmatched
+  // opening parenthesis before its dollar is sufficient structural evidence
+  // that the numeric dollar was currency; otherwise a permissive renderer can
+  // briefly flash "5 then (" as math.
+  const hasUnmatchedOpeningParen = (trailing.match(/\(/g)?.length ?? 0) > (trailing.match(/\)/g)?.length ?? 0)
+  const containsTexCommand = /\\[A-Za-z]+/.test(trailing)
+  if (hasUnmatchedOpeningParen && !containsTexCommand) return true
+
+  const closerLooksLikeLaterOpener = /^(?![\s,.;:!?)}\]])(?:\\[^\n]|[^\\\n$])+\$(?!\$)/.test(following)
+  return closerLooksLikeLaterOpener
+}
+
+const CELL_LINK_ATTRIBUTES = 'target="_blank" rel="noopener noreferrer" class="text-blue-600 dark:text-blue-400 hover:underline"'
+
+function cellLinkExtension(): MarkedExtension {
+  return {
+    renderer: {
+      link(this: Renderer, token: Tokens.Link): string {
+        // Marked owns escaping of the destination, title and nested label
+        // tokens. Only inject fixed attributes into its already-safe anchor.
+        const anchor = Renderer.prototype.link.call(this, token) as string
+        return anchor.replace('<a ', `<a ${CELL_LINK_ATTRIBUTES} `)
+      },
+    },
+  }
+}
+
+function mathExtension(renderer: MathRenderer): MarkedExtension {
+  let count = 0
+  const token = (raw: string, tex: string, displayMode: boolean): MathToken => ({
+    type: displayMode ? 'mcpDisplayMath' : 'mcpInlineMath',
+    raw,
+    tex,
+    displayMode,
+    render: ++count <= MATH_MARKDOWN_LIMITS.expressionCount && tex.length <= MATH_MARKDOWN_LIMITS.expressionLength,
+  })
+
+  return {
+    extensions: [
+      {
+        name: 'mcpDisplayMath',
+        level: 'block',
+        start(src) {
+          const index = src.indexOf('$$')
+          return index < 0 ? undefined : index
+        },
+        tokenizer(src) {
+          const match = /^\$\$\s*\n?([\s\S]+?)\n?\s*\$\$(?:\n|$)/.exec(src)
+          if (!match) return undefined
+          return token(match[0], match[1], true)
+        },
+        renderer(tokenValue) {
+          return renderToken(tokenValue as MathToken, renderer)
+        },
+      },
+      {
+        name: 'mcpInlineMath',
+        level: 'inline',
+        start(src) {
+          const index = src.indexOf('$')
+          return index < 0 ? undefined : index
+        },
+        tokenizer(src) {
+          const match = /^\$(?!\$)((?:\\[^\n]|[^\\\n$])+?)\$(?!\$)/.exec(src)
+          if (!match || isCurrencyLike(match[0], match[1], src.slice(match[0].length))) return undefined
+          return token(match[0], match[1], false)
+        },
+        renderer(tokenValue) {
+          return renderToken(tokenValue as MathToken, renderer)
+        },
+      },
+    ],
+  }
+}
+
+function renderToken(token: MathToken, renderer: MathRenderer): string {
+  if (!token.render) return escapeHtml(token.raw)
+  try {
+    const rendered = renderer(token.tex, { displayMode: token.displayMode })
+    if (!rendered) return escapeHtml(token.raw)
+    return sanitizeHtml(rendered, STRICT_MATHML_CONFIG)
+  } catch {
+    return escapeHtml(token.raw)
+  }
+}
+
+/**
+ * Parse Markdown with isolated, bounded math support and sanitize the complete
+ * result for its final sink. The optional transform sees escaped ordinary text
+ * tokens only. Math, code, raw HTML and link destinations never pass through
+ * it, so citation syntax cannot corrupt TeX optional arguments or attributes.
+ */
+export function parseMathMarkdown(
+  source: string,
+  renderer: MathRenderer,
+  profile: MathMarkdownProfile,
+  transformText?: MarkdownTextTransform,
+): string {
+  const input = source === null || source === undefined ? '' : String(source)
+  if (!canSanitizeHtml()) return escapeHtml(input)
+  if (input.length > MATH_MARKDOWN_LIMITS.sourceLength) return escapeHtml(input)
+
+  const textRenderer = transformText
+    ? {
+        renderer: {
+          text(this: Renderer, token: Tokens.Text | Tokens.Escape): string {
+            // Block text tokens (notably list-item text) can own already
+            // tokenized inline children. Recurse first so math and code keep
+            // their own renderers; leaf text callbacks run as parsing descends.
+            if ('tokens' in token && token.tokens) {
+              return this.parser.parseInline(token.tokens)
+            }
+            // Delegate entity handling and nested token rendering to Marked's
+            // own renderer. `escapeHtml` is deliberately not equivalent: it
+            // turns source `&amp;` into visible `&amp;` by double-escaping it.
+            const safeText = Renderer.prototype.text.call(this, token)
+            return transformText(safeText as string)
+          },
+        },
+      }
+    : undefined
+  const extensions = [mathExtension(renderer)]
+  if (profile === 'cellMarkdown') extensions.push(cellLinkExtension())
+  if (textRenderer) extensions.push(textRenderer)
+  const parser = new Marked({ gfm: true }, ...extensions)
+  const parsed = parser.parse(input, { async: false }) as string
+  return sanitizeHtml(parsed, FINAL_PROFILES[profile])
+}