fix(math): enhance KaTeX rendering with caching and debug support

Simon-He95 · Simon-He95 · commit b22ffa9df972 · 2025-10-10T19:15:10.000+08:00
diff --git a/src/components/MathBlockNode/MathBlockNode.vue b/src/components/MathBlockNode/MathBlockNode.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
+import katex from 'katex'
 import { onBeforeUnmount, onMounted, ref, watch } from 'vue'
-import { renderKaTeXInWorker } from '../../workers/katexWorkerClient'
+import { renderKaTeXInWorker, setKaTeXCache } from '../../workers/katexWorkerClient'
 
 const props = defineProps<{
   node: {
@@ -49,9 +50,27 @@ function renderMath() {
         return
       if (!mathBlockElement.value)
         return
-      // show raw fallback when we never successfully rendered before or when loading flag is false
-      if (!hasRenderedOnce || !props.node.loading) {
-        mathBlockElement.value.textContent = props.node.raw
+      // Try a synchronous KaTeX render on the main thread as a fallback
+      try {
+        const html = katex.renderToString(props.node.content, {
+          throwOnError: true,
+          displayMode: true,
+        })
+        mathBlockElement.value.innerHTML = html
+        hasRenderedOnce = true
+        // populate worker client cache so future calls hit cache
+        try {
+          setKaTeXCache(props.node.content, true, html)
+        }
+        catch {
+          // ignore cache set errors
+        }
+      }
+      catch {
+        // show raw fallback when we never successfully rendered before or when loading flag is false
+        if (!hasRenderedOnce || !props.node.loading) {
+          mathBlockElement.value.textContent = props.node.raw
+        }
       }
     })
 }
diff --git a/src/components/MathInlineNode/MathInlineNode.vue b/src/components/MathInlineNode/MathInlineNode.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
+import katex from 'katex'
 import { onBeforeUnmount, onMounted, ref, watch } from 'vue'
-import { renderKaTeXInWorker } from '../../workers/katexWorkerClient'
+import { renderKaTeXInWorker, setKaTeXCache } from '../../workers/katexWorkerClient'
 
 const props = defineProps<{
   node: {
@@ -44,8 +45,25 @@ function renderMath() {
         return
       if (!mathElement.value)
         return
-      if (!hasRenderedOnce || !props.node.loading)
-        mathElement.value.textContent = props.node.raw
+      // Try synchronous render as a fallback
+      try {
+        const html = katex.renderToString(props.node.content, {
+          throwOnError: true,
+          displayMode: false,
+        })
+        mathElement.value.innerHTML = html
+        hasRenderedOnce = true
+        try {
+          setKaTeXCache(props.node.content, false, html)
+        }
+        catch {
+          // ignore cache set errors
+        }
+      }
+      catch {
+        if (!hasRenderedOnce || !props.node.loading)
+          mathElement.value.textContent = props.node.raw
+      }
     })
 }
 
diff --git a/src/utils/markdown.ts b/src/utils/markdown.ts
@@ -8,7 +8,7 @@ import markdownItSub from 'markdown-it-sub'
 import markdownItSup from 'markdown-it-sup'
 import * as markdownItCheckbox from 'markdown-it-task-checkbox'
 import { useSafeI18n } from '../composables/useSafeI18n'
-import { renderKaTeXInWorker } from '../workers/katexWorkerClient'
+import { renderKaTeXInWorker, setKaTeXCache } from '../workers/katexWorkerClient'
 
 import {
   parseInlineTokens,
@@ -210,10 +210,17 @@ export async function renderMarkdownAsync(md: MarkdownIt, content: string) {
       }
       catch {
         try {
-          return katex.renderToString(latex, {
+          const data = katex.renderToString(latex, {
             throwOnError: true,
             displayMode: false,
           })
+          try {
+            setKaTeXCache(latex, false, data)
+          }
+          catch {
+            // ignore cache set errors
+          }
+          return data
         }
         catch {
           return null
diff --git a/src/workers/katexRenderer.worker.ts b/src/workers/katexRenderer.worker.ts
@@ -1,9 +1,12 @@
 import katex from 'katex'
 
 interface MessageIn {
-  id: string
-  content: string
+  // supports two shapes: init messages and render messages
+  type?: 'init' | 'render'
+  id?: string
+  content?: string
   displayMode?: boolean
+  debug?: boolean
 }
 
 interface MessageOut {
@@ -12,11 +15,32 @@ interface MessageOut {
   error?: string
 }
 
-// eslint-disable-next-line no-restricted-globals
-self.addEventListener('message', (ev: MessageEvent<MessageIn>) => {
-  const { id, content, displayMode = true } = ev.data
+let DEBUG = false
+
+;(globalThis as any).addEventListener('message', (ev: MessageEvent<MessageIn>) => {
+  const data = ev.data || {}
+  if (data.type === 'init') {
+    DEBUG = !!data.debug
+    try {
+      if (DEBUG)
+        console.debug('[katexRenderer.worker] debug enabled')
+    }
+    catch {}
+    return
+  }
+
+  const id = data.id ?? ''
+  const content = data.content ?? ''
+  const displayMode = data.displayMode ?? true
 
   try {
+    try {
+      // note: use console for visibility in DevTools when debugging worker
+      if (DEBUG)
+        console.debug('[katexRenderer.worker] render start', { id, displayMode, content })
+    }
+    catch {}
+
     // renderToString is CPU-bound but doesn't touch the DOM, so it's safe in a worker
     const html = katex.renderToString(content, {
       throwOnError: true,
@@ -26,13 +50,45 @@ self.addEventListener('message', (ev: MessageEvent<MessageIn>) => {
     })
 
     const out: MessageOut & { content: string, displayMode: boolean } = { id, html, content, displayMode }
-    // send back the generated HTML and original input for caching
-    // eslint-disable-next-line no-restricted-globals
-    ;(self as any).postMessage(out)
+    try {
+      // send back the generated HTML and original input for caching
+
+      ;(globalThis as any).postMessage(out)
+      try {
+        if (DEBUG)
+          console.debug('[katexRenderer.worker] render success', { id })
+      }
+      catch {}
+    }
+    catch (postErr) {
+      try {
+        console.error('[katexRenderer.worker] failed to postMessage result', postErr)
+      }
+      catch {}
+    }
   }
   catch (err: any) {
     const out: MessageOut & { content: string, displayMode: boolean } = { id, error: String(err?.message ?? err), content, displayMode }
-    // eslint-disable-next-line no-restricted-globals
-    ;(self as any).postMessage(out)
+    try {
+      ;(globalThis as any).postMessage(out)
+    }
+    catch (postErr) {
+      try {
+        console.error('[katexRenderer.worker] failed to postMessage error', postErr)
+      }
+      catch {}
+    }
+  }
+})
+
+// Catch any uncaught errors in the worker and attempt to inform the main thread
+;(globalThis as any).addEventListener('error', (ev: ErrorEvent) => {
+  try {
+    console.error('[katexRenderer.worker] uncaught error', ev.message, ev.error)
+  }
+  catch {}
+  try {
+    ;(globalThis as any).postMessage({ id: '__worker_uncaught__', error: String(ev.message ?? ev.error), content: '', displayMode: true })
   }
+  catch {}
 })
diff --git a/src/workers/katexWorkerClient.ts b/src/workers/katexWorkerClient.ts
@@ -5,6 +5,10 @@ interface Pending {
 }
 
 let worker: Worker | null = null
+// runtime debug flag controlled by the main thread
+let DEBUG_KATEX_WORKER = false
+// telemetry / diagnostics listeners for worker errors/timeouts
+const errorListeners = new Set<(err: any) => void>()
 const pending = new Map<string, Pending>()
 // Simple in-memory cache to avoid repeated renders for identical input.
 const cache = new Map<string, string>()
@@ -17,27 +21,53 @@ function ensureWorker() {
     // Only create a Worker in a browser environment
     if (typeof window === 'undefined') {
       worker = null
+      try {
+        console.warn('[katexWorkerClient] window is undefined — Web Worker will not be created')
+      }
+      catch {}
     }
     else {
       // Vite-friendly worker instantiation. Bundlers will inline the worker when configured.
       worker = new Worker(new URL('./katexRenderer.worker.ts', import.meta.url), { type: 'module' })
+      try {
+        // send initial debug flag to worker so it can gate debug logs
+        ;(worker as any).postMessage({ type: 'init', debug: DEBUG_KATEX_WORKER })
+      }
+      catch {}
     }
   }
   catch {
     worker = null
+    try {
+      console.warn('[katexWorkerClient] failed to instantiate Web Worker')
+    }
+    catch {}
   }
 
   if (worker) {
     worker.addEventListener('message', (ev: MessageEvent) => {
       const { id, html, error, content, displayMode } = ev.data as any
       const p = pending.get(id)
       if (!p) {
+        try {
+          console.warn('[katexWorkerClient] received message for unknown id', id, { content, displayMode, error })
+        }
+        catch {}
         return
       }
       (globalThis as any).clearTimeout(p.timeoutId)
       pending.delete(id)
       if (error) {
-        p.reject(new Error(error))
+        const err = new Error(String(error))
+        ;(err as any).name = 'WorkerRenderError'
+        ;(err as any).code = 'WORKER_RENDER_ERROR'
+        ;(err as any).content = content
+        ;(err as any).displayMode = displayMode
+        try {
+          console.warn('[katexWorkerClient] worker returned an error for id', id, String(error))
+        }
+        catch {}
+        p.reject(err)
         return
       }
 
@@ -51,17 +81,79 @@ function ensureWorker() {
           cache.delete(firstKey)
         }
       }
-      catch {
-        // ignore cache errors
+      catch (e) {
+        try {
+          console.warn('[katexWorkerClient] cache set failed', e)
+        }
+        catch {}
       }
 
       p.resolve(html)
     })
+
+    worker.addEventListener('error', (ev) => {
+      try {
+        console.error('[katexWorkerClient] Worker error', ev)
+      }
+      catch {}
+      // reject all pending promises so callers can fallback
+      for (const [_id, p] of pending.entries()) {
+        try {
+          const err = new Error('Worker crashed')
+          ;(err as any).name = 'WorkerCrashed'
+          ;(err as any).code = 'WORKER_CRASHED'
+          try {
+            for (const h of errorListeners) {
+              try {
+                h(err)
+              }
+              catch {}
+            }
+          }
+          catch {}
+          p.reject(err)
+        }
+        catch {}
+      }
+      pending.clear()
+    })
+
+    worker.addEventListener('messageerror', (ev) => {
+      try {
+        console.error('[katexWorkerClient] Worker messageerror', ev)
+      }
+      catch {}
+    })
   }
 
   return worker
 }
 
+// Allow toggling verbose worker debug logs at runtime. When set, we post an init
+// message to an existing worker so the worker can enable logs.
+export function setKaTeXWorkerDebug(enabled: boolean) {
+  DEBUG_KATEX_WORKER = !!enabled
+  if (worker) {
+    try {
+      ;(worker as any).postMessage({ type: 'init', debug: DEBUG_KATEX_WORKER })
+    }
+    catch {
+      try {
+        console.warn('[katexWorkerClient] failed to send debug init to worker')
+      }
+      catch {}
+    }
+  }
+}
+
+export function onKaTeXWorkerError(fn: (err: any) => void) {
+  errorListeners.add(fn)
+}
+
+export function offKaTeXWorkerError(fn: (err: any) => void) {
+  errorListeners.delete(fn)
+}
+
 export async function renderKaTeXInWorker(content: string, displayMode = true, timeout = 2000, signal?: AbortSignal): Promise<string> {
   // Quick cache hit
   const cacheKey = `${displayMode ? 'd' : 'i'}:${content}`
@@ -84,7 +176,19 @@ export async function renderKaTeXInWorker(content: string, displayMode = true, t
     const id = Math.random().toString(36).slice(2)
     const timeoutId = (globalThis as any).setTimeout(() => {
       pending.delete(id)
-      reject(new Error('Worker render timed out'))
+      const err = new Error('Worker render timed out')
+      ;(err as any).name = 'WorkerTimeout'
+      ;(err as any).code = 'WORKER_TIMEOUT'
+      try {
+        for (const h of errorListeners) {
+          try {
+            h(err)
+          }
+          catch {}
+        }
+      }
+      catch {}
+      reject(err)
     }, timeout)
 
     // Listen for abort to cancel this pending request
@@ -105,6 +209,22 @@ export async function renderKaTeXInWorker(content: string, displayMode = true, t
   })
 }
 
+// Allow callers (e.g. main-thread fallback renderers) to populate the internal cache
+// so that synchronous renders can benefit subsequent worker-based calls.
+export function setKaTeXCache(content: string, displayMode = true, html: string) {
+  try {
+    const cacheKey = `${displayMode ? 'd' : 'i'}:${content}`
+    cache.set(cacheKey, html)
+    if (cache.size > CACHE_MAX) {
+      const firstKey = cache.keys().next().value
+      cache.delete(firstKey)
+    }
+  }
+  catch {
+    // ignore cache errors
+  }
+}
+
 // When a worker response arrives we set the cache (handled in ensureWorker message handler),
 // but the handler does not currently set cache; to keep cache coherent, also set here by
 // wrapping the Promise resolution above would be ideal. However, pending resolution occurs
