@docubook/flame 1.7.2 → 2.0.0-alpha.1

package/.docu/lib/chunk-UISOJ4RW.js

@@ -0,0 +1,114 @@
+// .docu/node/runtime/deno.ts
+var denoAdapter = {
+  name: "deno",
+  serve(fetch, options) {
+    const server = Deno.serve(
+      {
+        port: options.port,
+        hostname: options.hostname,
+        onListen: () => {
+        }
+      },
+      fetch
+    );
+    return {
+      port: server.addr.port,
+      hostname: server.addr.hostname,
+      stop: () => server.shutdown()
+    };
+  }
+};
+
+// .docu/node/runtime/node.ts
+import { createServer } from "node:http";
+function toWebRequest(req, port, hostname) {
+  const host = req.headers.host ?? `${hostname}:${port}`;
+  const url = `http://${host}${req.url ?? "/"}`;
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(key, v);
+    } else {
+      headers.set(key, value);
+    }
+  }
+  const method = req.method ?? "GET";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  return new Request(url, {
+    method,
+    headers,
+    // IncomingMessage is an async iterable of Buffer chunks; Request accepts
+    // an async iterable body when half-duplex is declared.
+    body: hasBody ? req : void 0,
+    // @ts-expect-error -- required by undici for streaming request bodies
+    duplex: hasBody ? "half" : void 0
+  });
+}
+async function writeResponse(response, res) {
+  const headers = {};
+  const setCookie = response.headers.getSetCookie?.() ?? [];
+  response.headers.forEach((value, key) => {
+    if (key === "set-cookie") return;
+    headers[key] = value;
+  });
+  if (setCookie.length > 0) headers["set-cookie"] = setCookie;
+  res.writeHead(response.status, headers);
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const ok = res.write(value);
+      if (!ok) await new Promise((resolve) => res.once("drain", resolve));
+    }
+    res.end();
+  } catch {
+    await reader.cancel().catch(() => {
+    });
+    res.destroy();
+  }
+}
+var nodeAdapter = {
+  name: "node",
+  serve(fetch, options) {
+    const hostname = options.hostname ?? "localhost";
+    const server = createServer((req, res) => {
+      Promise.resolve().then(() => fetch(toWebRequest(req, options.port, hostname))).then((response) => writeResponse(response, res)).catch((err) => {
+        console.error(err);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "text/plain" });
+        }
+        res.end("Internal Server Error");
+      });
+    });
+    if (options.idleTimeout !== void 0) {
+      server.timeout = options.idleTimeout * 1e3;
+      server.keepAliveTimeout = options.idleTimeout * 1e3;
+    }
+    return new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(options.port, () => {
+        const address = server.address();
+        const port = typeof address === "object" && address ? address.port : options.port;
+        resolve({
+          port,
+          hostname,
+          stop: () => new Promise((res2, rej2) => {
+            server.closeAllConnections?.();
+            server.close((err) => err ? rej2(err) : res2());
+          })
+        });
+      });
+    });
+  }
+};
+
+export {
+  denoAdapter,
+  nodeAdapter
+};

package/.docu/lib/clean.js

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-PJIJEPNR.js";
+} from "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/clean.ts

package/.docu/lib/deploy.deno.js

@@ -1,6 +1,6 @@
 import {
   runDeploy
-} from "./chunk-SPHVBXRR.js";
+} from "./chunk-7PRQ3RQB.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/deploy.deno.ts

package/.docu/lib/deploy.node.js

@@ -1,6 +1,6 @@
 import {
   runDeploy
-} from "./chunk-SPHVBXRR.js";
+} from "./chunk-7PRQ3RQB.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/deploy.node.ts

package/.docu/lib/preview.deno.js

@@ -1,10 +1,12 @@
 import {
   runPreview
-} from "./chunk-KMDGSD57.js";
+} from "./chunk-LZDEWK25.js";
+import {
+  denoAdapter
+} from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-PJIJEPNR.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.deno.ts
-import { denoAdapter } from "@docubook/runt";
 await runPreview(denoAdapter);

package/.docu/lib/preview.node.js

@@ -1,10 +1,12 @@
 import {
   runPreview
-} from "./chunk-KMDGSD57.js";
+} from "./chunk-LZDEWK25.js";
+import {
+  nodeAdapter
+} from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-PJIJEPNR.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.node.ts
-import { nodeAdapter } from "@docubook/runt";
 await runPreview(nodeAdapter);

package/.docu/lib/server.deno.js

@@ -1,11 +1,13 @@
 import {
   runServer
-} from "./chunk-DITXUPUV.js";
-import "./chunk-B6LGUADD.js";
+} from "./chunk-A6FIEG3H.js";
+import "./chunk-TRT6WQZG.js";
+import {
+  denoAdapter
+} from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-PJIJEPNR.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.deno.ts
-import { denoAdapter } from "@docubook/runt";
 await runServer(denoAdapter);

package/.docu/lib/server.node.js

@@ -1,11 +1,13 @@
 import {
   runServer
-} from "./chunk-DITXUPUV.js";
-import "./chunk-B6LGUADD.js";
+} from "./chunk-A6FIEG3H.js";
+import "./chunk-TRT6WQZG.js";
+import {
+  nodeAdapter
+} from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-PJIJEPNR.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.node.ts
-import { nodeAdapter } from "@docubook/runt";
 await runServer(nodeAdapter);

package/.docu/node/build.impl.ts

@@ -12,7 +12,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,
@@ -120,8 +120,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(
@@ -131,12 +131,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,
     })
   );
 
@@ -149,11 +152,9 @@ async function renderDocsPage(
   const depth = slug ? slug.split("/").length : 1;
   const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
-  /**
-   * @docubook/mdx-remote uses new Function(compiledSource) for
-   * client-side MDX hydration. Keep allowEval=true until mdx-remote drops new Function.
-   */
-  const csp = cspHeader(nonce, true);
+  // MDX content hydrates from the bundled ESM module (mdx-hydrate), not
+  // new Function — no 'unsafe-eval' needed in the CSP.
+  const csp = cspHeader(nonce);
   let html = htmlShell({
     title,
     description,
@@ -217,9 +218,66 @@ export async function runBuild(): Promise<void> {
   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();
@@ -235,16 +293,6 @@ export async function runBuild(): Promise<void> {
     };
   }
 
-  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();
 
@@ -362,8 +410,7 @@ export async function runBuild(): Promise<void> {
     body: renderToString(landingPage),
     favicon: landingFavicon,
     seo: landingSeo,
-    /** unsafe-eval required by mdx-remote hydration — see above. */
-    csp: cspHeader(landingNonce, true),
+    csp: cspHeader(landingNonce),
     css: assetManifest.css,
     js: assetManifest.js,
     nonce: landingNonce,
@@ -384,12 +431,14 @@ export async function runBuild(): Promise<void> {
     body: renderToString(notFoundPage),
     favicon: notFoundFavicon,
     headExtra: ['<meta name="robots" content="noindex,follow">'],
-    /** unsafe-eval required by mdx-remote hydration — see above. */
-    csp: cspHeader(notFoundNonce, true),
+    csp: cspHeader(notFoundNonce),
     css: assetManifest.css,
     js: assetManifest.js,
     nonce: notFoundNonce,
     themeCss: inlineThemeCss,
+    // Served as the static-host fallback at ANY requested path — relative
+    // depth can never be right there, so use root-absolute asset URLs.
+    absoluteAssets: true,
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 

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();
 
@@ -368,6 +418,9 @@ async function build() {
     js: assetManifest.js,
     nonce: generateNonce(),
     themeCss: inlineThemeCss,
+    // Served as the static-host fallback at ANY requested path — relative
+    // depth can never be right there, so use root-absolute asset URLs.
+    absoluteAssets: true,
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 

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") {