diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 7d315ea..acb7268 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -160,5 +160,20 @@ export default withMermaid(
     mermaid: {
       securityLevel: 'strict',
     },
+
+    // Mermaid 11 ships its `dayjs` / `cytoscape` dependencies with a
+    // CommonJS `main` field but no `default` ESM export. Vite's dev
+    // server resolves those modules eagerly as ESM and the browser
+    // throws `does not provide an export named 'default'` on the
+    // first navigation. Telling `optimizeDeps` to pre-bundle the
+    // Mermaid dependency tree forces the CJS→ESM interop wrapper
+    // that Vite's Rollup-based build already applies in prod. The
+    // production build (`docs:build`) was unaffected even before
+    // this; this fix is exclusively for the `docs:dev` happy path.
+    vite: {
+      optimizeDeps: {
+        include: ['mermaid', 'dayjs', 'debug', '@braintree/sanitize-url'],
+      },
+    },
   }),
 );