@docubook/flame 1.7.1 → 2.0.0-alpha.0

package/.docu/node/build.ts

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 import React from "react";
 import { renderToString } from "react-dom/server";
-import { compileMdx, getGitLastModifiedBatch } from "./mdx";
+import { compileMdx, compileMdxModule, frontmatterField, getGitLastModifiedBatch } from "./mdx";
 import {
   DOCS_DIR,
   DIST_DIR,
@@ -113,8 +113,8 @@ async function renderDocsPage(
     });
   }
 
-  const title = (typeof frontmatter.title === "string" ? frontmatter.title : "") || slug || "Docs";
-  const description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+  const title = frontmatterField(frontmatter, "title") || slug || "Docs";
+  const description = frontmatterField(frontmatter, "description");
   const slugParts = slug ? slug.split("/") : [];
 
   const page = React.createElement(
@@ -124,12 +124,15 @@ async function renderDocsPage(
       slug: slugParts,
       title,
       description,
-      date: (frontmatter.date as string) || undefined,
-      content: result.content,
+      date: frontmatterField(frontmatter, "date") || undefined,
+      // Render MDX content as its own root: client hydrates the island as a
+      // separate root, so SSR must be root-relative too or useId-based ids
+      // (mdx-compiler components) mismatch during hydration.
+      content: renderToString(result.content),
       tocs: result.tocs,
       filePath,
       repoUrl: docuConfig.repo?.url,
-      compiledSource: result.compiledSource,
+      mdxSlug: slug,
     })
   );
 
@@ -203,9 +206,66 @@ async function build() {
   let built = 0;
   let skipped = 0;
 
+  const pluginsConfig = docuConfig.plugins ?? [];
+  const builder = pluginsConfig.length > 0 ? new BuildPluginBuilder(docuConfig) : null;
+  if (builder) {
+    const plugins = await loadPlugins(pluginsConfig);
+    for (const plugin of plugins) {
+      await plugin.setup(builder);
+    }
+    await builder.runOnStart();
+  }
+
+  // Pre-compile every page's MDX to an ESM module (program format) so the
+  // client bundle can hydrate the content island statically — no new Function.
+  // Mirrors the page loop's transform + plugin chain so SSR and client trees
+  // match. Runs for all files regardless of cache; the bundle is shared by
+  // every page, so a content change invalidates the page cache anyway.
+  const mdxSources: Record<string, string> = {};
+  const prePassTasks = mdxFiles.map(async (file) => {
+    let raw: string;
+    try {
+      raw = await readFile(file.absPath, "utf-8");
+    } catch {
+      return;
+    }
+    let content = raw;
+    if (builder) {
+      const relPath = file.absPath.replace(PROJECT_ROOT + "/", "");
+      const transformed = await builder.runOnLoad(relPath, content);
+      if (transformed?.contents) content = transformed.contents;
+    }
+    const remarkPlugins = builder?.collectRemarkPlugins();
+    const rehypePlugins = builder?.collectRehypePlugins();
+    mdxSources[file.path] = await compileMdxModule(content, remarkPlugins, rehypePlugins);
+  });
+  await Promise.all(prePassTasks);
+
+  // The docs root (index.mdx) renders with slug "" — mirror that key so the
+  // index page hydrates too. Its render has its own try/catch; skip on error.
+  const indexMdxPath = join(DOCS_DIR, "index.mdx");
+  if (existsSync(indexMdxPath)) {
+    try {
+      const indexRaw = await readFile(indexMdxPath, "utf-8");
+      let indexContent = indexRaw;
+      if (builder) {
+        const relPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
+        const transformed = await builder.runOnLoad(relPath, indexContent);
+        if (transformed?.contents) indexContent = transformed.contents;
+      }
+      mdxSources[""] = await compileMdxModule(
+        indexContent,
+        builder?.collectRemarkPlugins(),
+        builder?.collectRehypePlugins()
+      );
+    } catch {
+      // ignore — the index render reports its own error
+    }
+  }
+
   logger.bundleStart();
   let t = performance.now();
-  assetManifest = await buildClientBundle();
+  assetManifest = await buildClientBundle(mdxSources);
   logger.bundleDone(Math.round(performance.now() - t));
 
   inlineThemeCss = computeInlineThemeCss();
@@ -221,16 +281,6 @@ async function build() {
     };
   }
 
-  const pluginsConfig = docuConfig.plugins ?? [];
-  const builder = pluginsConfig.length > 0 ? new BuildPluginBuilder(docuConfig) : null;
-  if (builder) {
-    const plugins = await loadPlugins(pluginsConfig);
-    for (const plugin of plugins) {
-      await plugin.setup(builder);
-    }
-    await builder.runOnStart();
-  }
-
   logger.spinner.start("Building pages...");
   t = performance.now();
 

package/.docu/node/client.ts

@@ -1,22 +1,37 @@
 import { createRoot, hydrateRoot } from "react-dom/client";
 import React from "react";
+import { MDXProvider } from "@mdx-js/react";
 import { MDXRemote } from "@docubook/core";
-import { createMdxComponents } from "@docubook/mdx-content";
+import { createMdxComponents } from "@docubook/markdown";
+import { mdxModules } from "./mdx-manifest";
 import Sidebar, { MobileBar } from "../components/Sidebar";
 import Toc from "../components/Toc";
 import { ThemeToggle } from "../components/Theme";
 import { safeParseTocs } from "./parse-tocs";
 import type { TocItem } from "./types";
 
+/**
+ * Island mount mode — deliberate trade-off per island API:
+ *
+ * - `hydrate`: SSR HTML exists and the client renders the identical tree →
+ *   attach React in place (no flash, SSR content preserved).
+ * - `create`: client-only render — the client tree deliberately differs from
+ *   SSR (or SSR output is absent) → full render, discards SSR markup.
+ * - `auto`: hydrate when the SSR container has children, else create.
+ */
+type MountMode = "auto" | "hydrate" | "create";
+
 function mountIsland(
   id: string,
-  render: (el: HTMLElement) => React.ReactElement,
-  forceCreate = false
+  render: (el: HTMLElement) => React.ReactElement | null,
+  mode: MountMode = "auto"
 ) {
   const el = document.getElementById(id);
   if (!el) return;
   const node = render(el);
-  if (!forceCreate && el.childElementCount > 0) {
+  if (node === null) return; // island stays as-is (SSR HTML preserved)
+  const hydrate = mode === "hydrate" || (mode === "auto" && el.childElementCount > 0);
+  if (hydrate) {
     hydrateRoot(el, node);
   } else {
     el.innerHTML = "";
@@ -25,8 +40,9 @@ function mountIsland(
 }
 
 function mountIslands() {
-  // forceCreate: SSR sidebar renders <Menu> only; client renders full <Sidebar>
-  // (DesktopSidebar + MobileBar) — structure mismatch forces full createRoot.
+  // SSR renders <Menu> only; client renders full <Sidebar> (DesktopSidebar +
+  // MobileBar) — structural mismatch makes hydration impossible, so always
+  // createRoot and discard the SSR <Menu> markup.
   mountIsland(
     "sidebar-island",
     (el) => {
@@ -37,11 +53,11 @@ function mountIslands() {
         repoUrl: el.dataset.repo || "",
       });
     },
-    true
+    "create"
   );
 
-  // mobile-bar-island SSR div is empty (data attributes only),
-  // so hydrateRoot child check falls through to createRoot automatically.
+  // SSR div is empty (data attributes only) — childElementCount is 0, so
+  // auto falls through to createRoot.
   mountIsland("mobile-bar-island", (el) => {
     const tocs: TocItem[] = safeParseTocs(el.dataset.tocs);
     return React.createElement(MobileBar, {
@@ -58,24 +74,45 @@ function mountIslands() {
 
   mountIsland("theme-island", () => React.createElement(ThemeToggle));
 
-  hydrateMdxContent();
-}
-
-function hydrateMdxContent() {
-  const island = document.getElementById("mdx-content-island");
-  const sourceEl = document.getElementById("mdx-compiled-source");
-  if (!island || !sourceEl) return;
-
-  try {
-    const compiledSource = JSON.parse(sourceEl.textContent || "");
-    const components = createMdxComponents();
-    hydrateRoot(
-      island,
-      React.createElement(MDXRemote, { compiledSource, scope: {}, frontmatter: {}, components })
-    );
-  } catch (e) {
-    console.error("[mdx-hydrate]", e);
-  }
+  // MDX content: SSR renders the full content HTML; the client rebuilds the
+  // identical tree. Two sources, same tree shape:
+  //  - static build: per-slug compiled ESM module bundled via ./mdx-manifest
+  //    (no new Function) — module and SSR output come from the same plugin
+  //    chain, so hydration matches;
+  //  - dev: legacy per-page compiledSource script → MDXRemote eval.
+  // Hydrate when SSR markup exists, create only when the container is empty.
+  mountIsland(
+    "mdx-content-island",
+    (el) => {
+      const sourceEl = document.getElementById("mdx-compiled-source");
+      if (sourceEl) {
+        try {
+          const compiledSource = JSON.parse(sourceEl.textContent || "");
+          return React.createElement(MDXRemote, {
+            compiledSource,
+            scope: {},
+            frontmatter: {},
+            components: createMdxComponents(),
+          });
+        } catch (e) {
+          console.error("[mdx-hydrate]", e);
+          return null;
+        }
+      }
+      const slug = el.dataset.mdxSlug;
+      // The docs root (index.mdx) renders with an empty slug — `mdxSlug != null`
+      // keeps "" addressable (its module is stored under key ""), while a
+      // missing marker stays undefined and skips hydration.
+      const mod = slug != null ? mdxModules[slug] : undefined;
+      if (!mod) return null;
+      return React.createElement(
+        MDXProvider,
+        { components: createMdxComponents() },
+        React.createElement(mod.default, null)
+      );
+    },
+    "auto"
+  );
 }
 
 if (document.readyState === "loading") {

package/.docu/node/deploy.shared.ts

@@ -35,7 +35,7 @@ export const NGINX_CONF = `server {
   add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
   add_header Referrer-Policy "strict-origin-when-cross-origin" always;
   add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
-  add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
+  add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
 
   location /assets/ {
     expires 1y;
@@ -45,7 +45,7 @@ export const NGINX_CONF = `server {
     add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
     add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
-    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
   }
 
   location /docs/assets/ {
@@ -56,7 +56,7 @@ export const NGINX_CONF = `server {
     add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
     add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
-    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'" always;
   }
 
   location / {
@@ -135,7 +135,7 @@ export const HEADERS_FILE = `/*
   Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
   Referrer-Policy: strict-origin-when-cross-origin
   Permissions-Policy: camera=(), microphone=(), geolocation=()
-  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'
 
 /assets/*
   Cache-Control: public, max-age=31536000, immutable
@@ -171,7 +171,7 @@ async function writeDockerFiles() {
   if (!existsSync(join(dockerDir, "Dockerfile"))) {
     await writeFile(
       join(dockerDir, "Dockerfile"),
-      `FROM ghcr.io/docubook/flame-builder:${FLAME_MAJOR} AS builder
+      `FROM ghcr.io/docubook/flame:${FLAME_MAJOR} AS builder
 ENV NODE_ENV=production
 WORKDIR /app
 COPY . .

package/.docu/node/deploy.ts

@@ -49,7 +49,7 @@ async function runBuild() {
   }
 }
 
-export const DOCKERFILE_BUN = `FROM ghcr.io/docubook/flame-builder:${FLAME_MAJOR} AS builder
+export const DOCKERFILE_BUN = `FROM ghcr.io/docubook/flame:${FLAME_MAJOR} AS builder
 ENV NODE_ENV=production
 WORKDIR /app
 COPY . .

package/.docu/node/hydrate.node.ts

@@ -187,7 +187,6 @@ function collectAllLucideIcons(): string[] {
     join(FRAMEWORK_ROOT, "..", "mdx-content", "dist"),
     join(FRAMEWORK_ROOT, "..", "ui-react", "dist"),
     join(FRAMEWORK_ROOT, "..", "core", "dist"),
-    join(FRAMEWORK_ROOT, "..", "runt", "dist"),
     join(FRAMEWORK_ROOT, "..", "themes-colors", "dist"),
   ];
   for (const d of depDirs) scanDirLucideIcons(resolve(d), icons);
@@ -195,7 +194,10 @@ function collectAllLucideIcons(): string[] {
 }
 
 /** Build the client JS bundle and Tailwind CSS. */
-export async function buildClientBundle(): Promise<{ js: string; css: string }> {
+export async function buildClientBundle(
+  /** slug → compiled MDX ESM module source (program format) for static hydration. */
+  mdxSources: Record<string, string> = {}
+): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
   const twKey = tailwindCacheKey();
   await cleanOldBundles(new Set([`client-${twKey}.css`]));
@@ -243,11 +245,11 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
               if (args.namespace === "lucide-virt") {
                 return { path: getLucideRealEntry(), namespace: "file" };
               }
-              // mdx-content Icon.tsx uses namespace import for arbitrary
+              // markdown Icon.tsx uses namespace import for arbitrary
               // user-provided icon names in MDX — keep full barrel there.
               if (args.importer) {
                 const normalized = normalizeImporterPath(args.importer);
-                if (normalized.includes("/mdx-content/dist/")) {
+                if (normalized.includes("/markdown/dist/")) {
                   return { path: getLucideRealEntry(), namespace: "file" };
                 }
               }
@@ -294,6 +296,69 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
             });
           },
         },
+        {
+          // Serves per-page compiled MDX (program format) as real modules so
+          // the client hydrates the content island without `new Function`.
+          // client.ts imports `{ mdxModules } from "./mdx-manifest"`.
+          name: "mdx-hydrate",
+          setup(build) {
+            // Compiled MDX (program format) imports the JSX runtime and the
+            // MDX provider. Virtual modules have no real directory, so esbuild
+            // cannot resolve bare specifiers from them — map them to the
+            // installed real paths explicitly (same pattern as lucide-optimize).
+            const require = createRequire(import.meta.url);
+            const mdxModuleDeps: Record<string, string> = {
+              "react/jsx-runtime": require.resolve("react/jsx-runtime"),
+              "react/jsx-dev-runtime": require.resolve("react/jsx-dev-runtime"),
+              "@mdx-js/react": require.resolve("@mdx-js/react"),
+            };
+            build.onResolve(
+              { filter: /^(react\/jsx-runtime|react\/jsx-dev-runtime|@mdx-js\/react)$/ },
+              (args) => {
+                if (args.namespace !== "mdx-module") return;
+                return { path: mdxModuleDeps[args.path], namespace: "file" };
+              }
+            );
+            build.onResolve({ filter: /^mdx-module:/ }, (args) => ({
+              path: args.path,
+              namespace: "mdx-module",
+            }));
+            build.onLoad({ filter: /.*/, namespace: "mdx-module" }, (args) => {
+              const slug = args.path.slice("mdx-module:".length);
+              const contents = mdxSources[slug];
+              if (contents == null) {
+                return {
+                  errors: [{ text: `unknown mdx module: ${slug}` }],
+                  contents: "",
+                  loader: "js",
+                };
+              }
+              return { contents, loader: "js" };
+            });
+            build.onResolve({ filter: /mdx-manifest$/ }, (args) => ({
+              path: args.path,
+              namespace: "mdx-manifest",
+            }));
+            build.onLoad({ filter: /.*/, namespace: "mdx-manifest" }, () => {
+              // Sort keys: the prePass fills mdxSources via Promise.all, so
+              // insertion order = resolution order (non-deterministic across
+              // processes). Stable key order keeps the bundle hash stable so
+              // the build cache (`assetsChanged`) actually hits.
+              const slugs = Object.keys(mdxSources).sort();
+              const imports = slugs
+                .map((slug, i) => {
+                  const key = slug.replace(/["\\]/g, "");
+                  return `import * as _mdx${i} from "mdx-module:${key}";`;
+                })
+                .join("\n");
+              const map = slugs.map((slug, i) => `${JSON.stringify(slug)}: _mdx${i}`).join(", ");
+              return {
+                contents: `${imports}\nexport const mdxModules = { ${map} };\n`,
+                loader: "js",
+              };
+            });
+          },
+        },
       ],
     });
   } finally {

package/.docu/node/hydrate.ts

@@ -125,7 +125,10 @@ async function buildTailwindCss(key: string): Promise<{ file: string; content: s
   return { file: cssFile, content: cssContent };
 }
 
-export async function buildClientBundle(): Promise<{ js: string; css: string }> {
+export async function buildClientBundle(
+  /** slug → compiled MDX ESM module source (program format) for static hydration. */
+  mdxSources: Record<string, string> = {}
+): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
   const twKey = twCacheKey();
   await cleanOldBundles(new Set([`client-${twKey}.css`]));
@@ -166,6 +169,52 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
           });
         },
       },
+      {
+        // Serves per-page compiled MDX (program format) as real modules so
+        // the client hydrates the content island without `new Function`.
+        // client.ts imports `{ mdxModules } from "./mdx-manifest"`.
+        name: "mdx-hydrate",
+        setup(build) {
+          build.onResolve({ filter: /^mdx-module:/ }, (args) => ({
+            path: args.path,
+            namespace: "mdx-module",
+          }));
+          build.onLoad({ filter: /.*/, namespace: "mdx-module" }, (args) => {
+            const slug = args.path.slice("mdx-module:".length);
+            const contents = mdxSources[slug];
+            if (contents == null) {
+              return {
+                errors: [{ text: `unknown mdx module: ${slug}` }],
+                contents: "",
+                loader: "js",
+              };
+            }
+            return { contents, loader: "js" };
+          });
+          build.onResolve({ filter: /mdx-manifest$/ }, (args) => ({
+            path: args.path,
+            namespace: "mdx-manifest",
+          }));
+          build.onLoad({ filter: /.*/, namespace: "mdx-manifest" }, () => {
+            // Sort keys: the prePass fills mdxSources via Promise.all, so
+            // insertion order = resolution order (non-deterministic across
+            // processes). Stable key order keeps the bundle hash stable so
+            // the build cache (`assetsChanged`) actually hits.
+            const slugs = Object.keys(mdxSources).sort();
+            const imports = slugs
+              .map((slug, i) => {
+                const key = slug.replace(/["\\]/g, "");
+                return `import * as _mdx${i} from "mdx-module:${key}";`;
+              })
+              .join("\n");
+            const map = slugs.map((slug, i) => `${JSON.stringify(slug)}: _mdx${i}`).join(", ");
+            return {
+              contents: `${imports}\nexport const mdxModules = { ${map} };\n`,
+              loader: "js",
+            };
+          });
+        },
+      },
     ],
   });
 

package/.docu/node/mdx-manifest.d.ts

@@ -0,0 +1,5 @@
+// Virtual module served by the `mdx-hydrate` esbuild plugin (hydrate.node.ts).
+// Maps doc slug → compiled MDX module. Generated at bundle time; never on disk.
+declare module "./mdx-manifest" {
+  export const mdxModules: Record<string, { default: React.ComponentType }>;
+}

package/.docu/node/mdx.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import type { Pluggable } from "unified";
+import { z, type ZodType } from "zod";
 import {
   serialize,
   extractTocsFromRawMdx,
@@ -8,7 +9,7 @@ import {
   createDefaultRemarkPlugins,
   MDXRemote,
 } from "@docubook/core";
-import { createMdxComponents } from "@docubook/mdx-content";
+import { createMdxComponents } from "@docubook/markdown";
 import { getGitLastModified, getGitLastModifiedBatch, getFilesystemMtime } from "./git";
 
 /**
@@ -106,10 +107,39 @@ export { getGitLastModifiedBatch };
 export interface MdxResult {
   content: React.ReactElement;
   compiledSource: string;
-  frontmatter: { title?: string; description?: string; date?: string };
+  frontmatter: Frontmatter;
   tocs: ReturnType<typeof extractTocsFromRawMdx>;
 }
 
+/**
+ * DocuBook frontmatter contract — single source of truth for frontmatter
+ * fields. Add new properties here; types and validation derive from it.
+ * YAML coerces unquoted values, so string fields use `z.coerce.*`.
+ */
+export const frontmatterSchema = z.object({
+  title: z.coerce.string().optional(),
+  description: z.coerce.string().optional(),
+  image: z.coerce.string().optional(),
+  date: z.coerce.string().optional(),
+});
+
+export type Frontmatter = z.infer<typeof frontmatterSchema>;
+
+/**
+ * Read a string field from frontmatter after the plugin transform chain
+ * (which widens the type to `Record<string, unknown>`). Returns "" when
+ * missing or not a string.
+ */
+export function frontmatterField(frontmatter: Record<string, unknown>, key: string): string {
+  return typeof frontmatter[key] === "string" ? (frontmatter[key] as string) : "";
+}
+
+/**
+ * Zod schema validating frontmatter after extraction.
+ * Must satisfy the frontmatter contract (defaults to `frontmatterSchema`).
+ */
+export type FrontmatterSchema = ZodType<Frontmatter>;
+
 /**
  * Compile MDX/MD content into a React element and compiled source.
  *
@@ -118,20 +148,26 @@ export interface MdxResult {
  * @param gitDates - Optional pre-fetched git last-modified map
  * @param remarkPlugins - Additional remark plugins (merged after defaults, optional)
  * @param rehypePlugins - Additional rehype plugins (merged after defaults, optional)
+ * @param frontmatterSchema - Custom schema overriding the default contract
  */
-export async function compileMdx(
+/**
+ * Shared compile core used by `compileMdx` (SSR) and `compileMdxModule`
+ * (static hydration). Strips frontmatter, merges the doc plugin chain
+ * (defaults + .html link fixes + user plugins) and runs `serialize()`.
+ */
+async function serializeWithDocPlugins(
   rawMdx: string,
-  filePath: string,
-  gitDates?: Map<string, string>,
-  remarkPlugins?: Pluggable[],
-  rehypePlugins?: Pluggable[]
-): Promise<MdxResult> {
-  const tocs = extractTocsFromRawMdx(rawMdx);
-  const { frontmatter, strippedContent } = extractFrontmatterWithContent<{
-    title?: string;
-    description?: string;
-    date?: string;
-  }>(rawMdx);
+  opts: {
+    outputFormat?: "function-body" | "program";
+    remarkPlugins?: Pluggable[];
+    rehypePlugins?: Pluggable[];
+    frontmatterSchema?: FrontmatterSchema;
+  } = {}
+) {
+  const { strippedContent } = extractFrontmatterWithContent<Frontmatter>(
+    rawMdx,
+    opts.frontmatterSchema
+  );
 
   const defaultRemark = createDefaultRemarkPlugins();
   const defaultRehype = createDefaultRehypePlugins();
@@ -139,15 +175,46 @@ export async function compileMdx(
   // remarkMdxJsxDocsHtmlLinks must run before user plugins so custom remark
   // transforms see already-fixed hrefs.  rehypeDocsHtmlLinks handles plain
   // markdown [text](path) → <a> elements in the HAST phase.
-  const finalRemark = [...defaultRemark, remarkMdxJsxDocsHtmlLinks, ...(remarkPlugins ?? [])];
-  const finalRehype = [...defaultRehype, rehypeDocsHtmlLinks, ...(rehypePlugins ?? [])];
+  const finalRemark = [...defaultRemark, remarkMdxJsxDocsHtmlLinks, ...(opts.remarkPlugins ?? [])];
+  const finalRehype = [...defaultRehype, rehypeDocsHtmlLinks, ...(opts.rehypePlugins ?? [])];
 
-  const serialized = await serialize(strippedContent, {
+  // v2 contract: plain markdown + directives only — authored JSX tags are
+  // not parsed (dropped, content kept as text).
+  return serialize(strippedContent, {
+    outputFormat: opts.outputFormat,
+    format: "md",
     mdxOptions: {
       rehypePlugins: finalRehype,
       remarkPlugins: finalRemark,
     },
   });
+}
+
+/**
+ * Compile MDX/MD content into a React element and compiled source.
+ *
+ * @param rawMdx - Raw MDX/MD file content
+ * @param filePath - Relative file path for git date lookup
+ * @param gitDates - Optional pre-fetched git last-modified map
+ * @param remarkPlugins - Additional remark plugins (merged after defaults, optional)
+ * @param rehypePlugins - Additional rehype plugins (merged after defaults, optional)
+ * @param frontmatterSchema - Custom schema overriding the default contract
+ */
+export async function compileMdx(
+  rawMdx: string,
+  filePath: string,
+  gitDates?: Map<string, string>,
+  remarkPlugins?: Pluggable[],
+  rehypePlugins?: Pluggable[],
+  frontmatterSchema?: FrontmatterSchema
+): Promise<MdxResult> {
+  const tocs = extractTocsFromRawMdx(rawMdx);
+  const { frontmatter } = extractFrontmatterWithContent<Frontmatter>(rawMdx, frontmatterSchema);
+  const serialized = await serializeWithDocPlugins(rawMdx, {
+    remarkPlugins,
+    rehypePlugins,
+    frontmatterSchema,
+  });
 
   const components = createMdxComponents();
   const content = React.createElement(MDXRemote, {
@@ -171,3 +238,22 @@ export async function compileMdx(
     tocs,
   };
 }
+
+/**
+ * Compile MDX to a real ESM module source (program format) for static
+ * client-side hydration — the browser imports and executes it via the bundler
+ * instead of `new Function(compiledSource)`. Uses the same plugin chain as
+ * `compileMdx` so the hydrated tree matches the SSR output.
+ */
+export async function compileMdxModule(
+  rawMdx: string,
+  remarkPlugins?: Pluggable[],
+  rehypePlugins?: Pluggable[]
+): Promise<string> {
+  const serialized = await serializeWithDocPlugins(rawMdx, {
+    outputFormat: "program",
+    remarkPlugins,
+    rehypePlugins,
+  });
+  return serialized.compiledSource;
+}

package/.docu/node/preview.deno.ts

@@ -1,4 +1,4 @@
-import { denoAdapter } from "@docubook/runt";
+import { denoAdapter } from "./runtime";
 import { runPreview } from "./preview.impl";
 
 await runPreview(denoAdapter);