@kpritam/grimoire-output-docusaurus 0.1.8

package/dist/internal/docusaurusConfig.js

@@ -0,0 +1,259 @@
+const genImports = (spellbook) => {
+    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 = () => `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 = () => `const grimoireDevWatchPlugin = () => ({
+  name: "grimoire-dev-watch",
+  configureWebpack() {
+    return {
+      watchOptions: {
+        ignored: [
+          "**/.git/**",
+          "**/node_modules/**",
+          "**/.docusaurus/**",
+          "**/build/**",
+          "**/dist/**",
+          "**/.turbo/**",
+          "**/.next/**",
+          "**/coverage/**",
+        ],
+      },
+    };
+  },
+});
+`;
+const genSidebarHelpers = () => `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 = () => `          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) => mermaid
+    ? `markdown: {
+    mermaid: true,
+    format: "mdx",
+  },
+`
+    : "";
+const themesSection = (mermaid) => mermaid ? `  themes: ["@docusaurus/theme-mermaid"],\n` : "";
+const mermaidPrismTheme = (mermaid) => mermaid
+    ? `,
+    mermaid: { theme: { light: "neutral", dark: "dark" } }`
+    : "";
+const repoNavItem = (repo) => 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) => {
+    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/dist/internal/spellbookAssets.d.ts

@@ -0,0 +1,39 @@
+import { Effect, FileSystem, Path } from "effect";
+/**
+ * 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 declare const writeSpellbookAssets: (fs: FileSystem.FileSystem, pathApi: Path.Path, siteDir: string) => Effect.Effect<readonly string[], import("@kpritam/grimoire-core").OutputWriteError, never>;
+/**
+ * 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 declare const SPELLBOOK_DEPENDENCIES: Readonly<Record<string, string>>;
+/**
+ * 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 declare const SPELLBOOK_DEV_DEPENDENCIES: Readonly<Record<string, string>>;

package/dist/internal/spellbookAssets.js

@@ -0,0 +1,68 @@
+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) => {
+    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, pathApi, siteDir) => 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 = {
+    "@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 = {
+    webpack: "^5.95.0"
+};

package/dist/layer.d.ts

@@ -0,0 +1,3 @@
+import { type ScaffoldEnv, SiteGenerator } from "@kpritam/grimoire-core";
+import { Layer } from "effect";
+export declare const DocusaurusLayer: Layer.Layer<SiteGenerator, never, ScaffoldEnv>;

package/dist/layer.js

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

package/dist/shared.d.ts

@@ -0,0 +1,10 @@
+import type { PackageJsonPatches } from "@kpritam/grimoire-core/services/SiteScaffold";
+export declare const genDocusaurusConfig: (opts: {
+    readonly siteTitle: string;
+    readonly tagline: string;
+    readonly mermaid: boolean;
+    readonly repo?: string | undefined;
+    readonly spellbook?: boolean | undefined;
+}) => string;
+export declare const docusaurusPackagePatches: (mermaid: boolean, spellbook: boolean) => PackageJsonPatches;
+export declare const genSidebarsTs: () => string;

package/dist/shared.js

@@ -0,0 +1,36 @@
+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, spellbook) => ({
+    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 = () => {
+    return `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = {
+  grimoire: [
+    {
+      type: "autogenerated",
+      dirName: ".",
+    },
+  ],
+};
+
+export default sidebars;
+`;
+};

package/dist/upstream.d.ts

@@ -0,0 +1,6 @@
+import { type ScaffoldOptions } from "@kpritam/grimoire-core";
+import { Effect, FileSystem, Path } from "effect";
+/** Spawns `npx create-docusaurus`, applies Grimoire fix-up; skips full scaffold when `site/package.json` exists. */
+export declare const scaffoldUpstream: (opts: ScaffoldOptions) => Effect.Effect<{
+    filesWritten: string[];
+}, import("@kpritam/grimoire-core").OutputWriteError, FileSystem.FileSystem | Path.Path | import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner>;

package/dist/upstream.js

@@ -0,0 +1,84 @@
+import { detectPackageManager, diagramEngineUsesMermaid, outputWriteError, partialScaffoldError } 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) => 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 = [];
+    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 };
+    }
+    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 };
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@kpritam/grimoire-output-docusaurus",
+  "version": "0.1.8",
+  "description": "Grimoire site generator that emits a Docusaurus-compatible site from generated docs.",
+  "license": "MIT",
+  "homepage": "https://github.com/kpritam/grimoire/tree/main/packages/output/docusaurus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kpritam/grimoire.git",
+    "directory": "packages/output/docusaurus"
+  },
+  "bugs": {
+    "url": "https://github.com/kpritam/grimoire/issues"
+  },
+  "keywords": [
+    "grimoire",
+    "output",
+    "docusaurus",
+    "documentation",
+    "static-site"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.51",
+    "@kpritam/grimoire-core": "0.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsdown": "^0.21.10",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "sync-templates": "node scripts/sync-spellbook-templates.mjs",
+    "build": "node scripts/sync-spellbook-templates.mjs && rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly false --incremental false --composite false --sourceMap false",
+    "check": "tsc -p tsconfig.json --noEmit --emitDeclarationOnly false --incremental false --composite false --sourceMap false",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { DocusaurusLayer } from "./layer.js"

package/src/internal/assets.ts

@@ -0,0 +1,66 @@
+import type { OutputWriteError } from "@kpritam/grimoire-core"
+import type { PlaceholderAsset } from "@kpritam/grimoire-core/services/SiteScaffold"
+import { removeFiles } from "@kpritam/grimoire-core/services/SiteScaffold"
+import { Effect, FileSystem, Path } from "effect"
+
+export const PLACEHOLDER_CSS = `/* Replaced by the Grimoire agent during cast/sync with brand-aware styles. */
+:root {
+  color-scheme: light dark;
+}
+`
+
+export const PLACEHOLDER_LOGO_SVG = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" role="img" aria-label="Grimoire">
+  <title>Grimoire</title>
+  <g fill="#4a2f1a">
+    <rect x="11" y="16" width="3.5" height="40"/>
+    <rect x="18" y="12" width="3.5" height="44"/>
+    <rect x="25" y="18" width="3.5" height="38"/>
+    <rect x="32" y="10" width="3.5" height="46"/>
+    <rect x="39" y="14" width="3.5" height="42"/>
+  </g>
+  <circle cx="51" cy="16" r="6" fill="#b9532a"/>
+</svg>
+`
+
+export const PLACEHOLDER_LOGO_SVG_DARK = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" role="img" aria-label="Grimoire">
+  <title>Grimoire</title>
+  <g fill="#e8d6b8">
+    <rect x="11" y="16" width="3.5" height="40"/>
+    <rect x="18" y="12" width="3.5" height="44"/>
+    <rect x="25" y="18" width="3.5" height="38"/>
+    <rect x="32" y="10" width="3.5" height="46"/>
+    <rect x="39" y="14" width="3.5" height="42"/>
+  </g>
+  <circle cx="51" cy="16" r="6" fill="#e1a06b"/>
+</svg>
+`
+
+export const DOCUSAURUS_PLACEHOLDER_ASSETS: ReadonlyArray<PlaceholderAsset> = [
+  { relPath: "src/css/custom.css", content: PLACEHOLDER_CSS },
+  { relPath: "static/img/logo.svg", content: PLACEHOLDER_LOGO_SVG },
+  { relPath: "static/img/logo-dark.svg", content: PLACEHOLDER_LOGO_SVG_DARK }
+]
+
+export const DOCUSAURUS_SAMPLE_RELPATHS: ReadonlyArray<string> = [
+  "blog",
+  "docs",
+  "src/pages/index.tsx",
+  "src/pages/index.jsx",
+  "src/pages/index.js",
+  "src/pages/markdown-page.md",
+  "src/pages/markdown-page.mdx",
+  "src/pages/index.module.css",
+  "src/components"
+]
+
+export const removeDocusaurusSamples = (
+  fs: FileSystem.FileSystem,
+  pathApi: Path.Path,
+  siteDir: string
+): Effect.Effect<ReadonlyArray<string>, OutputWriteError> =>
+  removeFiles(siteDir, DOCUSAURUS_SAMPLE_RELPATHS).pipe(
+    Effect.provideService(FileSystem.FileSystem, fs),
+    Effect.provideService(Path.Path, pathApi)
+  )