@kpritam/grimoire-output-docusaurus 0.1.8

package/src/internal/docusaurusConfig.ts

@@ -0,0 +1,281 @@
+const genImports = (spellbook: boolean): string => {
+  const spellbookImport = spellbook
+    ? `import { spellbookWebpackPlugin } from "./spellbookPlugin";\n`
+    : ""
+  return `import type { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+import { themes as prismThemes } from "prism-react-renderer";
+${spellbookImport}`
+}
+
+const genWatcherEnv = (): string => `if (!Object.hasOwn(process.env, "WATCHPACK_POLLING")) {
+  process.env.WATCHPACK_POLLING = "true";
+}
+if (!Object.hasOwn(process.env, "CHOKIDAR_USEPOLLING")) {
+  process.env.CHOKIDAR_USEPOLLING = "true";
+}
+`
+
+const genDevWatchPlugin = (): string => `const grimoireDevWatchPlugin = () => ({
+  name: "grimoire-dev-watch",
+  configureWebpack() {
+    return {
+      watchOptions: {
+        ignored: [
+          "**/.git/**",
+          "**/node_modules/**",
+          "**/.docusaurus/**",
+          "**/build/**",
+          "**/dist/**",
+          "**/.turbo/**",
+          "**/.next/**",
+          "**/coverage/**",
+        ],
+      },
+    };
+  },
+});
+`
+
+const genSidebarHelpers = (): string => `const SIDEBAR_ACRONYMS = new Set([
+  "cli", "ci", "cd", "ai", "api", "sdk", "url", "uri", "http", "https",
+  "json", "yaml", "md", "mdx", "sha", "dsl", "ide", "ui", "ux", "io",
+  "pr", "mr", "os", "sql", "tls", "ssh", "cors", "dns", "tcp", "udp", "jwt",
+]);
+const humanizeSidebarLabel = (slug: string): string =>
+  slug
+    .split(/[-_\\s]+/)
+    .map((w, i) => {
+      if (!w) return w;
+      if (SIDEBAR_ACRONYMS.has(w.toLowerCase())) return w.toUpperCase();
+      if (/^v\\d/.test(w)) return w.toLowerCase();
+      return i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w;
+    })
+    .join(" ");
+
+const SIDEBAR_WEIGHTS: Record<string, number> = {
+  "index": -1000,
+  "introduction": -900,
+  "intro": -900,
+  "getting-started": -800,
+  "quickstart": -780,
+  "quick-start": -780,
+  "installation": -760,
+  "install": -760,
+  "tutorial": -700,
+  "overview": -680,
+  "concepts": -400,
+  "guides": -300,
+  "how-to": -280,
+  "recipes": -260,
+  "reference": 200,
+  "api": 220,
+  "cli": 220,
+  "configuration": 230,
+  "config": 230,
+  "architecture": 600,
+  "internals": 700,
+  "development": 780,
+  "contributing": 800,
+  "roadmap": 880,
+  "changelog": 900,
+  "faq": 920,
+  "troubleshooting": 940,
+};
+const sidebarWeight = (slug: string): number =>
+  SIDEBAR_WEIGHTS[slug.toLowerCase()] ?? 0;
+`
+
+const genSidebarItemsGenerator = (): string => `          sidebarItemsGenerator: async ({
+            defaultSidebarItemsGenerator,
+            ...args
+          }) => {
+            const items = await defaultSidebarItemsGenerator(args);
+            const hiddenAnywhere = new Set(["README"]);
+            const hiddenAtRoot = new Set(["index"]);
+            const slugTail = (id: string): string => {
+              const segs = id.split("/");
+              return segs[segs.length - 1] ?? id;
+            };
+            const looksRawSlug = (s: string): boolean =>
+              /^[a-z0-9]+([-_][a-z0-9]+)*$/.test(s);
+            type Item = (typeof items)[number];
+            const itemKey = (item: Item): string => {
+              if (item.type === "doc") return slugTail(item.id).toLowerCase();
+              if (item.type === "category") return item.label.toLowerCase();
+              return "";
+            };
+            const sortTopLevel = (list: Item[]): Item[] =>
+              [...list].sort((a, b) => {
+                const ka = itemKey(a);
+                const kb = itemKey(b);
+                const wa = sidebarWeight(ka);
+                const wb = sidebarWeight(kb);
+                if (wa !== wb) return wa - wb;
+                return ka.localeCompare(kb);
+              });
+            const walk = (item: Item, depth: number): Item | null => {
+              if (item.type === "doc") {
+                const tail = slugTail(item.id);
+                if (hiddenAnywhere.has(tail)) return null;
+                if (depth === 0 && hiddenAtRoot.has(tail)) return null;
+                if (!item.label && looksRawSlug(tail)) {
+                  return { ...item, label: humanizeSidebarLabel(tail) };
+                }
+                return item;
+              }
+              if (item.type === "category") {
+                const label = looksRawSlug(item.label)
+                  ? humanizeSidebarLabel(item.label)
+                  : item.label;
+                const children = item.items
+                  .map((c: Item) => walk(c, depth + 1))
+                  .filter((x: Item | null): x is Item => x !== null);
+                return {
+                  ...item,
+                  label,
+                  collapsed: depth === 0 ? false : item.collapsed,
+                  items: children,
+                };
+              }
+              return item;
+            };
+            return sortTopLevel(
+              items
+                .map((c: Item) => walk(c, 0))
+                .filter((x: Item | null): x is Item => x !== null),
+            );
+          },
+`
+
+const markdownBlock = (mermaid: boolean): string =>
+  mermaid
+    ? `markdown: {
+    mermaid: true,
+    format: "mdx",
+  },
+`
+    : ""
+
+const themesSection = (mermaid: boolean): string =>
+  mermaid ? `  themes: ["@docusaurus/theme-mermaid"],\n` : ""
+
+const mermaidPrismTheme = (mermaid: boolean): string =>
+  mermaid
+    ? `,
+    mermaid: { theme: { light: "neutral", dark: "dark" } }`
+    : ""
+
+const repoNavItem = (repo: string | undefined): string =>
+  repo !== undefined && repo !== ""
+    ? `        {
+          href: ${JSON.stringify(repo)},
+          position: "right",
+          className: "navbar__item navbar__item--github",
+          "aria-label": "View source on GitHub",
+          title: "GitHub",
+          label: "GitHub",
+        },
+`
+    : ""
+
+export const genDocusaurusConfig = (opts: {
+  readonly siteTitle: string
+  readonly tagline: string
+  readonly mermaid: boolean
+  readonly repo?: string | undefined
+  /** When true, emit the SpellbookChat webpack plugin (`__SPELLBOOK_ENABLED__`,
+   * SSR aliases for `@huggingface/transformers` / `@mlc-ai/web-llm`, asset rules). */
+  readonly spellbook?: boolean | undefined
+}): string => {
+  const mb = markdownBlock(opts.mermaid)
+  const ts = themesSection(opts.mermaid)
+  const mpt = mermaidPrismTheme(opts.mermaid)
+  const rni = repoNavItem(opts.repo)
+  const spellbookOn = opts.spellbook === true
+  const pluginsList = spellbookOn
+    ? "[grimoireDevWatchPlugin, spellbookWebpackPlugin]"
+    : "[grimoireDevWatchPlugin]"
+
+  return `${genImports(spellbookOn)}
+// macOS EMFILE workaround when \`docs.path\` walks the whole tome: force
+// Webpack/Watchpack and chokidar onto polling. Opt out with
+// WATCHPACK_POLLING=false / CHOKIDAR_USEPOLLING=false.
+${genWatcherEnv()}
+${genDevWatchPlugin()}
+// Sidebar polish: humanize raw slugs into Sentence-case, upper-case known
+// technical acronyms, and weight common top-level slugs (getting-started
+// first, architecture / internals last). Agent-authored \`sidebar_label\` /
+// \`sidebar_position\` always wins over these fallbacks.
+${genSidebarHelpers()}
+const config: Config = {
+  title: ${JSON.stringify(opts.siteTitle)},
+  tagline: ${JSON.stringify(opts.tagline)},
+  favicon: "img/logo.svg",
+  url: "https://example.com",
+  baseUrl: "/",
+  organizationName: "grimoire",
+  projectName: "docs",
+  onBrokenLinks: "warn",
+  ${mb}  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          path: "../",
+          exclude: [
+            "site/**",
+            "**/node_modules/**",
+            "**/.git/**",
+            ".grimoire/**",
+            "**/.grimoire/**",
+            ".grimoire-seal",
+            "**/.grimoire-seal",
+            ".grimoire-progress.json",
+            "**/.grimoire-progress.json",
+            // README.md and index.md (slug: /) would both claim "/" — keep the
+            // landing page and exclude README globally.
+            "**/README.md",
+          ],
+          routeBasePath: "/",
+          sidebarPath: "./sidebars.ts",
+          editLocalizedFiles: false,
+          editUrl: undefined,
+${genSidebarItemsGenerator()}        },
+        blog: false,
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+  plugins: ${pluginsList},
+${ts}  themeConfig: {
+    colorMode: {
+      defaultMode: "light",
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: ${JSON.stringify(opts.siteTitle)},
+      logo: {
+        alt: ${JSON.stringify(opts.siteTitle)},
+        src: "img/logo.svg",
+        srcDark: "img/logo-dark.svg",
+      },
+      items: [
+${rni}      ],
+    },
+    footer: {
+      style: "dark",
+      copyright: \`© \${new Date().getFullYear()} \${${JSON.stringify(opts.siteTitle)}}\`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    }${mpt},
+  },
+};
+
+export default config;
+`
+}

package/src/internal/spellbookAssets.ts

@@ -0,0 +1,80 @@
+import { fileURLToPath } from "node:url"
+import { siteScaffoldPhases } from "@kpritam/grimoire-core/services/SiteScaffold"
+import { Effect, FileSystem, Path } from "effect"
+
+// Loaded from `dist/internal/spellbookAssets.js`; `templates/spellbook` lives
+// two levels up alongside the published `dist/` and `src/` folders.
+const spellbookTemplatesRoot = (pathApi: Path.Path): string => {
+  const here = fileURLToPath(new URL(".", import.meta.url))
+  return pathApi.resolve(here, "..", "..", "templates", "spellbook")
+}
+
+/**
+ * Copy the SpellbookChat React tree, the `theme/Root.tsx` swizzle, the
+ * `SpellbookChatDisabled.tsx` stub, AND the root-level `spellbookPlugin.ts`
+ * into the scaffolded site. The template layout mirrors the site layout 1:1
+ * so this is a single recursive copy.
+ *
+ * Files are **overwritten** on every run. This is safe because the entire
+ * copied tree is package-managed: it's regenerated from
+ * `tome/site/src/components/SpellbookChat/` on every release of
+ * `@kpritam/grimoire-output-docusaurus` via `sync-spellbook-templates.mjs`.
+ * Customisation should happen in user-owned files (e.g. theme overrides),
+ * not by editing these in place.
+ */
+export const writeSpellbookAssets = (
+  fs: FileSystem.FileSystem,
+  pathApi: Path.Path,
+  siteDir: string
+) =>
+  siteScaffoldPhases
+    .writeManagedAssets({
+      templatesRoot: spellbookTemplatesRoot(pathApi),
+      siteDir
+    })
+    .pipe(
+      Effect.provideService(FileSystem.FileSystem, fs),
+      Effect.provideService(Path.Path, pathApi)
+    )
+
+/**
+ * npm dependencies the SpellbookChat components require at runtime.
+ * Keep in sync with `tome/site/package.json` so the canonical site and
+ * scaffolded sites resolve identical versions.
+ *
+ * Notable additions over the v0.1.6 baseline:
+ *   - `streamdown` replaces `react-markdown` for streaming-aware rendering
+ *   - `@ricky0123/vad-web` + `onnxruntime-web` power Silero VAD for voice
+ *     mode (Web Audio + ONNX in-browser)
+ */
+export const SPELLBOOK_DEPENDENCIES: Readonly<Record<string, string>> = {
+  "@ai-sdk/anthropic": "^3.0.77",
+  "@ai-sdk/google": "^3.0.73",
+  "@ai-sdk/openai": "^3.0.63",
+  "@ai-sdk/openai-compatible": "^2.0.47",
+  "@huggingface/transformers": "^4.2.0",
+  "@mlc-ai/web-llm": "^0.2.83",
+  "@ricky0123/vad-web": "^0.0.30",
+  ai: "^6.0.180",
+  "highlight.js": "^11.11.1",
+  "onnxruntime-web": "^1.26.0",
+  "rehype-highlight": "^7.0.2",
+  "remark-gfm": "^4.0.1",
+  streamdown: "^2.5.0"
+}
+
+/**
+ * Build-time dependencies the Spellbook plugin imports directly.
+ *
+ * `spellbookPlugin.ts` calls `new webpack.NormalModuleReplacementPlugin(...)`
+ * to swap the chat tree for the disabled stub, so `webpack` must be
+ * resolvable both at type-check time (`tsc --noEmit`) and when Docusaurus
+ * loads the plugin. Strict pnpm node_modules layouts only expose packages
+ * that are direct dependencies, so we must declare it here even though
+ * `@docusaurus/core` already pulls it in transitively.
+ *
+ * Pinned to `^5.95.0` to match `@docusaurus/core@3.10.x`'s declared range.
+ */
+export const SPELLBOOK_DEV_DEPENDENCIES: Readonly<Record<string, string>> = {
+  webpack: "^5.95.0"
+}

package/src/layer.ts

@@ -0,0 +1,12 @@
+import { type ScaffoldEnv, SiteGenerator } from "@kpritam/grimoire-core"
+import { Effect, Layer } from "effect"
+
+import { scaffoldUpstream } from "./upstream.js"
+
+export const DocusaurusLayer: Layer.Layer<SiteGenerator, never, ScaffoldEnv> = Layer.succeed(
+  SiteGenerator,
+  {
+    scaffold: (opts) =>
+      scaffoldUpstream(opts).pipe(Effect.withSpan("grimoire.site.docusaurus.upstream"))
+  }
+)

package/src/shared.ts

@@ -0,0 +1,43 @@
+import type { PackageJsonPatches } from "@kpritam/grimoire-core/services/SiteScaffold"
+import { genDocusaurusConfig as genDocusaurusConfigInner } from "./internal/docusaurusConfig.js"
+import { SPELLBOOK_DEPENDENCIES, SPELLBOOK_DEV_DEPENDENCIES } from "./internal/spellbookAssets.js"
+
+export const genDocusaurusConfig = genDocusaurusConfigInner
+
+export const docusaurusPackagePatches = (
+  mermaid: boolean,
+  spellbook: boolean
+): PackageJsonPatches => ({
+  private: true,
+  scripts: {
+    start: "CHOKIDAR_USEPOLLING=true WATCHPACK_POLLING=true docusaurus start",
+    serve: "CHOKIDAR_USEPOLLING=true WATCHPACK_POLLING=true docusaurus serve",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    ...(mermaid
+      ? {
+          "@docusaurus/theme-mermaid": "^3.10.0",
+          "@mermaid-js/layout-elk": "^0.1.9"
+        }
+      : {}),
+    ...(spellbook ? SPELLBOOK_DEPENDENCIES : {})
+  },
+  devDependencies: spellbook ? SPELLBOOK_DEV_DEPENDENCIES : {}
+})
+
+export const genSidebarsTs = (): string => {
+  return `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = {
+  grimoire: [
+    {
+      type: "autogenerated",
+      dirName: ".",
+    },
+  ],
+};
+
+export default sidebars;
+`
+}

package/src/upstream.ts

@@ -0,0 +1,119 @@
+import {
+  detectPackageManager,
+  diagramEngineUsesMermaid,
+  outputWriteError,
+  partialScaffoldError,
+  type ScaffoldOptions,
+  type ScaffoldResult
+} from "@kpritam/grimoire-core"
+import { removeFiles, siteScaffoldPhases } from "@kpritam/grimoire-core/services/SiteScaffold"
+import { Effect, FileSystem, Path } from "effect"
+import { DOCUSAURUS_PLACEHOLDER_ASSETS, DOCUSAURUS_SAMPLE_RELPATHS } from "./internal/assets.js"
+import { writeSpellbookAssets } from "./internal/spellbookAssets.js"
+import { docusaurusPackagePatches, genDocusaurusConfig, genSidebarsTs } from "./shared.js"
+
+/** Spawns `npx create-docusaurus`, applies Grimoire fix-up; skips full scaffold when `site/package.json` exists. */
+export const scaffoldUpstream = (opts: ScaffoldOptions) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const pathApi = yield* Path.Path
+    const siteTitle = opts.siteTitle ?? "Grimoire"
+    const tagline = opts.tagline ?? "Documentation generated by Grimoire"
+    const mermaidOn = diagramEngineUsesMermaid(opts.diagramEngine)
+    const spellbookOn = opts.spellbook === true
+    const logStream = opts.logStream === true
+    yield* fs
+      .makeDirectory(opts.tomeDir, { recursive: true })
+      .pipe(Effect.mapError((e) => outputWriteError(opts.tomeDir, e)))
+
+    const written: string[] = []
+    const pkgPath = pathApi.join(opts.siteDir, "package.json")
+
+    if (yield* siteScaffoldPhases.existing(opts.siteDir, pkgPath)) {
+      for (const p of yield* siteScaffoldPhases.writePlaceholderAssets(
+        opts.siteDir,
+        DOCUSAURUS_PLACEHOLDER_ASSETS
+      )) {
+        written.push(p)
+      }
+      if (spellbookOn) {
+        yield* siteScaffoldPhases.patchPackageJson(
+          pkgPath,
+          docusaurusPackagePatches(mermaidOn, spellbookOn)
+        )
+        written.push(pkgPath)
+        for (const p of yield* writeSpellbookAssets(fs, pathApi, opts.siteDir)) {
+          written.push(p)
+        }
+      }
+      return { filesWritten: written } satisfies ScaffoldResult
+    }
+
+    const siteDirExists = yield* fs.exists(opts.siteDir).pipe(Effect.orElseSucceed(() => false))
+    if (siteDirExists) {
+      return yield* Effect.fail(partialScaffoldError({ siteDir: opts.siteDir, pkgPath }))
+    }
+
+    const pm = yield* detectPackageManager(fs, pathApi, opts.root)
+    yield* siteScaffoldPhases.spawnUpstream({
+      binary: "npx",
+      args: [
+        "--yes",
+        "create-docusaurus@^3.10",
+        pathApi.basename(opts.siteDir),
+        "classic",
+        "--typescript",
+        "--skip-install",
+        "--package-manager",
+        pm
+      ],
+      cwd: opts.tomeDir,
+      label: "docusaurus",
+      logStream
+    })
+
+    for (const p of yield* removeFiles(opts.siteDir, DOCUSAURUS_SAMPLE_RELPATHS)) {
+      written.push(`-${p}`)
+    }
+
+    yield* siteScaffoldPhases.patchPackageJson(
+      pkgPath,
+      docusaurusPackagePatches(mermaidOn, spellbookOn)
+    )
+    written.push(pkgPath)
+
+    const docusaurusConfigPath = pathApi.join(opts.siteDir, "docusaurus.config.ts")
+    yield* siteScaffoldPhases.writeFrameworkConfig(
+      docusaurusConfigPath,
+      genDocusaurusConfig({
+        siteTitle,
+        tagline,
+        mermaid: mermaidOn,
+        spellbook: spellbookOn,
+        ...(opts.siteRepo !== undefined ? { repo: opts.siteRepo } : {})
+      })
+    )
+    written.push(docusaurusConfigPath)
+
+    for (const p of yield* removeFiles(opts.siteDir, ["docusaurus.config.js", "sidebars.js"])) {
+      written.push(`-${p}`)
+    }
+
+    const sidebarsPath = pathApi.join(opts.siteDir, "sidebars.ts")
+    yield* siteScaffoldPhases.writeFrameworkConfig(sidebarsPath, genSidebarsTs())
+    written.push(sidebarsPath)
+
+    for (const p of yield* siteScaffoldPhases.writePlaceholderAssets(
+      opts.siteDir,
+      DOCUSAURUS_PLACEHOLDER_ASSETS
+    )) {
+      written.push(p)
+    }
+    if (spellbookOn) {
+      for (const p of yield* writeSpellbookAssets(fs, pathApi, opts.siteDir)) {
+        written.push(p)
+      }
+    }
+
+    return { filesWritten: written } satisfies ScaffoldResult
+  })

package/templates/spellbook/spellbookPlugin.ts

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import webpack from "webpack";
+
+/**
+ * In-browser RAG chat ("Spellbook") master switch + Docusaurus plugin.
+ *
+ * This file is the single source of truth: the live Grimoire docs site
+ * imports it directly, and `@kpritam/grimoire-output-docusaurus` ships a
+ * mirror to scaffolded sites (see `templates/spellbook/spellbookPlugin.ts`
+ * and `sync-spellbook-templates.mjs`). Edit here, then re-run the sync.
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolution order:
+//   1. SPELLBOOK_ENABLED=true|false env var (explicit override)
+//   2. Presence of static/grimoire-index/manifest.json (last `grimoire cast`)
+//   3. Default: false
+const SPELLBOOK_INDEX_MANIFEST = path.join(
+  __dirname,
+  "static/grimoire-index/manifest.json",
+);
+
+export const resolveSpellbookEnabled = (): boolean => {
+  const envFlag = process.env.SPELLBOOK_ENABLED;
+  if (envFlag === "false" || envFlag === "0") return false;
+  if (envFlag === "true" || envFlag === "1") return true;
+  return fs.existsSync(SPELLBOOK_INDEX_MANIFEST);
+};
+
+export const SPELLBOOK_ENABLED = resolveSpellbookEnabled();
+
+const SPELLBOOK_DISABLED_STUB = path.join(
+  __dirname,
+  "src/components/SpellbookChatDisabled.tsx",
+);
+
+interface MutableWebpackConfig {
+  resolve?: { alias?: Record<string, string> | unknown };
+  module?: { rules?: unknown[] };
+}
+
+/**
+ * Webpack warnings we deliberately silence:
+ *
+ * - `onnxruntime-web` ships a UMD bundle whose dynamic `require()` only
+ *   fires in non-web targets (Node fallbacks). Webpack can't statically
+ *   resolve it, but it's effectively dead code in our browser build, so
+ *   the "Critical dependency: require function is used in a way…" noise
+ *   is purely cosmetic.
+ *
+ * - `@huggingface/transformers`'s web entry uses `import.meta` at the top
+ *   level. Webpack 5 supports it but emits a "Critical dependency:
+ *   Accessing import.meta directly is unsupported" warning because the
+ *   runtime feature-detects gracefully. Library issue we can't fix here.
+ *
+ * Keeping this list narrow (matched by `module` and `message`) so future
+ * real warnings still surface.
+ */
+const SPELLBOOK_IGNORED_WARNINGS = [
+  {
+    module: /node_modules[\\/].*onnxruntime-web/,
+    message: /Critical dependency: require function is used in a way/,
+  },
+  {
+    module:
+      /node_modules[\\/].*@huggingface[\\/]transformers[\\/].*transformers\.web/,
+    message:
+      /Critical dependency: Accessing import\.meta directly is unsupported/,
+  },
+];
+
+/**
+ * Replaces every entrypoint into the SpellbookChat tree with an inert
+ * stub when disabled (webpack still creates a chunk for `import()` even
+ * when the branch is dead at runtime), and wires SSR stubs + binary
+ * asset rules when enabled.
+ *
+ * Earlier revisions also defined a build-time `__SPELLBOOK_ENABLED__`
+ * constant via `webpack.DefinePlugin`. That triggered a webpack
+ * persistent-cache serialization warning ("No serializer registered for
+ * ConstDependency") on every consumer of the constant. Since
+ * `NormalModuleReplacementPlugin` already collapses the SpellbookChat
+ * graph to the inert stub when disabled — and tree-shaking handles the
+ * empty default export — the DefinePlugin layer was redundant. Removing
+ * it eliminates the cache warning without changing bundle output.
+ */
+export const spellbookWebpackPlugin = () => ({
+  name: "spellbook-webpack",
+  configureWebpack(config: MutableWebpackConfig, isServer: boolean) {
+    if (!SPELLBOOK_ENABLED) {
+      const replacePlugin = new webpack.NormalModuleReplacementPlugin(
+        /(?:^|[\\/])components[\\/]SpellbookChat(?:[\\/](?:index)?)?$/,
+        SPELLBOOK_DISABLED_STUB,
+      );
+      return { plugins: [replacePlugin] };
+    }
+
+    const transformersStub = path.join(
+      __dirname,
+      "src/components/SpellbookChat/transformers-ssr-stub.ts",
+    );
+    const webllmStub = path.join(
+      __dirname,
+      "src/components/SpellbookChat/webllm-ssr-stub.ts",
+    );
+    const vadStub = path.join(
+      __dirname,
+      "src/components/SpellbookChat/vad-ssr-stub.ts",
+    );
+    const binaryRule = {
+      test: /\.(wasm|onnx|bin|node)$/i,
+      type: "asset/resource" as const,
+    };
+
+    if (isServer) {
+      config.resolve ??= {};
+      const prev = config.resolve.alias;
+      const alias: Record<string, string> =
+        prev && typeof prev === "object" && !Array.isArray(prev)
+          ? { ...(prev as Record<string, string>) }
+          : {};
+      alias["@huggingface/transformers"] = transformersStub;
+      alias["@mlc-ai/web-llm"] = webllmStub;
+      // `@ricky0123/vad-web` and `onnxruntime-web` are not safe to evaluate
+      // during Docusaurus SSR — they reference `AudioWorklet` and resolve
+      // .wasm assets. Stub the VAD entrypoint and let the binary rule
+      // handle the ORT wasm files when bundled for the browser.
+      alias["@ricky0123/vad-web"] = vadStub;
+      config.resolve.alias = alias;
+      config.module ??= { rules: [] };
+      config.module.rules ??= [];
+      config.module.rules.push(binaryRule);
+      return { ignoreWarnings: SPELLBOOK_IGNORED_WARNINGS };
+    }
+
+    return {
+      experiments: {
+        asyncWebAssembly: true,
+      },
+      resolve: {
+        fallback: {
+          fs: false as const,
+          path: false as const,
+          crypto: false as const,
+        },
+      },
+      module: {
+        rules: [binaryRule],
+      },
+      ignoreWarnings: SPELLBOOK_IGNORED_WARNINGS,
+    };
+  },
+});