fix(math): load KaTeX lazily and show TeX source when it can't typeset

docs/content/4.plugins/1.built-in/math.md

@@ -156,7 +156,7 @@ Returns a `ComarkPlugin` that tokenizes `$...$` and `$$...$$` expressions.
 
 **Returns:** `ComarkPlugin`
 
-The plugin stores LaTeX source as plain text in the AST. Rendering requires passing `Math` to the `components` prop of `<Markdown>` (see [Usage](#usage)). KaTeX only runs when the component mounts.
+The plugin stores LaTeX source as plain text in the AST. Rendering requires passing `Math` to the `components` prop of `<Markdown>` (see [Usage](#usage)). The `Math` components load KaTeX on first use, so pages without math don't load it. A formula KaTeX can't typeset, such as one still streaming in, shows as its TeX source.
 
 ### Rendering math manually
 

packages/comark-angular/src/components/math.component.ts

@@ -1,5 +1,5 @@
 import { Component, Input, OnChanges, SimpleChanges, ChangeDetectionStrategy, ElementRef, inject } from '@angular/core'
-import katex from 'katex'
+import { loadKatex, typesetMath } from 'comark/plugins/math'
 
 /**
  * Math rendering component for Angular.
@@ -44,13 +44,19 @@ export class Math implements OnChanges {
     const wrapper = document.createElement(isInline ? 'span' : 'div')
     wrapper.className = isInline ? 'math inline' : 'math block'
 
-    try {
-      wrapper.innerHTML = katex.renderToString(this.content, {
-        throwOnError: true,
-        displayMode: !isInline,
-      })
-    } catch {
-      wrapper.textContent = '...'
+    const html = typesetMath(this.content, !isInline)
+    if (html) {
+      wrapper.innerHTML = html
+    } else {
+      // Unfinished or invalid TeX, and TeX before KaTeX loads, stays readable as its source.
+      wrapper.textContent = this.content
+      if (html === undefined) {
+        const content = this.content
+        loadKatex().then(
+          () => content === this.content && this.renderMath(),
+          () => {}
+        )
+      }
     }
 
     hostEl.appendChild(wrapper)

packages/comark-react/package.json

@@ -61,6 +61,7 @@
   "devDependencies": {
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
+    "happy-dom": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
     "vitest": "catalog:"

packages/comark-react/src/components/Math.tsx

@@ -1,40 +1,88 @@
-import { useState, useEffect } from 'react'
-import katex from 'katex'
+import { Suspense, memo, use } from 'react'
+import { loadKatex, typesetMath } from 'comark/plugins/math'
 
 export interface MathProps {
   content: string
   className?: string
 }
 
-export function Math({ content, className = '' }: MathProps) {
-  const isInline = className.includes('inline')
-  const [mathml, setMathml] = useState<string>('...')
-
-  useEffect(() => {
-    try {
-      const rendered = katex.renderToString(content, {
-        throwOnError: true,
-        displayMode: !isInline,
-      })
-      setMathml(rendered)
-    } catch {
-      // Keep loading state on error
-    }
-  }, [content, isInline])
+// After a failed load, formulas show their source, and a render this long
+// after the failure loads KaTeX again.
+const RETRY_DELAY = 5000
+
+// One promise for every formula, since `use` needs the same one on each render.
+let katexReady: Promise<boolean> | undefined
+let failedAt: number | undefined
+
+function waitForKatex(): Promise<boolean> {
+  if (!katexReady || (failedAt !== undefined && Date.now() - failedAt >= RETRY_DELAY)) {
+    failedAt = undefined
+    katexReady = loadKatex().then(
+      () => true,
+      () => {
+        failedAt = Date.now()
+        return false
+      }
+    )
+  }
+  return katexReady
+}
+
+// Memoized because streaming re-renders every formula on each chunk.
+const Typeset = memo(function Typeset({ content, isInline }: { content: string; isInline: boolean }) {
+  let html = typesetMath(content, !isInline)
+  if (html === undefined) {
+    use(waitForKatex())
+    html = typesetMath(content, !isInline)
+  }
+  if (!html)
+    return (
+      <Source
+        content={content}
+        isInline={isInline}
+      />
+    )
 
   if (isInline) {
     return (
       <span
         className="math inline"
-        dangerouslySetInnerHTML={{ __html: mathml }}
+        dangerouslySetInnerHTML={{ __html: html }}
       />
     )
   }
 
   return (
     <div
       className="math block"
-      dangerouslySetInnerHTML={{ __html: mathml }}
+      dangerouslySetInnerHTML={{ __html: html }}
     />
   )
+})
+
+// Unfinished or invalid TeX, and TeX without KaTeX installed, stays readable as its source.
+function Source({ content, isInline }: { content: string; isInline: boolean }) {
+  return isInline ? <span className="math inline">{content}</span> : <div className="math block">{content}</div>
+}
+
+export function Math({ content, className = '' }: MathProps) {
+  const isInline = className.includes('inline')
+
+  // KaTeX loads on first use. Streaming server rendering and hydration wait
+  // for it; otherwise the source shows until it loads.
+  return (
+    <Suspense
+      fallback={
+        <Source
+          content={content}
+          isInline={isInline}
+        />
+      }
+    >
+      <Typeset
+        content={content}
+        isInline={isInline}
+      />
+    </Suspense>
+  )
 }

packages/comark-react/test/plugin-math.client.test.tsx

@@ -0,0 +1,35 @@
+// @vitest-environment happy-dom
+import { StrictMode, act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { expect, it, vi } from 'vitest'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+it('shows the TeX source and stops loading KaTeX after a failed load in StrictMode', async () => {
+  let attempts = 0
+  vi.doMock('katex', () => {
+    attempts++
+    throw new Error('Failed to fetch dynamically imported module')
+  })
+  const { Math } = await import('../src/plugins/math')
+  const container = document.createElement('div')
+  const root = createRoot(container)
+
+  await act(async () => {
+    root.render(
+      <StrictMode>
+        <Math
+          content="x^2"
+          className="math inline"
+        />
+      </StrictMode>
+    )
+  })
+  await act(() => new Promise((resolve) => setTimeout(resolve, 100)))
+
+  expect(container.innerHTML).toBe('<span class="math inline">x^2</span>')
+  expect(attempts).toBe(1)
+
+  act(() => root.unmount())
+  vi.doUnmock('katex')
+})

packages/comark-react/test/plugin-math.test.tsx

@@ -1,12 +1,11 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { renderToString } from 'react-dom/server'
 import { parseMarkdown } from 'comark'
 import { MarkdownDocument } from '../src/components/MarkdownDocument'
 import math, { Math } from '../src/plugins/math'
 
 // `Math` derives its wrapper markup from the incoming class string, so the
-// `class` -> `className` renderer remap is observable under SSR alone —
-// `useEffect` (katex) never runs here.
+// `class` -> `className` renderer remap is observable under SSR alone.
 
 describe('@comark/react plugins/math — Math component', () => {
   it('renders inline math as an inline <span class="math inline">', async () => {
@@ -31,4 +30,77 @@ describe('@comark/react plugins/math — Math component', () => {
     )
     expect(html).toContain('<div class="math block"')
   })
+
+  it('shows the escaped TeX source when KaTeX cannot parse it', async () => {
+    const tree = await parseMarkdown('$\\frac{<b>}{$', { plugins: [math()] })
+    const html = renderToString(
+      <MarkdownDocument
+        value={tree}
+        components={{ math: Math }}
+      />
+    )
+    expect(html).toContain('<span class="math inline">\\frac{&lt;b&gt;}{</span>')
+    expect(html).not.toContain('...')
+  })
+
+  it('waits for KaTeX in streaming server rendering', async () => {
+    vi.resetModules()
+    const { Math } = await import('../src/plugins/math')
+    const { renderToReadableStream, renderToString } = await import('react-dom/server')
+
+    // Before KaTeX loads, the source stands in for the formula.
+    expect(
+      renderToString(
+        <Math
+          content="x^2"
+          className="math inline"
+        />
+      )
+    ).toContain('<span class="math inline">x^2</span>')
+
+    const stream = await renderToReadableStream(
+      <Math
+        content="x^2"
+        className="math inline"
+      />
+    )
+    await stream.allReady
+    const html = await new Response(stream).text()
+
+    expect(html).toContain('<span class="math inline"><span class="katex">')
+  })
+
+  it('loads KaTeX again after a failed load', async () => {
+    vi.resetModules()
+    let fail = true
+    vi.doMock('katex', async (importOriginal) => {
+      if (fail) throw new Error('Failed to fetch dynamically imported module')
+      return importOriginal()
+    })
+    const { Math } = await import('../src/plugins/math')
+    const { renderToReadableStream } = await import('react-dom/server')
+    const render = async () => {
+      const stream = await renderToReadableStream(
+        <Math
+          content="x^2"
+          className="math inline"
+        />
+      )
+      await stream.allReady
+      return new Response(stream).text()
+    }
+
+    vi.useFakeTimers({ toFake: ['Date'] })
+    try {
+      expect(await render()).toContain('<span class="math inline">x^2</span>')
+      fail = false
+      // Right after the failure, the source still shows.
+      expect(await render()).toContain('<span class="math inline">x^2</span>')
+      vi.advanceTimersByTime(5000)
+      expect(await render()).toContain('<span class="math inline"><span class="katex">')
+    } finally {
+      vi.useRealTimers()
+      vi.doUnmock('katex')
+    }
+  })
 })

packages/comark-svelte/src/components/Math.svelte

@@ -16,7 +16,7 @@ determines inline vs display mode (display when class does NOT contain "inline")
 ```
 -->
 <script lang="ts">
-  import katex from 'katex'
+  import { loadKatex, typesetMath } from 'comark/plugins/math'
 
   let {
     content,
@@ -28,22 +28,23 @@ determines inline vs display mode (display when class does NOT contain "inline")
 
   let isInline = $derived(className.split(' ').includes('inline'))
 
-  let mathml = $derived.by(() => {
-    try {
-      return katex.renderToString(content, {
-        throwOnError: true,
-        displayMode: !isInline,
-      })
-    }
-    catch {
-      return '...'
-    }
+  // KaTeX loads on first use; parsing a document with math loads it, so a
+  // server render after parsing typesets. Until then, and for unfinished or
+  // invalid TeX, the source shows.
+  let loaded = $state(false)
+  let html = $derived.by(() => {
+    void loaded
+    return typesetMath(content, !isInline)
+  })
+
+  $effect(() => {
+    if (html === undefined) loadKatex().then(() => (loaded = true), () => {})
   })
 </script>
 
 <!-- eslint-disable svelte/no-at-html-tags -- KaTeX output is safe rendered HTML -->
 {#if isInline}
-  <span class="math inline">{@html mathml}</span>
+  <span class="math inline">{#if html}{@html html}{:else}{content}{/if}</span>
 {:else}
-  <div class="math block">{@html mathml}</div>
+  <div class="math block">{#if html}{@html html}{:else}{content}{/if}</div>
 {/if}

packages/comark-svelte/test/math/index.svelte.test.ts

@@ -10,20 +10,21 @@ describe('Math component', () => {
     const screen = await render(Math, { content: 'x^2', class: 'inline' })
     const wrapper = screen.container.querySelector<HTMLElement>('.math.inline')!
     expect(wrapper).not.toBeNull()
-    expect(wrapper.querySelector('.katex')).not.toBeNull()
+    await expect.poll(() => wrapper.querySelector('.katex')).not.toBeNull()
   })
 
   it('renders display math with KaTeX', async () => {
     const screen = await render(Math, { content: 'E = mc^2', class: '' })
     const wrapper = screen.container.querySelector<HTMLElement>('.math.block')!
     expect(wrapper).not.toBeNull()
-    expect(wrapper.querySelector('.katex')).not.toBeNull()
+    await expect.poll(() => wrapper.querySelector('.katex')).not.toBeNull()
   })
 
-  it('handles invalid LaTeX gracefully', async () => {
+  it('shows the TeX source for invalid LaTeX', async () => {
     const screen = await render(Math, { content: '\\invalid{', class: '' })
     const wrapper = screen.container.querySelector<HTMLElement>('.math.block')!
     expect(wrapper).not.toBeNull()
+    expect(wrapper.textContent).toBe('\\invalid{')
   })
 })
 

packages/comark-svelte/test/math/index.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest'
+import { beforeAll, describe, expect, it } from 'vitest'
 import { render } from 'svelte/server'
 import { parseMarkdown } from 'comark'
+import { loadKatex } from 'comark/plugins/math'
 import math, { Math } from '../../src/plugins/math'
 import MarkdownDocument from '../../src/components/MarkdownDocument.svelte'
 
@@ -10,6 +11,8 @@ function html(body: string): string {
 }
 
 describe('Math component (server)', () => {
+  beforeAll(() => loadKatex())
+
   it('renders inline math', () => {
     const { body } = render(Math, {
       props: { content: 'x^2', class: 'inline' },
@@ -33,8 +36,7 @@ describe('Math component (server)', () => {
       props: { content: '\\invalid{', class: '' },
     })
     const output = html(body)
-    // Should render fallback rather than throwing
-    expect(output).toContain('<div class="math block">')
+    expect(output).toContain('<div class="math block">\\invalid{</div>')
   })
 })