@docubook/flame 2.0.0-beta.5 → 2.0.0

package/.docu/node/plugin-builder.ts

@@ -1,5 +1,12 @@
 import type { Pluggable } from "unified";
-import type { DocuConfig, PageContext, PageMeta, DevServerContext, PluginBuilder } from "./plugin";
+import type {
+  BuildEndContext,
+  DevServerContext,
+  DocuConfig,
+  PageContext,
+  PageMeta,
+  PluginBuilder,
+} from "./plugin";
 
 type Awaitable<T> = T | Promise<T>;
 
@@ -20,7 +27,9 @@ export class BuildPluginBuilder implements PluginBuilder {
   > = [];
   private _injectBody: Array<(context: PageContext) => string | string[]> = [];
   private _injectHead: Array<(context: PageContext) => string | string[]> = [];
-  private _onEnd: Array<(config: DocuConfig, pages: PageMeta[]) => Awaitable<void>> = [];
+  private _onEnd: Array<
+    (config: DocuConfig, pages: PageMeta[], context: BuildEndContext) => Awaitable<void>
+  > = [];
   private _onLoad: OnLoadHandler[] = [];
   private _onStart: Array<(config: DocuConfig) => Awaitable<void>> = [];
   private _rehypePlugins: Array<() => Pluggable[]> = [];
@@ -185,22 +194,24 @@ export class BuildPluginBuilder implements PluginBuilder {
 
   /**
    * Register a callback to run once after all pages are built.
-   * Receives the resolved config and aggregated page metadata.
-   * Errors thrown by the callback propagate to the caller via `runOnEnd()`.
+   * Receives the resolved config, aggregated docs metadata, and final build metadata.
+   * Callback errors are logged by `runOnEnd()` and do not stop later callbacks.
    *
-   * @param callback - Receives config and page metadata array. May return a Promise.
+   * @param callback - Receives config, page metadata, and emitted assets. May return a Promise.
    *
    * @example
-   * build.onEnd(async (config, pages) => {
+   * build.onEnd(async (config, pages, { outDir }) => {
    *   const xml = generateSitemap(pages, config.meta.baseURL);
-   *   const out = ".docu/dist/sitemap.xml";
+   *   const out = join(outDir, "sitemap.xml");
    *   // Bun.write on Bun for speed, writeFile on Node/Deno
    *   await (typeof Bun !== "undefined"
    *     ? Bun.write(out, xml)
    *     : writeFile(out, xml));
    * });
    */
-  onEnd(callback: (config: DocuConfig, pages: PageMeta[]) => Awaitable<void>): void {
+  onEnd(
+    callback: (config: DocuConfig, pages: PageMeta[], context: BuildEndContext) => Awaitable<void>
+  ): void {
     this._onEnd.push(callback);
   }
 
@@ -208,7 +219,7 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Register a callback to transform raw file content before MDX compilation.
    * Filtered by regex against the file's relative path — only the **first** matching
    * handler's result is used.
-   * Errors thrown by the callback propagate to the caller via `runOnLoad()`.
+   * Callback errors are logged by `runOnLoad()` before trying later matching handlers.
    *
    * @param args.filter - RegExp matched against the file's relative path.
    * @param args.namespace - Optional namespace prefix (reserved for future use).
@@ -232,7 +243,7 @@ export class BuildPluginBuilder implements PluginBuilder {
   /**
    * Register a callback to run once before the build starts.
    * Receives the resolved DocuConfig for validation or resource initialization.
-   * Errors thrown by the callback propagate to the caller via `runOnStart()`.
+   * Callback errors are logged by `runOnStart()` and do not stop later callbacks.
    *
    * @param callback - Receives the resolved config. May return a Promise.
    *
@@ -303,12 +314,13 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Errors inside individual callbacks are caught and logged — execution
    * continues to the next callback without throwing.
    *
-   * @param pages - Array of metadata for every built page.
+   * @param pages - Array of metadata for every built docs page.
+   * @param context - Final output directory and page-specific asset manifest.
    */
-  async runOnEnd(pages: PageMeta[]): Promise<void> {
+  async runOnEnd(pages: PageMeta[], context: BuildEndContext): Promise<void> {
     for (let i = 0; i < this._onEnd.length; i++) {
       try {
-        await this._onEnd[i](this.config, pages);
+        await this._onEnd[i](this.config, pages, context);
       } catch (err) {
         console.error(
           `[plugin] onEnd callback #${i + 1} error: ${err instanceof Error ? err.message : String(err)}`

package/.docu/node/plugin.ts

@@ -1,5 +1,5 @@
 import type { Pluggable } from "unified";
-import type { DocuConfig } from "./types";
+import type { AssetEntry, AssetManifest, DocuConfig } from "./types";
 
 // ─── Config Types ───────────────────────────────────────
 
@@ -18,14 +18,20 @@ export type PluginEntry = string | [string, Record<string, unknown>];
 /**
  * Context passed to content-transform hooks for a single page.
  */
+export type PageType = keyof AssetManifest;
+
 export interface PageContext {
+  /** Page family used to select the page-specific asset bundle. */
+  pageType: PageType;
+  /** Hashed CSS and optional JavaScript entry used by this page. */
+  assets: Readonly<AssetEntry>;
   /** Relative slug path: "getting-started/introduction" */
   slug: string;
-  /** Absolute file path on disk */
+  /** Absolute or project-relative source file path on disk. */
   filePath: string;
-  /** Parsed frontmatter metadata */
+  /** Parsed frontmatter metadata. Generated pages receive site metadata or an empty object. */
   frontmatter: Record<string, unknown>;
-  /** Raw MDX/MD content (only available in `transformFrontmatter` when enabled) */
+  /** Raw MDX/MD content. Only docs pages provide content. */
   content?: string;
   /** Resolved site configuration */
   config: DocuConfig;
@@ -53,9 +59,21 @@ export interface DevServerContext {
   port: number;
   /** Dev server hostname */
   hostname: string;
+  /** Current page-specific asset manifest, refreshed after HMR rebuilds. */
+  assetManifest: Readonly<AssetManifest>;
 }
 
-export type { DocuConfig };
+/**
+ * Final build metadata passed to `onEnd` after all HTML files are written.
+ */
+export interface BuildEndContext {
+  /** Page-specific hashed assets emitted under `outDir/assets`. */
+  assetManifest: Readonly<AssetManifest>;
+  /** Absolute static output directory. */
+  outDir: string;
+}
+
+export type { AssetEntry, AssetManifest, DocuConfig };
 
 // ─── PluginBuilder Interface ────────────────────────────
 
@@ -95,19 +113,25 @@ export interface PluginBuilder {
    * Register a callback to run once after all pages are built.
    * Use for: generating sitemaps, RSS feeds, manifests, post-build reports.
    *
-   * @param callback - Receives config and aggregated page metadata. May return a Promise.
+   * @param callback - Receives config, aggregated docs metadata, and final build metadata.
    *
    * @example
-   * build.onEnd(async (config, pages) => {
+   * build.onEnd(async (config, pages, { outDir }) => {
    *   const xml = generateSitemap(pages, config.meta.baseURL);
-   *   const out = join(DIST_DIR, "sitemap.xml");
+   *   const out = join(outDir, "sitemap.xml");
    *   // Bun.write on Bun for speed, writeFile on Node/Deno
    *   await (typeof Bun !== "undefined"
    *     ? Bun.write(out, xml)
    *     : writeFile(out, xml));
    * });
    */
-  onEnd(callback: (config: DocuConfig, pages: PageMeta[]) => void | Promise<void>): void;
+  onEnd(
+    callback: (
+      config: DocuConfig,
+      pages: PageMeta[],
+      context: BuildEndContext
+    ) => void | Promise<void>
+  ): void;
 
   // ─── Content Transform ─────────────────────────────────
 

package/.docu/node/server-routes.ts

@@ -5,10 +5,10 @@ import React, { type ReactNode } from "react";
 import { renderToString } from "react-dom/server";
 import { compileMdx, frontmatterField } from "./mdx";
 import { DEFAULT_FAVICON, getContentType } from "./utils";
-import { DOCS_DIR, DIST_DIR, PROJECT_ROOT } from "./paths";
+import { DOCS_DIR, DIST_DIR, PAGES_DIR, PROJECT_ROOT } from "./paths";
 import { BuildPluginBuilder } from "./plugin-builder";
-import type { PageContext } from "./plugin";
-import type { DocuConfig, TocItem } from "./types";
+import type { PageContext, PageType } from "./plugin";
+import type { AssetEntry, AssetManifest, DocuConfig, TocItem } from "./types";
 import DocsPage from "../pages/docs/[[...slug]]";
 import NotFoundPage from "../pages/404";
 import IndexPage from "../pages/index";
@@ -18,37 +18,49 @@ import { htmlShell as createHtmlShell, hmrScript, errorHtml } from "./html.share
 
 export interface ServerState {
   docuConfig: DocuConfig;
-  assetManifest: { css: string; js: string };
+  assetManifest: AssetManifest;
   inlineThemeCss?: string;
   builder: BuildPluginBuilder | null;
 }
 
-function createHtmlResponse(
+async function createHtmlResponse(
   title: string,
   description: string,
   body: string,
   status: number,
   state: ServerState,
+  pageType: PageType,
+  page: Omit<PageContext, "pageType" | "assets" | "config">,
   depth = 0
-): Response {
+): Promise<Response> {
   const nonce = generateNonce();
   const favicon = state.docuConfig.meta?.favicon || DEFAULT_FAVICON;
-  const html = createHtmlShell({
+  const assets: AssetEntry = state.assetManifest[pageType];
+  const context: PageContext = {
+    ...page,
+    pageType,
+    assets,
+    config: state.docuConfig,
+  };
+  let html = createHtmlShell({
     title,
     description,
     body,
     favicon,
-    css: state.assetManifest.css,
-    js: state.assetManifest.js,
+    css: assets.css,
+    js: assets.js,
     nonce,
     extraScripts: hmrScript(nonce),
     themeCss: state.inlineThemeCss,
+    headExtra: state.builder?.collectHead(context),
+    bodyExtra: state.builder?.collectBody(context),
     depth,
     // 404 pages can be requested at arbitrary depths (e.g. a noLink section
     // path typed in the address bar) — relative asset paths would resolve
     // against the wrong directory and break CSS/JS.
     absoluteAssets: status === 404,
   });
+  if (state.builder) html = await state.builder.runTransformHtmlChain(html, context);
   /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */
   return htmlResponse(html, nonce, status, true);
 }
@@ -127,7 +139,7 @@ async function getDocsForSlug(
   let frontmatter = result.frontmatter as Record<string, unknown>;
   if (state.builder) {
     frontmatter = await state.builder.runTransformFrontmatterChain(frontmatter, {
-      slug: slug || "/",
+      slug,
       filePath: relPath,
       content,
     });
@@ -176,41 +188,24 @@ async function renderDocsServerPage(
   // Match build.ts depth calculation: slug.split("/").length, fallback to 1 for empty
   const depth = slug.length || 1;
 
-  if (state.builder) {
-    const ctx: PageContext = {
-      slug: slug.join("/") || "/",
+  return createHtmlResponse(
+    title,
+    description,
+    body,
+    200,
+    state,
+    "docs",
+    {
+      slug: slug.join("/"),
       filePath: doc.filePath,
       frontmatter: doc.frontmatter,
       content: doc.resolvedContent,
-      config: state.docuConfig,
-    };
-    const headExtra = state.builder.collectHead(ctx);
-    const bodyExtra = state.builder.collectBody(ctx);
-    const nonce = generateNonce();
-    const favicon = state.docuConfig.meta?.favicon || DEFAULT_FAVICON;
-    let html = createHtmlShell({
-      title,
-      description,
-      body,
-      favicon,
-      css: state.assetManifest.css,
-      js: state.assetManifest.js,
-      nonce,
-      extraScripts: hmrScript(nonce),
-      themeCss: state.inlineThemeCss,
-      headExtra,
-      bodyExtra,
-      depth,
-    });
-    html = await state.builder.runTransformHtmlChain(html, ctx);
-    /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */
-    return htmlResponse(html, nonce, 200, true);
-  }
-
-  return createHtmlResponse(title, description, body, 200, state, depth);
+    },
+    depth
+  );
 }
 
-function renderPage(
+async function renderPage(
   Component: React.ComponentType<Record<string, unknown>>,
   title: string,
   description: string,
@@ -218,14 +213,22 @@ function renderPage(
   state: ServerState,
   props: Record<string, unknown> = {},
   depth = 0
-): Response {
-  const page = React.createElement(
-    DocsLayout,
-    { repoUrl: state.docuConfig.repo?.url, pathname: "/docs" },
-    React.createElement(Component, props)
+): Promise<Response> {
+  const body = renderToString(React.createElement(Component, props));
+  return createHtmlResponse(
+    title,
+    description,
+    body,
+    status,
+    state,
+    "notFound",
+    {
+      slug: "404",
+      filePath: resolve(PAGES_DIR, "404.tsx"),
+      frontmatter: {},
+    },
+    depth
   );
-  const body = renderToString(page);
-  return createHtmlResponse(title, description, body, status, state, depth);
 }
 
 export async function handleDocsIndex(state: ServerState): Promise<Response> {
@@ -242,7 +245,7 @@ export async function handleDocsRoute(slug: string[], state: ServerState): Promi
   return renderDocsServerPage(doc, slug, `/docs/${path}`, state);
 }
 
-export function handleIndex(state: ServerState): Response {
+export async function handleIndex(state: ServerState): Promise<Response> {
   const page = React.createElement(IndexPage);
   const body = renderToString(page);
   return createHtmlResponse(
@@ -250,11 +253,17 @@ export function handleIndex(state: ServerState): Response {
     state.docuConfig.meta?.description || "",
     body,
     200,
-    state
+    state,
+    "home",
+    {
+      slug: "",
+      filePath: resolve(PAGES_DIR, "index.tsx"),
+      frontmatter: { ...state.docuConfig.meta } as Record<string, unknown>,
+    }
   );
 }
 
-export function handleNotFound(state: ServerState, depth = 0): Response {
+export async function handleNotFound(state: ServerState, depth = 0): Promise<Response> {
   return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, depth);
 }
 

package/.docu/node/server.impl.ts

@@ -63,6 +63,7 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
     for (const plugin of plugins) {
       await plugin.setup(builder);
     }
+    await builder.runOnStart();
   }
 
   const state: ServerState = {
@@ -155,6 +156,7 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
       const pluginResponse = await builder.runHandleRequest(req, {
         port: handle?.port ?? PORT,
         hostname: handle?.hostname ?? "localhost",
+        assetManifest: state.assetManifest,
       });
       if (pluginResponse) {
         const securedResponse = wrapPluginResponse(pluginResponse, true);
@@ -198,7 +200,7 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
       // Manual route matching — same routes Bun.FileSystemRouter derives
       // from `.docu/pages/` ("/", "/docs/[[...slug]]", "/404").
       if (pathname === "/") {
-        response = handleIndex(state);
+        response = await handleIndex(state);
       } else if (pathname === "/docs" || pathname === "/docs/") {
         response = await handleDocsIndex(state);
       } else if (pathname.startsWith("/docs/")) {
@@ -206,7 +208,7 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
         response =
           slug.length === 0 ? await handleDocsIndex(state) : await handleDocsRoute(slug, state);
       } else {
-        response = handleNotFound(state);
+        response = await handleNotFound(state);
       }
 
       logger.request(

package/.docu/node/server.ts

@@ -54,6 +54,7 @@ if (builder) {
   for (const plugin of plugins) {
     await plugin.setup(builder);
   }
+  await builder.runOnStart();
 }
 
 const state: ServerState = {
@@ -159,6 +160,7 @@ const server = Bun.serve({
       const pluginResponse = await builder.runHandleRequest(req, {
         port: serverPort,
         hostname: serverHostname,
+        assetManifest: state.assetManifest,
       });
       if (pluginResponse) {
         const securedResponse = wrapPluginResponse(pluginResponse, true);
@@ -200,27 +202,21 @@ const server = Bun.serve({
       const match = router?.match(pathname);
       let response: Response;
 
-      if (match) {
-        const routeName = match.name;
+      const routeName = match?.name;
 
-        if (routeName === "/docs/[[...slug]]") {
-          const slugParam = match.params?.slug;
-          const slug = slugParam ? slugParam.split("/") : [];
+      if (routeName === "/docs/[[...slug]]") {
+        const slugParam = match?.params?.slug;
+        const slug = slugParam ? slugParam.split("/") : [];
 
-          if (slug.length === 0) {
-            response = await handleDocsIndex(state);
-          } else {
-            response = await handleDocsRoute(slug, state);
-          }
-        } else if (routeName === "/404") {
-          response = handleNotFound(state);
-        } else if (routeName === "/") {
-          response = handleIndex(state);
+        if (slug.length === 0) {
+          response = await handleDocsIndex(state);
         } else {
-          response = handleNotFound(state);
+          response = await handleDocsRoute(slug, state);
         }
+      } else if (routeName === "/") {
+        response = await handleIndex(state);
       } else {
-        response = handleNotFound(state);
+        response = await handleNotFound(state);
       }
 
       logger.request(

package/.docu/node/types.ts

@@ -93,6 +93,17 @@ export interface DocuConfig {
   plugins?: PluginEntry[];
 }
 
+export interface AssetEntry {
+  css: string;
+  js?: string;
+}
+
+export interface AssetManifest {
+  docs: AssetEntry;
+  home: AssetEntry;
+  notFound: AssetEntry;
+}
+
 export interface BuildCacheEntry {
   hash: string;
   mtime: number;

package/.docu/pages/404.tsx

@@ -1,13 +1,16 @@
+import { BackgroundBlobs, Hero } from "../components/home";
+
 export default function NotFoundPage() {
   return (
-    <div className="flex w-full flex-1 px-4 py-8 lg:h-[calc(100vh-4rem)] lg:px-8 lg:py-4">
-      <div className="bg-base-100 border-base-300 flex min-h-[50vh] w-full flex-col items-center justify-center rounded-xl border shadow-md lg:min-h-0 lg:flex-1">
-        <h1 className="text-6xl font-bold">404</h1>
-        <p className="text-base-content/60 py-4 text-xl">Page not found</p>
-        <a href="/docs/" className="btn btn-primary mt-2">
-          Go to Docs
-        </a>
-      </div>
-    </div>
+    <main className="bg-base-100 relative isolate flex min-h-screen w-full items-center justify-center overflow-hidden">
+      <BackgroundBlobs />
+      <Hero
+        hero={{
+          headline: "404",
+          description: "Page not found",
+          actions: [{ text: "Go to Docs", link: "/docs/" }],
+        }}
+      />
+    </main>
   );
 }

package/.docu/pages/index.tsx

@@ -1,6 +1,7 @@
 import { loadDocuConfig } from "../node/paths";
 import { docsHtmlHref, isExternalUrl } from "../node/utils";
-import { Hero, Features } from "../components/home";
+import { Hero, Features, BackgroundBlobs } from "../components/home";
+import { ThemeToggle } from "../components/Theme";
 import type { HomeFeature } from "../node/types";
 
 const docuConfig = loadDocuConfig();
@@ -61,41 +62,19 @@ export default function IndexPage() {
 
   return (
     <div className="bg-base-100 relative isolate min-h-screen overflow-hidden">
-      <div className="absolute top-4 right-4 z-10" id="theme-island" />
-
-      {/* Background gradient blobs */}
-      <div
-        aria-hidden="true"
-        className="pointer-events-none absolute -top-40 left-1/2 -z-10 -translate-x-1/2 blur-3xl sm:-top-80"
-      >
-        <div
-          style={{
-            clipPath:
-              "polygon(74.1% 44.1%, 100% 61.6%, 97.5% 26.9%, 85.5% 0.1%, 80.7% 2%, 72.5% 32.5%, 60.2% 62.4%, 52.4% 68.1%, 47.5% 58.3%, 45.2% 34.5%, 27.5% 76.7%, 0.1% 64.9%, 17.9% 100%, 27.6% 76.8%, 76.1% 97.7%, 74.1% 44.1%)",
-          }}
-          className="from-primary to-accent h-[40rem] w-[80rem] bg-gradient-to-tr opacity-20"
-        />
+      <div className="absolute top-4 right-4 z-10">
+        <div id="theme-toggle-island">
+          <ThemeToggle />
+        </div>
       </div>
 
+      <BackgroundBlobs />
+
       {/* Hero Section */}
       <Hero hero={hero} />
 
       {/* Features Section */}
       <Features features={features} />
-
-      {/* Bottom gradient blob */}
-      <div
-        aria-hidden="true"
-        className="pointer-events-none absolute bottom-0 left-1/2 -z-10 translate-x-1/4 blur-3xl"
-      >
-        <div
-          style={{
-            clipPath:
-              "polygon(74.1% 44.1%, 100% 61.6%, 97.5% 26.9%, 85.5% 0.1%, 80.7% 2%, 72.5% 32.5%, 60.2% 62.4%, 52.4% 68.1%, 47.5% 58.3%, 45.2% 34.5%, 27.5% 76.7%, 0.1% 64.9%, 17.9% 100%, 27.6% 76.8%, 76.1% 97.7%, 74.1% 44.1%)",
-          }}
-          className="from-accent to-primary h-[30rem] w-[70rem] bg-gradient-to-tr opacity-20"
-        />
-      </div>
     </div>
   );
 }