@barzhsieh/nuxt-content-mermaid 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 [English](./README.md) | [中文](./README.zh-TW.md)
 
-# nuxt-mermaid-content
+# nuxt-content-mermaid
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -9,32 +9,50 @@
 [![Mermaid](https://img.shields.io/badge/mermaid-11.x-0f5b9d?logo=mermaid)](https://mermaid.js.org/)
 [![Nuxt Content](https://img.shields.io/badge/Nuxt%20Content-3.x-00DC82?logo=nuxt.js)](https://content.nuxt.com/)
 
-A Nuxt module designed for integrating Mermaid with `@nuxt/content`. It automatically converts `mermaid` code blocks in Markdown into responsive chart components, and supports lazy loading and dark/light theme switching.
+A Nuxt module designed for integrating [**Mermaid**](https://mermaid.js.org/) with [**Nuxt Content v3**](https://content.nuxt.com/docs/getting-started).
+It automatically converts `mermaid` code blocks in Markdown into responsive chart components, and supports lazy loading and dark/light theme switching.
 
 ## Features
 
 - **Automatic conversion**: Parses Markdown code blocks and replaces them with a `<Mermaid>` rendering component.
 - **Performance friendly**: Supports lazy loading — Mermaid core and related resources are only loaded when the component mounts.
 - **Theme integration**: Integrates with `@nuxtjs/color-mode` to automatically switch between light and dark Mermaid themes.
-- **Highly customizable**: Allows custom wrapper components, loading spinners, and custom CDN or local import sources.
+- **Highly customizable**: Allows custom wrapper components, loading spinners, error views, and custom CDN or local import sources.
 - **Runtime config**: Settings can be overridden at deployment time through runtime config / environment variables.
 
 ## Requirements
 
-- Nuxt 4 (`nuxt@^4.0.0`)
-- `@nuxt/content@^3.8.0`
+- Nuxt 3.19+ or 4.1+ (`nuxt@^3.20.1 || ^4.1.0`)
+- `@nuxt/content@>=3.5.0`
 
 ## Quick Setup
 
 ### 1. Install the module
 
+**Auto-setup (adds to `modules` automatically):**
+
 ```bash
 npx nuxi module add @barzhsieh/nuxt-content-mermaid
 ```
 
+> Nuxt CLI installs third-party modules as regular `dependencies` by default. If you prefer `devDependencies`, move it after install or use the manual option below.
+
+**Install as dev dependency (manual modules entry):**
+
+```bash
+# pnpm
+pnpm add -D @barzhsieh/nuxt-content-mermaid
+
+# npm
+npm install -D @barzhsieh/nuxt-content-mermaid
+
+# yarn
+yarn add -D @barzhsieh/nuxt-content-mermaid
+```
+
 ### 2. Configure `nuxt.config.ts`
 
-Make sure the module is included in the `modules` array (if you used `nuxi module add`, this is added automatically):
+Make sure the module is included in the `modules` array (skip if you used `nuxi module add`):
 
 ```ts
 export default defineNuxtConfig({
@@ -84,6 +102,7 @@ export default defineNuxtConfig({
     components: {
       renderer: undefined,
       spinner: undefined,
+      error: undefined,
     },
   },
 });
@@ -118,6 +137,7 @@ export default defineNuxtConfig({
 | :------------------------ | :------- | :---------- | :----------------------------------------------------------------------- |
 | `components.renderer`     | `string` | `undefined` | Optional: custom Mermaid renderer component name.                        |
 | `components.spinner`      | `string` | `undefined` | Optional: global loading spinner component name.                         |
+| `components.error`        | `string` | `undefined` | Optional: global error component name when Mermaid rendering fails.      |
 
 > **Note**: All options can be overridden at runtime via `runtimeConfig.public.mermaidContent`.
 
@@ -164,6 +184,117 @@ If you want full control over rendering (for example to add a border, zoom contr
    </template>
    ```
 
+#### Loading Indicator
+
+The module renders a built-in spinner before the first Mermaid render. If you set `components.spinner`, the named component will replace the default spinner and will be passed into your custom renderer as a `spinner` prop.
+
+Minimal example that uses the provided spinner while waiting for your own loading logic:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  mermaidContent: {
+    components: {
+      renderer: 'MyCustomMermaid',
+      spinner: 'MySpinner', // optional: globally replace the default spinner
+    },
+  },
+})
+```
+
+```vue
+<!-- components/MyCustomMermaid.vue -->
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import type { Component } from 'vue'
+
+const props = defineProps<{ spinner: Component | string }>()
+const loading = ref(true)
+onMounted(() => { loading.value = false })
+</script>
+
+<template>
+  <div class="my-mermaid">
+    <component v-if="loading" :is="props.spinner" />
+    <Mermaid v-else>
+      <slot />
+    </Mermaid>
+  </div>
+</template>
+```
+
+### Wrapper Example
+
+You can wrap `<Mermaid>` inside your own Vue component.
+For example, you can bundle a title, loading state, and error/fallback UI, then drop it anywhere in templates:
+
+```vue
+<!-- WrapperMermaid.vue -->
+<template>
+  <section>
+    <header v-if="title">{{ title }}</header>
+
+    <Mermaid>
+      <slot>
+        <pre><code>{{ code }}</code></pre>
+      </slot>
+
+      <template #loading>
+        <component :is="spinner" v-if="spinner" />
+        <p v-else>Diagram loading…</p>
+      </template>
+
+      <template #error="{ error, source }">
+        <p>Render failed: {{ error instanceof Error ? error.message : String(error) }}</p>
+        <pre><code>{{ source }}</code></pre>
+      </template>
+    </Mermaid>
+  </section>
+</template>
+```
+
+```vue
+<!-- usage -->
+<WrapperMermaid
+  title="Demo Diagram"
+  spinner="MySpinner"
+>
+  <pre><code>graph TD; A-->B; B-->C; C-->A</code></pre>
+</WrapperMermaid>
+```
+
+Copy or adapt this pattern to centralize the common slots you want to reuse.
+
+### Error Handling
+
+When Mermaid parsing/rendering fails, the component exposes an `error` slot and supports a global error component via `components.error`. Both receive the thrown error and the original Mermaid source for inspection.
+
+```vue
+<Mermaid>
+  <pre><code>graph TD; A-->B; B-->C; C-->A</code></pre>
+
+  <template #error="{ error, source }">
+    <p>Render failed: {{ error instanceof Error ? error.message : String(error) }}</p>
+    <details>
+      <summary>Show definition</summary>
+      <pre><code>{{ source }}</code></pre>
+    </details>
+  </template>
+</Mermaid>
+```
+
+To reuse a global error view everywhere, register it once and reference it in config:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  mermaidContent: {
+    components: {
+      error: 'MermaidError', // globally registered component name
+    },
+  },
+})
+```
 ## Contribution
 
 <details>

package/README.zh-TW.md

@@ -1,6 +1,6 @@
 [English](./README.md) | [中文](./README.zh-TW.md)
 
-# nuxt-mermaid-content
+# nuxt-content-mermaid
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -9,32 +9,50 @@
 [![Mermaid](https://img.shields.io/badge/mermaid-11.x-0f5b9d?logo=mermaid)](https://mermaid.js.org/)
 [![Nuxt Content](https://img.shields.io/badge/Nuxt%20Content-3.x-00DC82?logo=nuxt.js)](https://content.nuxt.com/)
 
-專為 Nuxt + `@nuxt/content` 設計的 Mermaid 整合模組。能自動將 Markdown 中的 ```mermaid 區塊轉換為響應式的圖表元件，並支援 Lazy Loading 與深色模式切換。
+專為 [**Nuxt Content v3**](https://content.nuxt.com/docs/getting-started) 整合 [**Mermaid**](https://mermaid.js.org/) 的模組。
+能自動將 Markdown 中的 ```mermaid 區塊轉換為響應式的圖表元件，並支援 Lazy Loading 與深色模式切換。
 
 ## Features
 
 - **自動轉換**：解析 Markdown 代碼區塊並替換為 `<Mermaid>` 渲染元件。
 - **效能優化**：支援 Lazy Loading，僅在元件掛載時載入 Mermaid 核心與資源。
 - **主題整合**：無縫整合 `@nuxtjs/color-mode`，自動切換 Light/Dark 對應主題。
-- **高度客製**：支援自訂渲染元件（Wrapper）、Loading Spinner 及 CDN 來源。
+- **高度客製**：支援自訂渲染元件（Wrapper）、Loading Spinner、錯誤畫面以及 CDN 來源。
 - **Runtime Config**：支援透過環境變數動態覆寫設定。
 
 ## 使用前提
 
-- Nuxt 4 (`nuxt@^4.0.0`)
-- `@nuxt/content@^3.8.0`（必須安裝）
+- Nuxt 3.19 以上或 4.1 以上（`nuxt@^3.20.1 || ^4.1.0`）
+- `@nuxt/content@>=3.5.0`
 
 ## Quick Setup
 
 ### 1. 安裝模組
 
+**自動設定（自動寫入 `modules`）：**
+
 ```bash
 npx nuxi module add @barzhsieh/nuxt-content-mermaid
 ```
 
+> Nuxt CLI 對第三方模組預設會裝到 `dependencies`。若想放 `devDependencies`，請裝完後移動或改用下方手動安裝。
+
+**裝到 `devDependencies`（需手動加入 `modules`）：**
+
+```bash
+# pnpm
+pnpm add -D @barzhsieh/nuxt-content-mermaid
+
+# npm
+npm install -D @barzhsieh/nuxt-content-mermaid
+
+# yarn
+yarn add -D @barzhsieh/nuxt-content-mermaid
+```
+
 ### 2. 配置 `nuxt.config.ts`
 
-確保模組已加入 `modules` 清單（若使用 `nuxi module add` 則會自動加入）：
+確保模組已加入 `modules` 清單（若使用 `nuxi module add` 則可略過）：
 
 ```ts
 export default defineNuxtConfig({
@@ -84,6 +102,7 @@ export default defineNuxtConfig({
     components: {
       renderer: undefined,
       spinner: undefined,
+      error: undefined,
     },
   },
 });
@@ -118,6 +137,7 @@ export default defineNuxtConfig({
 | :----------------------- | :------- | :--------- | :----------------------------------------------------- |
 | `components.renderer`    | `string` | `undefined` | 指定自訂的 Mermaid 實作元件名稱（見進階用法）。        |
 | `components.spinner`     | `string` | `undefined` | 指定全域的 Loading 元件名稱。                          |
+| `components.error`       | `string` | `undefined` | 指定全域的錯誤顯示元件名稱，渲染失敗時會使用。         |
 
 > **Note**: 所有設定皆可透過 `runtimeConfig.public.mermaidContent` 在部署時進行覆寫。
 
@@ -164,6 +184,117 @@ export default defineNuxtConfig({
    </template>
    ```
 
+#### 載入中指示
+
+模組在首次渲染前會使用內建的 spinner，如需替換可在 `components.spinner` 指定元件名稱；該元件也會以 `spinner` prop 傳入你的自訂渲染元件，方便直接渲染。
+
+以下是極簡的設定與元件示例：
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  mermaidContent: {
+    components: {
+      renderer: 'MyCustomMermaid',
+      spinner: 'MySpinner', // 選填：改用自己的全域 Loading 元件
+    }
+  }
+})
+```
+
+```vue
+<!-- components/MyCustomMermaid.vue -->
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import type { Component } from 'vue'
+
+const props = defineProps<{ spinner: Component | string }>()
+const loading = ref(true)
+onMounted(() => { loading.value = false })
+</script>
+
+<template>
+  <div class="my-mermaid">
+    <component v-if="loading" :is="props.spinner" />
+    <Mermaid v-else>
+      <slot />
+    </Mermaid>
+  </div>
+</template>
+```
+
+### 元件使用方式
+
+可以用 `<Mermaid>` 自己包一個的 Vue 元件 。
+例如，你可以同時放入標題、Loading 與錯誤顯示，之後就能在任意模板重複使用：
+```vue
+<!-- WrapperMermaid.vue -->
+<template>
+  <section>
+    <header v-if="title">{{ title }}</header>
+
+    <Mermaid>
+      <slot>
+        <pre><code>{{ code }}</code></pre>
+      </slot>
+
+      <template #loading>
+        <component :is="spinner" v-if="spinner" />
+        <p v-else>Diagram loading…</p>
+      </template>
+
+      <template #error="{ error, source }">
+        <p>渲染失敗：{{ error instanceof Error ? error.message : String(error) }}</p>
+        <pre><code>{{ source }}</code></pre>
+      </template>
+    </Mermaid>
+  </section>
+</template>
+```
+
+```vue
+<!-- 使用範例 -->
+<WrapperMermaid
+  title="Demo Diagram"
+  spinner="MySpinner"
+>
+  <pre><code>graph TD; A-->B; B-->C; C-->A</code></pre>
+</WrapperMermaid>
+```
+
+可依需求調整此模式，把常用的 slot 寫在一個可重用的包裝元件中。
+
+### 錯誤處理
+
+當 Mermaid 解析或渲染失敗時，`<Mermaid>` 會觸發 `error` slot，並可透過 `components.error` 指定全域錯誤元件。兩者都會拿到錯誤內容與原始 Mermaid 定義，方便除錯。
+
+```vue
+<Mermaid>
+  <pre><code>graph TD; A-->B; B-->C; C-->A</code></pre>
+
+  <template #error="{ error, source }">
+    <p>渲染失敗：{{ error instanceof Error ? error.message : String(error) }}</p>
+    <details>
+      <summary>查看原始定義</summary>
+      <pre><code>{{ source }}</code></pre>
+    </details>
+  </template>
+</Mermaid>
+```
+
+若想一次註冊、全域套用自訂錯誤畫面，可在設定中指定元件名稱：
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  mermaidContent: {
+    components: {
+      error: 'MermaidError', // 全域註冊的元件名稱
+    },
+  },
+})
+```
+
 ## Contribution
 
 <details>

package/dist/module.d.mts

@@ -19,6 +19,14 @@ interface ModuleOptions {
          * Pass-through to `mermaid.initialize`
          */
         init?: MermaidConfig;
+        /**
+         * Whether to lazy load the diagram when it enters the viewport.
+         * Can be a boolean or an object with IntersectionObserver options.
+         * @default true
+         */
+        lazy?: boolean | {
+            threshold?: number;
+        };
     };
     /**
      * Options related to theme handling
@@ -48,6 +56,12 @@ interface ModuleOptions {
          * If not provided, the module's built-in `Spinner.vue` will be used.
          */
         spinner?: string;
+        /**
+         * Error component name to display when Mermaid rendering fails.
+         * This should be a globally available component name (e.g., under the project `components/` directory).
+         * If not provided, the module's built-in fallback message will be used.
+         */
+        error?: string;
     };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.json

@@ -2,9 +2,9 @@
   "name": "@barzhsieh/nuxt-content-mermaid",
   "configKey": "mermaidContent",
   "compatibility": {
-    "nuxt": "^4.0.0"
+    "nuxt": "^3.20.1 || ^4.1.0"
   },
-  "version": "1.0.1",
+  "version": "1.0.3",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -7,7 +7,8 @@ const DEFAULTS = {
   enabled: true,
   loader: {
     importSource: DEFAULT_IMPORT_SOURCE,
-    init: { ...DEFAULT_MERMAID_INIT }
+    init: { ...DEFAULT_MERMAID_INIT },
+    lazy: true
   },
   theme: {
     useColorModeTheme: true,
@@ -16,7 +17,8 @@ const DEFAULTS = {
   },
   components: {
     renderer: void 0,
-    spinner: void 0
+    spinner: void 0,
+    error: void 0
   }
 };
 const module$1 = defineNuxtModule({
@@ -24,7 +26,7 @@ const module$1 = defineNuxtModule({
     name: "@barzhsieh/nuxt-content-mermaid",
     configKey: "mermaidContent",
     compatibility: {
-      nuxt: "^4.0.0"
+      nuxt: "^3.20.1 || ^4.1.0"
     }
   },
   defaults: {

package/dist/runtime/components/Mermaid.d.vue.ts

@@ -1,14 +1,17 @@
-declare var __VLS_8: {}, __VLS_10: {}, __VLS_12: {}, __VLS_14: {}, __VLS_22: {};
+declare var __VLS_1: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {}, __VLS_21: {
+    error: unknown;
+    source: string;
+};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_8) => any;
+    default?: (props: typeof __VLS_1) => any;
 } & {
-    default?: (props: typeof __VLS_10) => any;
+    default?: (props: typeof __VLS_9) => any;
 } & {
-    default?: (props: typeof __VLS_12) => any;
+    default?: (props: typeof __VLS_11) => any;
 } & {
-    loading?: (props: typeof __VLS_14) => any;
+    loading?: (props: typeof __VLS_13) => any;
 } & {
-    default?: (props: typeof __VLS_22) => any;
+    error?: (props: typeof __VLS_21) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/runtime/components/Mermaid.vue

@@ -7,41 +7,46 @@ import {
   nextTick,
   computed,
   watch,
-  shallowRef
+  shallowRef,
+  useTemplateRef
 } from "vue";
+import { enqueueRender } from "../utils";
 import Spinner from "./Spinner.vue";
 const nuxtApp = useNuxtApp();
 const runtimeConfig = useRuntimeConfig();
-const mermaidRuntime = runtimeConfig.public?.mermaidContent || {};
-const isEnabled = mermaidRuntime.enabled !== false;
-const loaderOptions = mermaidRuntime.loader || {};
-const themeOptions = mermaidRuntime.theme || {};
-const componentOptions = mermaidRuntime.components || {};
+const mermaidContent = runtimeConfig.public?.mermaidContent || {};
+const isEnabled = mermaidContent.enabled !== false;
+const loaderOptions = mermaidContent.loader || {};
+const themeOptions = mermaidContent.theme || {};
+const componentOptions = mermaidContent.components || {};
+const lazyOption = loaderOptions.lazy;
+const isLazy = lazyOption !== false;
+const lazyThreshold = typeof lazyOption === "object" && typeof lazyOption.threshold === "number" ? lazyOption.threshold : 0.1;
+const baseMermaidInit = loaderOptions.init || {};
+const useColorModeTheme = themeOptions.useColorModeTheme;
+const lightTheme = themeOptions.light;
+const darkTheme = themeOptions.dark;
 const colorMode = nuxtApp.$colorMode;
 const { $mermaid } = nuxtApp;
-const mermaidContainer = ref(null);
-const isMounted = ref(false);
+const mermaidContainer = useTemplateRef("mermaidContainer");
 const hasRenderedOnce = ref(false);
 const isLoading = ref(false);
+const hasError = ref(false);
+const errorContent = shallowRef(null);
 let mermaidDefinition = "";
 let observer = null;
-const baseMermaidInit = loaderOptions.init || {};
-const useColorModeTheme = themeOptions.useColorModeTheme;
-const lightTheme = themeOptions.light;
-const darkTheme = themeOptions.dark;
 const mermaidTheme = computed(() => {
   if (useColorModeTheme && colorMode)
     return colorMode.value === "dark" ? darkTheme : lightTheme;
   return baseMermaidInit.theme ?? lightTheme ?? darkTheme;
 });
-const configuredSpinnerName = computed(
-  () => componentOptions.spinner?.trim() || ""
-);
+const configuredSpinnerName = computed(() => componentOptions.spinner?.trim() || "");
 const customSpinner = shallowRef(null);
-const configuredMermaidImplName = computed(
-  () => componentOptions.renderer?.trim() || ""
-);
+const configuredMermaidImplName = computed(() => componentOptions.renderer?.trim() || "");
 const customMermaidImpl = shallowRef(null);
+const configuredErrorName = computed(() => componentOptions.error?.trim() || "");
+const errorComponent = shallowRef(null);
+const spinnerComponent = computed(() => customSpinner.value || Spinner);
 function normalizeIdentifier(value) {
   return value.replace(/\.vue$/i, "").split(/[\\/]/).pop()?.replace(/[\s_-]+/g, "").toLowerCase() || "";
 }
@@ -54,59 +59,46 @@ async function resolveAppComponent(name, appComponents, label) {
   });
   if (!matchEntry) {
     console.warn(
-      `[nuxt-mermaid-content] Cannot find ${label} component:`,
+      `[nuxt-content-mermaid] Cannot find ${label} component:`,
       name
     );
     return null;
   }
   try {
-    const [, loader] = matchEntry;
-    const mod = await loader();
+    const [, componentLoader] = matchEntry;
+    const mod = await componentLoader();
     return mod.default || mod;
   } catch (error) {
     console.error(
-      `[nuxt-mermaid-content] Failed to load ${label} component:`,
+      `[nuxt-content-mermaid] Failed to load ${label} component:`,
       error
     );
     return null;
   }
 }
 if (import.meta.client && isEnabled) {
+  let watchCustomAppComponent = function(nameRef, targetRef, label) {
+    watch(
+      nameRef,
+      async (name) => {
+        if (!name) {
+          targetRef.value = null;
+          return;
+        }
+        targetRef.value = await resolveAppComponent(
+          name,
+          appComponents,
+          label
+        );
+      },
+      { immediate: true }
+    );
+  };
   const appComponents = import.meta.glob("~/components/**/*.{vue,js,ts}");
-  watch(
-    configuredSpinnerName,
-    async (name) => {
-      if (!name) {
-        customSpinner.value = null;
-        return;
-      }
-      customSpinner.value = await resolveAppComponent(
-        name,
-        appComponents,
-        "spinner"
-      );
-    },
-    { immediate: true }
-  );
-  watch(
-    configuredMermaidImplName,
-    async (name) => {
-      if (!name) {
-        customMermaidImpl.value = null;
-        return;
-      }
-      customMermaidImpl.value = await resolveAppComponent(
-        name,
-        appComponents,
-        "mermaid"
-      );
-    },
-    { immediate: true }
-  );
+  watchCustomAppComponent(configuredSpinnerName, customSpinner, "spinner");
+  watchCustomAppComponent(configuredMermaidImplName, customMermaidImpl, "mermaid");
+  watchCustomAppComponent(configuredErrorName, errorComponent, "error");
 }
-const spinnerComponent = computed(() => {
-  return customSpinner.value || Spinner;
-});
 function serializeMermaidFromNode(root) {
   const TEXT_NODE = 3;
   const ELEMENT_NODE = 1;
@@ -125,66 +117,74 @@ function serializeMermaidFromNode(root) {
   }
   return "";
 }
+function extractMermaidDefinition(container) {
+  const pre = container.querySelector("pre");
+  const code = container.querySelector("code");
+  if (code) return code.textContent?.trim() || "";
+  if (pre) return pre.textContent?.trim() || "";
+  return serializeMermaidFromNode(container).trim();
+}
 async function renderMermaid() {
   if (!mermaidContainer.value || !mermaidDefinition) return;
-  try {
-    isLoading.value = true;
-    const mermaid = await $mermaid();
-    const theme = mermaidTheme.value;
-    const initOptions = {
-      startOnLoad: false,
-      ...baseMermaidInit,
-      theme
-    };
-    mermaid.initialize(initOptions);
-    mermaidContainer.value.removeAttribute("data-processed");
-    mermaidContainer.value.textContent = mermaidDefinition;
-    await nextTick();
-    await mermaid.run({
-      nodes: [mermaidContainer.value],
-      suppressErrors: true
-    });
-    hasRenderedOnce.value = true;
-    isLoading.value = false;
-  } catch (error) {
-    console.error("[nuxt-mermaid-content]", error);
-    if (mermaidContainer.value)
-      mermaidContainer.value.innerHTML = "\u26A0\uFE0F Mermaid Diagram Error";
-    isLoading.value = false;
-  }
+  isLoading.value = true;
+  const performRender = async () => {
+    if (!mermaidContainer.value) return;
+    hasError.value = false;
+    errorContent.value = null;
+    try {
+      const mermaid = await $mermaid();
+      const initOptions = {
+        startOnLoad: false,
+        ...baseMermaidInit,
+        theme: mermaidTheme.value
+      };
+      mermaid.initialize(initOptions);
+      mermaidContainer.value.removeAttribute("data-processed");
+      mermaidContainer.value.textContent = mermaidDefinition;
+      await nextTick();
+      await mermaid.run({
+        nodes: [mermaidContainer.value],
+        suppressErrors: true
+      });
+      hasRenderedOnce.value = true;
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    } catch (error) {
+      console.error("[nuxt-content-mermaid]", error);
+      hasError.value = true;
+      errorContent.value = error;
+      if (mermaidContainer.value)
+        mermaidContainer.value.innerHTML = "";
+    } finally {
+      isLoading.value = false;
+    }
+  };
+  await enqueueRender(performRender);
 }
 function setupMermaidContainer() {
-  if (mermaidContainer.value) {
-    const pre = mermaidContainer.value.querySelector("pre");
-    const code = mermaidContainer.value.querySelector("code");
-    if (code) {
-      mermaidDefinition = code.textContent?.trim() || "";
-    } else if (pre) {
-      mermaidDefinition = pre.textContent?.trim() || "";
-    } else {
-      mermaidDefinition = serializeMermaidFromNode(
-        mermaidContainer.value
-      ).trim();
-    }
-    observer = new IntersectionObserver(
-      (entries) => {
-        if (entries[0]?.isIntersecting && !hasRenderedOnce.value) {
-          renderMermaid();
-          if (observer) {
-            observer.disconnect();
-          }
-        }
-      },
-      { threshold: 0.1 }
-    );
-    observer.observe(mermaidContainer.value);
+  const container = mermaidContainer.value;
+  if (!container) return;
+  if (!mermaidDefinition)
+    mermaidDefinition = extractMermaidDefinition(container);
+  if (!isLazy) {
+    renderMermaid();
+    return;
   }
+  observer = new IntersectionObserver(
+    (entries) => {
+      if (entries[0]?.isIntersecting && !hasRenderedOnce.value) {
+        renderMermaid();
+        if (observer) observer.disconnect();
+      }
+    },
+    { threshold: lazyThreshold }
+  );
+  observer.observe(container);
 }
-onMounted(async () => {
+onMounted(() => {
   if (!isEnabled) return;
-  isMounted.value = true;
-  await nextTick();
-  setupMermaidContainer();
+  if (mermaidContainer.value)
+    mermaidDefinition = extractMermaidDefinition(mermaidContainer.value);
+  nextTick(() => setupMermaidContainer());
 });
 onUnmounted(() => {
   if (observer) observer.disconnect();
@@ -196,46 +196,63 @@ watch(mermaidTheme, () => {
 </script>
 
 <template>
-  <component
-    :is="customMermaidImpl"
-    v-if="customMermaidImpl"
-  >
-    <slot />
-  </component>
+  <div class="mermaid-outer-wrapper">
+    <div
+      v-if="!isEnabled"
+      class="mermaid-wrapper"
+    >
+      <div ref="mermaidContainer">
+        <slot />
+      </div>
+    </div>
 
-  <div
-    v-else-if="!isEnabled"
-    class="mermaid"
-  >
-    <slot />
-  </div>
+    <component
+      :is="customMermaidImpl"
+      v-else-if="customMermaidImpl"
+      :spinner="spinnerComponent"
+    >
+      <slot />
+    </component>
 
-  <div
-    v-else-if="isMounted"
-    class="mermaid-wrapper"
-  >
     <div
-      ref="mermaidContainer"
-      class="mermaid"
+      v-else
+      class="mermaid-wrapper"
     >
-      <slot />
-    </div>
+      <div ref="mermaidContainer">
+        <!-- Initially show the slot's <pre><code> for SSR; client-side rendering will replace it with the mermaid SVG -->
+        <slot />
+      </div>
 
-    <template v-if="isLoading && !hasRenderedOnce">
-      <slot name="loading">
-        <component :is="spinnerComponent" />
-      </slot>
-    </template>
-  </div>
+      <template v-if="isLoading && !hasRenderedOnce">
+        <slot name="loading">
+          <component :is="spinnerComponent" />
+        </slot>
+      </template>
+      <template v-else-if="hasError">
+        <slot
+          name="error"
+          :error="errorContent"
+          :source="mermaidDefinition"
+        >
+          <component
+            :is="errorComponent"
+            v-if="errorComponent"
+            :error="errorContent"
+            :source="mermaidDefinition"
+          />
 
-  <div
-    v-else
-    class="mermaid"
-  >
-    <slot />
+          <div
+            v-else
+            class="mermaid-error-default"
+          >
+            ⚠️ Mermaid Diagram Error
+          </div>
+        </slot>
+      </template>
+    </div>
   </div>
 </template>
 
 <style scoped>
-.mermaid-wrapper{align-items:center;display:flex;justify-content:center;position:relative}.mermaid:not([data-processed]){color:transparent;min-height:10px}.mermaid{display:flex;justify-content:center}.mermaid .edgeLabel,.mermaid .label,.mermaid .nodeLabel{overflow:visible!important;white-space:normal!important}.mermaid foreignObject{overflow:visible!important}
+.mermaid-wrapper{align-items:center;display:flex;justify-content:center;position:relative}.mermaid-wrapper :deep(code),.mermaid-wrapper :deep(pre){margin:0;max-height:160px;opacity:0;overflow:hidden;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.mermaid-error-default{text-align:center}.mermaid:not([data-processed]){color:transparent;min-height:10px}.mermaid{display:flex;justify-content:center}.mermaid .edgeLabel,.mermaid .label,.mermaid .nodeLabel{overflow:visible!important;white-space:normal!important}.mermaid foreignObject{overflow:visible!important}
 </style>

package/dist/runtime/components/Mermaid.vue.d.ts

@@ -1,14 +1,17 @@
-declare var __VLS_8: {}, __VLS_10: {}, __VLS_12: {}, __VLS_14: {}, __VLS_22: {};
+declare var __VLS_1: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {}, __VLS_21: {
+    error: unknown;
+    source: string;
+};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_8) => any;
+    default?: (props: typeof __VLS_1) => any;
 } & {
-    default?: (props: typeof __VLS_10) => any;
+    default?: (props: typeof __VLS_9) => any;
 } & {
-    default?: (props: typeof __VLS_12) => any;
+    default?: (props: typeof __VLS_11) => any;
 } & {
-    loading?: (props: typeof __VLS_14) => any;
+    loading?: (props: typeof __VLS_13) => any;
 } & {
-    default?: (props: typeof __VLS_22) => any;
+    error?: (props: typeof __VLS_21) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/runtime/plugins/mermaid.client.js

@@ -27,7 +27,7 @@ export default defineNuxtPlugin(() => {
       provide: {
         mermaid: async () => {
           throw new Error(
-            "[nuxt-mermaid-content] Mermaid is disabled via config."
+            "[nuxt-content-mermaid] Mermaid is disabled via config."
           );
         }
       }

package/dist/runtime/utils.d.ts

@@ -0,0 +1 @@
+export declare function enqueueRender(task: () => Promise<void>): Promise<void>;

package/dist/runtime/utils.js

@@ -0,0 +1,7 @@
+let renderQueue = Promise.resolve();
+export function enqueueRender(task) {
+  renderQueue = renderQueue.then(task).catch((e) => {
+    console.error("[nuxt-content-mermaid] Render error:", e);
+  });
+  return renderQueue;
+}

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@barzhsieh/nuxt-content-mermaid",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A Nuxt module designed for integrating Mermaid with `@nuxt/content`. It automatically converts `mermaid` code blocks in Markdown into responsive chart components, and supports lazy loading and dark/light theme switching.",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "content",
+    "nuxt-content",
+    "markdown",
+    "mermaid",
+    "diagram",
+    "mdc"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/andy820621/nuxt-content-mermaid.git"
@@ -31,7 +41,6 @@
     "dev:build": "nuxi build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "release:base": "npm run lint && npm run test && npm run prepack",
-
     "release:patch": "npm run release:base && changelogen --release --patch --push --publish",
     "release:minor": "npm run release:base && changelogen --release --minor --push --publish",
     "release:major": "npm run release:base && changelogen --release --major --push --publish",
@@ -42,30 +51,32 @@
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.2.1",
-    "defu": "^6.1.4"
+    "@nuxt/kit": "catalog:integrations",
+    "defu": "catalog:dev"
   },
   "peerDependencies": {
-    "@nuxt/content": "^3.8.0"
+    "nuxt": "^3.20.1 || ^4.1.0",
+    "@nuxt/content": ">=3.5.0"
   },
   "devDependencies": {
-    "@nuxt/content": "3.8.0",
-    "@nuxt/devtools": "^3.1.0",
-    "@nuxt/eslint-config": "^1.10.0",
-    "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "^4.2.1",
-    "@nuxt/test-utils": "^3.20.1",
-    "@nuxtjs/color-mode": "^4.0.0",
-    "@types/node": "latest",
-    "changelogen": "^0.6.2",
-    "eslint": "^9.39.1",
-    "mermaid": "^11.12.1",
-    "nuxt": "^4.2.1",
-    "typescript": "~5.9.3",
-    "vitest": "^4.0.10",
-    "vue-tsc": "^3.1.4"
+    "@nuxt/content": "catalog:integrations",
+    "@nuxt/devtools": "catalog:dev",
+    "@nuxt/eslint-config": "catalog:dev",
+    "@nuxt/module-builder": "catalog:dev",
+    "@nuxt/schema": "catalog:integrations",
+    "@nuxt/test-utils": "catalog:test",
+    "@nuxtjs/color-mode": "catalog:dev",
+    "@types/node": "catalog:types",
+    "changelogen": "catalog:dev",
+    "eslint": "catalog:dev",
+    "mermaid": "catalog:integrations",
+    "nuxt": "catalog:dev",
+    "typescript": "catalog:dev",
+    "vitest": "catalog:test",
+    "vue-tsc": "catalog:dev"
   },
   "volta": {
     "node": "22.21.1"
-  }
+  },
+  "packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a"
 }