@docubook/flame 2.0.0-beta.5 → 2.0.0

package/.docu/node/build.ts

@@ -21,6 +21,7 @@ import {
   CACHE_FILE,
   DOCS_ASSETS_DIR,
   PROJECT_ROOT,
+  PAGES_DIR,
   loadDocuConfig,
 } from "./paths";
 import { htmlShell } from "./html";
@@ -31,7 +32,7 @@ import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
-import type { BuildCache, BuildCacheMeta, CliArgs } from "./types";
+import type { AssetManifest, BuildCache, BuildCacheMeta, CliArgs } from "./types";
 import { isCacheEntry } from "./types";
 import {
   BUILD_CACHE_VERSION,
@@ -117,7 +118,11 @@ export function shouldRebuild(path: string, mtime: number, cache: BuildCache): R
   return "no";
 }
 
-let assetManifest = { js: "client.js", css: "client.css" };
+let assetManifest: AssetManifest = {
+  docs: { js: "client.js", css: "docs.css" },
+  home: { js: "home-client.js", css: "site.css" },
+  notFound: { css: "site.css" },
+};
 
 /**
  * Reuse manifest.json on bundle cache hit; fall back to a full rebuild
@@ -126,15 +131,20 @@ let assetManifest = { js: "client.js", css: "client.css" };
 async function resolveAssetManifest(
   bundleHit: boolean,
   mdxSources: Record<string, string>
-): Promise<{ js: string; css: string }> {
+): Promise<AssetManifest> {
   if (!bundleHit) return buildClientBundle(mdxSources);
   try {
-    const manifest = JSON.parse(await readFile(join(ASSETS_DIR, "manifest.json"), "utf-8")) as {
-      js?: string;
-      css?: string;
-    };
-    if (typeof manifest.js === "string" && typeof manifest.css === "string") {
-      return { js: manifest.js, css: manifest.css };
+    const manifest = JSON.parse(
+      await readFile(join(ASSETS_DIR, "manifest.json"), "utf-8")
+    ) as Partial<AssetManifest>;
+    if (
+      typeof manifest.docs?.js === "string" &&
+      typeof manifest.docs.css === "string" &&
+      typeof manifest.home?.js === "string" &&
+      typeof manifest.home.css === "string" &&
+      typeof manifest.notFound?.css === "string"
+    ) {
+      return manifest as AssetManifest;
     }
   } catch {
     // corrupt/missing manifest — rebuild below
@@ -221,7 +231,15 @@ async function renderDocsPage(
 
   const body = renderToString(page);
 
-  const ctx: PageContext = { slug, filePath, frontmatter, content, config: docuConfig };
+  const ctx: PageContext = {
+    pageType: "docs",
+    assets: assetManifest.docs,
+    slug,
+    filePath,
+    frontmatter,
+    content,
+    config: docuConfig,
+  };
   const headExtra = builder?.collectHead(ctx);
   const bodyExtra = builder?.collectBody(ctx);
 
@@ -238,8 +256,8 @@ async function renderDocsPage(
     favicon,
     seo,
     csp,
-    css: assetManifest.css,
-    js: assetManifest.js,
+    css: ctx.assets.css,
+    js: ctx.assets.js,
     nonce,
     themeCss: inlineThemeCss,
     depth,
@@ -380,14 +398,10 @@ async function build() {
   inlineThemeCss = computeInlineThemeCss();
 
   const lastManifest = cache["__assets__"];
-  const assetsChanged =
-    !isCacheEntry(lastManifest) || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;
+  const assetHash = JSON.stringify(assetManifest);
+  const assetsChanged = !isCacheEntry(lastManifest) || lastManifest.hash !== assetHash;
   if (assetsChanged) {
-    cache["__assets__"] = {
-      hash: `${assetManifest.js}:${assetManifest.css}`,
-      mtime: 0,
-      builtAt: Date.now(),
-    };
+    cache["__assets__"] = { hash: assetHash, mtime: 0, builtAt: Date.now() };
   }
   if (!bundleHit) {
     cache["__bundle__"] = { hash: bundleHash, mtime: 0, builtAt: Date.now() };
@@ -410,7 +424,7 @@ async function build() {
   for (const file of mdxFiles) {
     const rebuildDecision = shouldRebuild(file.path, file.mtime, cache);
 
-    if (rebuildDecision === "no") {
+    if (rebuildDecision === "no" && !builder) {
       const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
       if (existsSync(outputPath) && !assetsChanged) {
         skipped++;
@@ -428,7 +442,7 @@ async function build() {
       }
     }
 
-    if (rebuildDecision === "hash_check") {
+    if (rebuildDecision === "hash_check" && !builder) {
       const contentHash = hashContent(rawMdx);
       const cached = cache[file.path];
       if (isCacheEntry(cached) && cached.hash === contentHash) {
@@ -512,42 +526,62 @@ async function build() {
     ""
   );
   const landingNonce = generateNonce();
-  const landingHtml = htmlShell({
+  const landingContext: PageContext = {
+    pageType: "home",
+    assets: assetManifest.home,
+    slug: "",
+    filePath: join(PAGES_DIR, "index.tsx"),
+    frontmatter: { ...docuConfig.meta } as unknown as Record<string, unknown>,
+    config: docuConfig,
+  };
+  let landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",
     description: docuConfig.meta?.description || "",
     body: renderToString(landingPage),
     favicon: landingFavicon,
     seo: landingSeo,
     csp: cspHeader(landingNonce),
-    css: assetManifest.css,
-    js: assetManifest.js,
+    css: landingContext.assets.css,
+    js: landingContext.assets.js,
     nonce: landingNonce,
     themeCss: inlineThemeCss,
+    headExtra: builder?.collectHead(landingContext),
+    bodyExtra: builder?.collectBody(landingContext),
   });
+  if (builder) landingHtml = await builder.runTransformHtmlChain(landingHtml, landingContext);
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
 
-  const notFoundPage = React.createElement(
-    DocsLayout,
-    { repoUrl: docuConfig.repo?.url },
-    React.createElement(NotFoundPage)
-  );
+  const notFoundPage = React.createElement(NotFoundPage);
   const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
   const notFoundNonce = generateNonce();
-  const notFoundHtml = htmlShell({
+  const notFoundContext: PageContext = {
+    pageType: "notFound",
+    assets: assetManifest.notFound,
+    slug: "404",
+    filePath: join(PAGES_DIR, "404.tsx"),
+    frontmatter: {},
+    config: docuConfig,
+  };
+  let notFoundHtml = htmlShell({
     title: "404 - Not Found",
     description: "",
     body: renderToString(notFoundPage),
     favicon: notFoundFavicon,
-    headExtra: ['<meta name="robots" content="noindex,follow">'],
+    headExtra: [
+      '<meta name="robots" content="noindex,follow">',
+      ...(builder?.collectHead(notFoundContext) ?? []),
+    ],
+    bodyExtra: builder?.collectBody(notFoundContext),
     csp: cspHeader(notFoundNonce),
-    css: assetManifest.css,
-    js: assetManifest.js,
+    css: notFoundContext.assets.css,
+    js: notFoundContext.assets.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,
   });
+  if (builder) notFoundHtml = await builder.runTransformHtmlChain(notFoundHtml, notFoundContext);
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 
   logger.spinner.stop(
@@ -561,7 +595,7 @@ async function build() {
       filePath: join(DOCS_DIR, f.path),
       outputPath: join(DIST_DIR, "docs", `${f.path}.html`),
     }));
-    await builder.runOnEnd(pages);
+    await builder.runOnEnd(pages, { assetManifest, outDir: DIST_DIR });
   }
 
   logger.indexStart();

package/.docu/node/cache-key.ts

@@ -8,7 +8,7 @@ import { FRAMEWORK_ROOT, STYLES_DIR, resolveProjectFile } from "./paths";
  * (e.g. Bun.build barrel optimization, Tailwind CLI upgrade). Old caches
  * with a mismatched version are discarded on read (see build.ts readCache).
  */
-export const BUILD_CACHE_VERSION = 4;
+export const BUILD_CACHE_VERSION = 5;
 
 /** Toolchain fingerprint: Bun version on Bun, Deno version on Deno, Node elsewhere. */
 export function runtimeStamp(): string {
@@ -234,10 +234,14 @@ export function computeTailwindCacheKey(
   return h.digest("hex").slice(0, 16);
 }
 
-/** Read globals.css content ("" when missing). Shared by both hydrators. */
+/** Read a Tailwind entry plus relative imports for cache invalidation. */
+export function readStyleCss(file = "globals.css"): string {
+  return readCssWithImports(join(STYLES_DIR, file), new Set());
+}
+
+/** Backward-compatible alias for the docs stylesheet entry. */
 export function readGlobalsCss(): string {
-  const globalsPath = join(STYLES_DIR, "globals.css");
-  return existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+  return readStyleCss();
 }
 
 /**

package/.docu/node/client.ts

@@ -6,7 +6,7 @@ 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";
 
@@ -21,14 +21,7 @@ import type { TocItem } from "./types";
  */
 type MountMode = "auto" | "hydrate" | "create";
 
-function mountIsland(
-  id: string,
-  render: (el: HTMLElement) => React.ReactElement | null,
-  mode: MountMode = "auto"
-) {
-  const el = document.getElementById(id);
-  if (!el) return;
-  const node = render(el);
+function mountNode(el: HTMLElement, node: React.ReactElement | null, mode: MountMode) {
   if (node === null) return; // island stays as-is (SSR HTML preserved)
   const hydrate = mode === "hydrate" || (mode === "auto" && el.childElementCount > 0);
   if (hydrate) {
@@ -39,6 +32,28 @@ function mountIsland(
   }
 }
 
+function mountIsland(
+  id: string,
+  render: (el: HTMLElement) => React.ReactElement | null,
+  mode: MountMode = "auto"
+) {
+  const el = document.getElementById(id);
+  if (!el) return;
+  mountNode(el, render(el), mode);
+}
+
+function mountAsyncIsland(
+  id: string,
+  render: (el: HTMLElement) => Promise<React.ReactElement | null>,
+  mode: MountMode = "auto"
+) {
+  const el = document.getElementById(id);
+  if (!el) return;
+  render(el)
+    .then((node) => mountNode(el, node, mode))
+    .catch((error) => console.error(`[${id}]`, error));
+}
+
 function mountIslands() {
   // SSR renders <Menu> only; client renders full <Sidebar> (DesktopSidebar +
   // MobileBar) — structural mismatch makes hydration impossible, so always
@@ -72,8 +87,6 @@ function mountIslands() {
     return React.createElement(Toc, { tocs });
   });
 
-  mountIsland("theme-island", () => React.createElement(ThemeToggle));
-
   // 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
@@ -81,30 +94,26 @@ function mountIslands() {
   //    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(
+  mountAsyncIsland(
     "mdx-content-island",
-    (el) => {
+    async (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 compiledSource = JSON.parse(sourceEl.textContent || "");
+        return React.createElement(MDXRemote, {
+          compiledSource,
+          scope: {},
+          frontmatter: {},
+          components: createMdxComponents(),
+        });
       }
       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;
+      const load = slug != null ? mdxModules[slug] : undefined;
+      if (!load) return null;
+      const mod = await load();
       return React.createElement(
         MDXProvider,
         { components: createMdxComponents() },

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

@@ -13,9 +13,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { DIST_DIR, PROJECT_ROOT, FRAMEWORK_ROOT } from "./paths";
 
-const FLAME_MAJOR = JSON.parse(
+const FLAME_VERSION = JSON.parse(
   readFileSync(resolve(FRAMEWORK_ROOT, "package.json"), "utf-8")
-).version.split(".")[0];
+).version;
 
 const WORKFLOW_DIR = join(PROJECT_ROOT, ".github/workflows");
 const WORKFLOW_FILE = join(WORKFLOW_DIR, "deploy.yml");
@@ -25,6 +25,7 @@ export const NGINX_CONF = `server {
   server_name _;
   root /usr/share/nginx/html;
   index index.html;
+  error_page 404 /404.html;
 
   gzip on;
   gzip_types text/html text/css application/javascript image/svg+xml;
@@ -37,6 +38,16 @@ export const NGINX_CONF = `server {
   add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" 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;
 
+  # Build metadata and search content use stable URLs, so clients must revalidate them.
+  location = /assets/manifest.json {
+    expires -1;
+  }
+
+  location = /assets/search-index.json {
+    expires -1;
+  }
+
+  # Generated JS, CSS, and chunks include content hashes in their filenames.
   location /assets/ {
     expires 1y;
     add_header Cache-Control "public, immutable";
@@ -59,6 +70,8 @@ export const NGINX_CONF = `server {
     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 = /404.html { }
+
   location / {
     try_files $uri $uri.html $uri/ =404;
   }
@@ -75,6 +88,19 @@ export const DOCKERIGNORE = `node_modules
 *.log
 `;
 
+export const DOCKERFILE = `FROM ghcr.io/docubook/flame:${FLAME_VERSION} AS builder
+ENV NODE_ENV=production
+WORKDIR /app
+COPY . .
+RUN flame build --bun
+
+FROM nginx:alpine
+COPY --from=builder /app/.docu/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+
 export function detectPkgManager(dir: string): {
   baseImage: string;
   lockFile: string;
@@ -137,8 +163,22 @@ export const HEADERS_FILE = `/*
   Permissions-Policy: camera=(), microphone=(), geolocation=()
   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/*
+/assets/client-*
   Cache-Control: public, max-age=31536000, immutable
+/assets/home-client-*
+  Cache-Control: public, max-age=31536000, immutable
+/assets/docs-*
+  Cache-Control: public, max-age=31536000, immutable
+/assets/site-*
+  Cache-Control: public, max-age=31536000, immutable
+/assets/chunks/*
+  Cache-Control: public, max-age=31536000, immutable
+/assets/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+/assets/manifest.json
+  Cache-Control: no-cache
+/assets/search-index.json
+  Cache-Control: no-cache
 `;
 
 const isDocker = !!process.env.FLAME_DEPLOY_DOCKER;
@@ -169,21 +209,7 @@ async function writeDockerFiles() {
   const dockerDir = PROJECT_ROOT;
 
   if (!existsSync(join(dockerDir, "Dockerfile"))) {
-    await writeFile(
-      join(dockerDir, "Dockerfile"),
-      `FROM ghcr.io/docubook/flame:${FLAME_MAJOR} AS builder
-ENV NODE_ENV=production
-WORKDIR /app
-COPY . .
-RUN flame build
-
-FROM nginx:alpine
-COPY --from=builder /app/.docu/dist /usr/share/nginx/html
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-EXPOSE 80
-CMD ["nginx", "-g", "daemon off;"]
-`
-    );
+    await writeFile(join(dockerDir, "Dockerfile"), DOCKERFILE);
     log.created("📄 Created Dockerfile");
   }
 

package/.docu/node/deploy.ts

@@ -8,14 +8,10 @@
  */
 
 import { mkdir } from "node:fs/promises";
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { DIST_DIR, PROJECT_ROOT, FRAMEWORK_ROOT } from "./paths";
-import { HEADERS_FILE, NGINX_CONF, DOCKERIGNORE } from "./deploy.shared";
-
-const FLAME_PKG = JSON.parse(readFileSync(resolve(FRAMEWORK_ROOT, "package.json"), "utf-8"));
-const FLAME_VERSION = FLAME_PKG.version;
-const FLAME_MAJOR = FLAME_VERSION.split(".")[0];
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DIST_DIR, PROJECT_ROOT } from "./paths";
+import { DOCKERFILE, HEADERS_FILE, NGINX_CONF, DOCKERIGNORE } from "./deploy.shared";
 
 export { HEADERS_FILE, NGINX_CONF, DOCKERIGNORE };
 
@@ -49,18 +45,7 @@ async function runBuild() {
   }
 }
 
-export const DOCKERFILE_BUN = `FROM ghcr.io/docubook/flame:${FLAME_MAJOR} AS builder
-ENV NODE_ENV=production
-WORKDIR /app
-COPY . .
-RUN flame build
-
-FROM nginx:alpine
-COPY --from=builder /app/.docu/dist /usr/share/nginx/html
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-EXPOSE 80
-CMD ["nginx", "-g", "daemon off;"]
-`;
+export const DOCKERFILE_BUN = DOCKERFILE;
 
 async function writeDockerFiles() {
   const dockerDir = PROJECT_ROOT;

package/.docu/node/home-client.ts

@@ -0,0 +1,6 @@
+import { hydrateRoot } from "react-dom/client";
+import React from "react";
+import { ThemeToggle } from "../components/Theme";
+
+const root = document.getElementById("theme-toggle-island");
+if (root) hydrateRoot(root, React.createElement(ThemeToggle));

package/.docu/node/html.shared.ts

@@ -17,7 +17,7 @@ export interface HtmlShellOptions {
   body: string;
   favicon: string;
   css: string;
-  js: string;
+  js?: string;
   nonce?: string;
   /**
    * Content-Security-Policy value (from `cspHeader()` in security.ts).
@@ -63,6 +63,9 @@ export function htmlShell(opts: HtmlShellOptions): string {
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
   const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const clientScript = js
+    ? `\n  <link rel="modulepreload" href="${escapeHtml(assetPrefix + js)}">\n  <script type="module"${nonceAttr} src="${escapeHtml(assetPrefix + js)}"></script>`
+    : "";
   const resolvePath = (path: string) =>
     absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
@@ -92,9 +95,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>
 <body>
-  <div id="root">${body}</div>
-  <link rel="modulepreload" href="${escapeHtml(assetPrefix + js)}">
-  <script type="module"${nonceAttr} src="${escapeHtml(assetPrefix + js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
+  <div id="root">${body}</div>${clientScript}${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
 </body>
 </html>`;
 }

package/.docu/node/html.ts

@@ -25,6 +25,9 @@ export function htmlShell(opts: HtmlShellOptions): string {
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
   const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const clientScript = js
+    ? `\n  <link rel="modulepreload" href="${Bun.escapeHTML(assetPrefix + js)}">\n  <script type="module"${nonceAttr} src="${Bun.escapeHTML(assetPrefix + js)}"></script>`
+    : "";
   const resolvePath = (path: string) =>
     absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
@@ -54,9 +57,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>
 <body>
-  <div id="root">${body}</div>
-  <link rel="modulepreload" href="${Bun.escapeHTML(assetPrefix + js)}">
-  <script type="module"${nonceAttr} src="${Bun.escapeHTML(assetPrefix + js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
+  <div id="root">${body}</div>${clientScript}${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
 </body>
 </html>`;
 }