@docubook/flame 1.7.2 → 2.0.0-alpha.1

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/html.shared.ts

@@ -34,6 +34,9 @@ export interface HtmlShellOptions {
   bodyExtra?: string[];
   /** SEO meta tags derived from config + frontmatter */
   seo?: SeoMeta;
+  /** Root-absolute asset URLs (`/assets/...`). Required for pages served at
+   * arbitrary paths (404 fallback) — relative depth is wrong there. */
+  absoluteAssets?: boolean;
 }
 
 export function htmlShell(opts: HtmlShellOptions): string {
@@ -51,14 +54,16 @@ export function htmlShell(opts: HtmlShellOptions): string {
     depth = 0,
     headExtra,
     bodyExtra,
+    absoluteAssets = false,
   } = opts;
   const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${escapeHtml(themeCss)}</style>` : "";
   const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = depthPrefix + "assets/";
-  const resolvePath = (path: string) => (path.startsWith("/") ? depthPrefix + path.slice(1) : path);
+  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const resolvePath = (path: string) =>
+    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

package/.docu/node/html.ts

@@ -16,14 +16,16 @@ export function htmlShell(opts: HtmlShellOptions): string {
     depth = 0,
     headExtra,
     bodyExtra,
+    absoluteAssets = false,
   } = opts;
   const nonceAttr = nonce ? ` nonce="${Bun.escapeHTML(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${Bun.escapeHTML(themeCss)}</style>` : "";
   const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = depthPrefix + "assets/";
-  const resolvePath = (path: string) => (path.startsWith("/") ? depthPrefix + path.slice(1) : path);
+  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const resolvePath = (path: string) =>
+    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

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);

package/.docu/node/preview.impl.ts

@@ -6,7 +6,7 @@
 import { existsSync, statSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import type { RuntimeAdapter, ServerHandle } from "@docubook/runt";
+import type { RuntimeAdapter, ServerHandle } from "./runtime";
 import { logger } from "./logger";
 import { DIST_DIR } from "./paths";
 import { getContentType } from "./utils";
@@ -63,7 +63,7 @@ export async function runPreview(adapter: RuntimeAdapter): Promise<ServerHandle
             headers: {
               "Content-Type": "text/html",
               ...SECURITY_HEADERS,
-              "Content-Security-Policy": cspHeader(nonce, true),
+              "Content-Security-Policy": cspHeader(nonce),
             },
           });
         }
@@ -81,7 +81,7 @@ export async function runPreview(adapter: RuntimeAdapter): Promise<ServerHandle
           headers: {
             "Content-Type": "text/html",
             ...SECURITY_HEADERS,
-            "Content-Security-Policy": cspHeader(nonce, true),
+            "Content-Security-Policy": cspHeader(nonce),
           },
         });
       }

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

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

package/.docu/node/preview.ts

@@ -57,7 +57,7 @@ const server = Bun.serve({
           headers: {
             "Content-Type": "text/html",
             ...SECURITY_HEADERS,
-            "Content-Security-Policy": cspHeader(nonce, true),
+            "Content-Security-Policy": cspHeader(nonce),
           },
         });
       }
@@ -75,7 +75,7 @@ const server = Bun.serve({
         headers: {
           "Content-Type": "text/html",
           ...SECURITY_HEADERS,
-          "Content-Security-Policy": cspHeader(nonce, true),
+          "Content-Security-Policy": cspHeader(nonce),
         },
       });
     }

package/.docu/node/route.ts

@@ -1,6 +1,11 @@
 import { loadDocuConfig } from "./paths";
 import type { DocuRoute } from "./types";
 import { resolveRoutes } from "./fs-scanner";
+import { DOCS_DIR } from "./paths";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractFrontmatter } from "@docubook/core";
+import type { Frontmatter } from "./mdx";
 
 const docuConfig = loadDocuConfig();
 export const routes: DocuRoute[] = resolveRoutes(docuConfig.routes);
@@ -41,8 +46,53 @@ export function getRouteMap(): Map<string, string> {
   return map;
 }
 
+/** Build-time cache of href → frontmatter description (docs content is static). */
+const descriptionCache = new Map<string, string>();
+
+function readDescription(href: string): string {
+  const cached = descriptionCache.get(href);
+  if (cached !== undefined) return cached;
+
+  let description = "";
+  const rel = href.replace(/^\/|$/g, "");
+  for (const ext of [".mdx", ".md"]) {
+    for (const file of [join(DOCS_DIR, `${rel}${ext}`), join(DOCS_DIR, `${rel}/index${ext}`)]) {
+      try {
+        const fm = extractFrontmatter<Frontmatter>(readFileSync(file, "utf-8"));
+        description = typeof fm.description === "string" ? fm.description : "";
+        if (description) break;
+      } catch {
+        // not this file — try the next candidate
+      }
+    }
+    if (description) break;
+  }
+  descriptionCache.set(href, description);
+  return description;
+}
+
 export function getPreviousNext(pathname: string) {
   const normalizedPath = pathname.replace(/^\/|$/g, "");
+
+  // Docs index (/docs — DocsPage renders with pathname "" from slug []):
+  // next-only navigation into the first docs page — never read the route
+  // backward from the index, so prev stays null even if a page sits before
+  // it in the route list.
+  if (normalizedPath === "docs" || normalizedPath === "") {
+    const paths = flattenRoutes();
+    const routeMap = getRouteMap();
+    const first = paths[0];
+    if (!first) return { prev: null, next: null };
+    return {
+      prev: null,
+      next: {
+        href: first,
+        title: routeMap.get(first) || "",
+        description: readDescription(first),
+      },
+    };
+  }
+
   const paths = flattenRoutes();
 
   const index = paths.findIndex((href) => href === `/${normalizedPath}` || href === normalizedPath);
@@ -57,7 +107,13 @@ export function getPreviousNext(pathname: string) {
 
   return {
     prev: prevHref ? { href: prevHref, title: routeMap.get(prevHref) || "" } : null,
-    next: nextHref ? { href: nextHref, title: routeMap.get(nextHref) || "" } : null,
+    next: nextHref
+      ? {
+          href: nextHref,
+          title: routeMap.get(nextHref) || "",
+          description: readDescription(nextHref),
+        }
+      : null,
   };
 }
 

package/.docu/node/runtime/bun.ts

@@ -0,0 +1,28 @@
+import type { FetchHandler, RuntimeAdapter, ServerOptions } from "./types";
+
+/** Minimal ambient view of the Bun global — only what the adapter touches. */
+declare const Bun: {
+  serve(options: { port: number; hostname?: string; idleTimeout?: number; fetch: FetchHandler }): {
+    port?: number;
+    hostname?: string;
+    stop(closeActiveConnections?: boolean): void | Promise<void>;
+  };
+};
+
+export const bunAdapter: RuntimeAdapter = {
+  name: "bun",
+
+  serve(fetch: FetchHandler, options: ServerOptions) {
+    const server = Bun.serve({
+      port: options.port,
+      hostname: options.hostname,
+      idleTimeout: options.idleTimeout,
+      fetch,
+    });
+    return {
+      port: server.port ?? options.port,
+      hostname: server.hostname ?? options.hostname ?? "localhost",
+      stop: () => server.stop(),
+    };
+  },
+};

package/.docu/node/runtime/deno.ts

@@ -0,0 +1,34 @@
+import type { FetchHandler, RuntimeAdapter, ServerOptions } from "./types";
+
+/** Minimal ambient view of the Deno global — only what the adapter touches. */
+declare const Deno: {
+  serve(
+    options: { port?: number; hostname?: string; onListen?: (addr: unknown) => void },
+    handler: (req: Request) => Response | Promise<Response>
+  ): {
+    addr: { port: number; hostname: string };
+    shutdown(): Promise<void>;
+  };
+};
+
+export const denoAdapter: RuntimeAdapter = {
+  name: "deno",
+
+  serve(fetch: FetchHandler, options: ServerOptions) {
+    const server = Deno.serve(
+      {
+        port: options.port,
+        hostname: options.hostname,
+        onListen: () => {
+          // Suppress Deno's default "Listening on ..." log; callers print their own.
+        },
+      },
+      fetch
+    );
+    return {
+      port: server.addr.port,
+      hostname: server.addr.hostname,
+      stop: () => server.shutdown(),
+    };
+  },
+};

package/.docu/node/runtime/index.ts

@@ -0,0 +1,4 @@
+export type { FetchHandler, RuntimeAdapter, ServerHandle, ServerOptions } from "./types";
+export { bunAdapter } from "./bun";
+export { denoAdapter } from "./deno";
+export { nodeAdapter } from "./node";