fix(katex): improve error handling for worker initialization and fallback rendering

Author: Simon-He95

src/components/MathBlockNode/MathBlockNode.vue

@@ -44,33 +44,44 @@ function renderMath() {
       mathBlockElement.value.innerHTML = html
       hasRenderedOnce = true
     })
-    .catch(() => {
+    .catch((err: any) => {
       // ignore if a newer render was requested or component unmounted
       if (isUnmounted || renderId !== currentRenderId)
         return
       if (!mathBlockElement.value)
         return
-      // 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
+
+      // If the worker failed to initialize (e.g. bad new Worker path), the
+      // worker client will return a special error with code 'WORKER_INIT_ERROR'
+      // and `fallbackToRenderer = true`. In that case, perform a synchronous
+      // KaTeX render on the main thread as a fallback. If the error is a
+      // KaTeX render error from the worker (syntax), we should ignore it here
+      // and fall through to the raw/text fallback below.
+      if (err?.code === 'WORKER_INIT_ERROR' || err?.fallbackToRenderer) {
         try {
-          setKaTeXCache(props.node.content, true, html)
+          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
+          }
+          return
         }
         catch {
-          // ignore cache set errors
+          // if synchronous render fails, fall through to raw/text fallback
         }
       }
-      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
-        }
+
+      // 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
       }
     })
 }

src/components/MathInlineNode/MathInlineNode.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import katex from 'katex'
 import { computed, onBeforeUnmount, onMounted, ref, useAttrs, watch } from 'vue'
 import { renderKaTeXInWorker } from '../../workers/katexWorkerClient'
 
@@ -55,11 +56,28 @@ function renderMath() {
       mathElement.value.innerHTML = html
       hasRenderedOnce = true
     })
-    .catch(() => {
+    .catch((err: any) => {
       if (isUnmounted || renderId !== currentRenderId)
         return
       if (!mathElement.value)
         return
+
+      // Only attempt synchronous KaTeX fallback when the worker failed to initialize.
+      // If the worker returned a render error (syntax), leave the loading state as-is
+      // and don't try to synchronously render here to avoid surfacing KaTeX errors.
+      if (err?.code === 'WORKER_INIT_ERROR' || err?.fallbackToRenderer) {
+        try {
+          const html = katex.renderToString(props.node.content, { throwOnError: true, displayMode: false })
+          renderingLoading.value = false
+          mathElement.value.innerHTML = html
+          hasRenderedOnce = true
+          return
+        }
+        catch {
+          // fall through to existing loading/raw behaviour
+        }
+      }
+
       if (!hasRenderedOnce || !props.node.loading) {
         renderingLoading.value = true
         // mathElement.value.textContent = props.node.raw
@@ -112,12 +130,15 @@ const attrs = useAttrs()
 </script>
 
 <template>
-  <!-- <span v-if="renderingLoading"
-      :style="cssVars"
-  >Loading...</span> -->
   <span v-show="renderingLoading" class="math-loading inline-flex items-baseline gap-1.5" :aria-hidden="!node.loading ? 'true' : 'false'" v-bind="attrs" :style="cssVars">
     <span class="math-text-wrapper relative inline-flex">
-      <span class="leading-[normal] math-text">Loading...</span>
+      <span class="leading-[normal] math-text">
+        <!-- Allow consumers to override the loading content via a named slot `loading`,
+             or via the default slot. Fallback to the original text when no slot is provided. -->
+        <slot name="loading">
+          <slot>Loading...</slot>
+        </slot>
+      </span>
       <span class="underline-anim" aria-hidden="true" />
     </span>
   </span>

src/components/MermaidBlockNode/MermaidBlockNode.vue

@@ -988,10 +988,7 @@ function cleanupAfterLoadingSettled() {
     previewPollController = null
   }
   // terminate parser worker to free resources; it will be recreated on demand
-  try {
-    terminateMermaidWorker()
-  }
-  catch {}
+  terminateMermaidWorker()
 }
 
 function scheduleNextPreviewPoll(delay = 800) {
@@ -1233,10 +1230,7 @@ onUnmounted(() => {
     currentWorkController.abort()
     currentWorkController = null
   }
-  try {
-    terminateMermaidWorker()
-  }
-  catch {}
+  terminateMermaidWorker()
   stopPreviewPolling()
 })
 

src/utils/markdown.ts

@@ -208,23 +208,29 @@ export async function renderMarkdownAsync(md: MarkdownIt, content: string) {
       try {
         return await renderKaTeXInWorker(latex, false, 800)
       }
-      catch {
-        try {
-          const data = katex.renderToString(latex, {
-            throwOnError: true,
-            displayMode: false,
-          })
+      catch (err: any) {
+        // Only fallback to synchronous main-thread KaTeX render if the worker
+        // couldn't be instantiated (init error). If the worker reported a
+        // render/syntax error, we should not treat it as an init failure.
+        if (err?.code === 'WORKER_INIT_ERROR' || err?.fallbackToRenderer) {
           try {
-            setKaTeXCache(latex, false, data)
+            const data = katex.renderToString(latex, {
+              throwOnError: true,
+              displayMode: false,
+            })
+            try {
+              setKaTeXCache(latex, false, data)
+            }
+            catch {
+              // ignore cache set errors
+            }
+            return data
           }
           catch {
-            // ignore cache set errors
+            return null
           }
-          return data
-        }
-        catch {
-          return null
         }
+        return null
       }
     })()
   })