@docubook/flame 1.7.2 → 2.0.0-alpha.0

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/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";

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

@@ -0,0 +1,107 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { FetchHandler, RuntimeAdapter, ServerHandle, ServerOptions } from "./types";
+
+function toWebRequest(req: IncomingMessage, port: number, hostname: string): Request {
+  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 === undefined) 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 as unknown as BodyInit) : undefined,
+    // @ts-expect-error -- required by undici for streaming request bodies
+    duplex: hasBody ? "half" : undefined,
+  });
+}
+
+async function writeResponse(response: Response, res: ServerResponse): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  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;
+
+  // Flush headers immediately so streaming responses (SSE) reach the client
+  // before the first body chunk.
+  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;
+      // Incremental piping — never buffer the full body (SSE streams forever).
+      const ok = res.write(value);
+      if (!ok) await new Promise<void>((resolve) => res.once("drain", resolve));
+    }
+    res.end();
+  } catch {
+    // Client disconnected mid-stream; cancel the source.
+    await reader.cancel().catch(() => {});
+    res.destroy();
+  }
+}
+
+export const nodeAdapter: RuntimeAdapter = {
+  name: "node",
+
+  serve(fetch: FetchHandler, options: ServerOptions): Promise<ServerHandle> {
+    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 !== undefined) {
+      server.timeout = options.idleTimeout * 1000;
+      // keepAliveTimeout must not undercut idleTimeout or Node closes
+      // long-lived SSE connections early.
+      server.keepAliveTimeout = options.idleTimeout * 1000;
+    }
+
+    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<void>((res2, rej2) => {
+              server.closeAllConnections?.();
+              server.close((err) => (err ? rej2(err) : res2()));
+            }),
+        });
+      });
+    });
+  },
+};

package/.docu/node/runtime/types.ts

@@ -0,0 +1,19 @@
+export interface ServerOptions {
+  port: number;
+  hostname?: string;
+  /** Seconds a connection may stay idle before being closed. */
+  idleTimeout?: number;
+}
+
+export interface ServerHandle {
+  port: number;
+  hostname: string;
+  stop(): void | Promise<void>;
+}
+
+export type FetchHandler = (req: Request) => Response | Promise<Response>;
+
+export interface RuntimeAdapter {
+  name: string;
+  serve(fetch: FetchHandler, options: ServerOptions): ServerHandle | Promise<ServerHandle>;
+}

package/.docu/node/search-indexer.ts

@@ -14,6 +14,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { extractFrontmatterWithContent } from "@docubook/core";
+import { frontmatterField } from "./mdx";
 import { DOCS_DIR, ASSETS_DIR, loadDocuConfig } from "./paths";
 import { scanMdxFiles, docsHtmlHref } from "./utils";
 
@@ -74,7 +75,7 @@ export function extractRecords(filePath: string, raw: string): SearchRecord[] {
   const records: SearchRecord[] = [];
   const url = docsHtmlHref(`/docs/${filePath}`);
   const lvl0 = getSectionTitle(filePath);
-  const lvl1 = frontmatter.title || null;
+  const lvl1 = frontmatterField(frontmatter, "title") || null;
 
   const hierarchy = {
     lvl0,
@@ -90,7 +91,7 @@ export function extractRecords(filePath: string, raw: string): SearchRecord[] {
     records.push({
       url,
       hierarchy: { ...hierarchy },
-      content: frontmatter.description || null,
+      content: frontmatterField(frontmatter, "description") || null,
       type: "lvl1",
     });
   }

package/.docu/node/seo.ts

@@ -1,4 +1,5 @@
 import type { DocuConfig } from "./types";
+import { frontmatterField } from "./mdx";
 
 export interface SeoMeta {
   /** Absolute canonical URL */
@@ -27,8 +28,7 @@ export function buildSeoMeta(
   };
 
   // Per-page image from frontmatter, fallback to global default from config
-  const image =
-    (typeof frontmatter.image === "string" && frontmatter.image) || config.meta?.ogImage;
+  const image = frontmatterField(frontmatter, "image") || config.meta?.ogImage;
   if (image) {
     // Resolve using URL constructor — handles absolute, root-relative, and relative paths
     try {

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

@@ -1,9 +1,9 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { readFileSync, statSync } from "node:fs";
 import React, { type ReactNode } from "react";
 import { renderToString } from "react-dom/server";
-import { compileMdx } from "./mdx";
+import { compileMdx, frontmatterField } from "./mdx";
 import { getContentType } from "./utils";
 import { DOCS_DIR, DIST_DIR, PROJECT_ROOT } from "./paths";
 import { BuildPluginBuilder } from "./plugin-builder";
@@ -45,10 +45,20 @@ function createHtmlResponse(
     themeCss: state.inlineThemeCss,
     depth,
   });
-  /** unsafe-eval required by mdx-remote hydration — see build.impl.ts */
+  /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */
   return htmlResponse(html, nonce, status, true);
 }
 
+// Dev-only memo: compileMdx per request is ~70ms; repeat navigations with
+// an unchanged file (same mtime) reuse the compiled result. The dev server
+// has no other per-page cache — without this every navigation re-parses MDX.
+// ponytail: unbounded Map is fine — docs sites have a handful of pages; cap
+// with an LRU only if a project exceeds thousands of routes.
+const docsCache = new Map<
+  string,
+  { mtimeMs: number; doc: NonNullable<Awaited<ReturnType<typeof getDocsForSlug>>> }
+>();
+
 async function getDocsForSlug(
   slug: string,
   state: ServerState
@@ -92,6 +102,12 @@ async function getDocsForSlug(
 
   const relPath = filePath.replace(PROJECT_ROOT + "/", "");
 
+  const mtimeMs = (await stat(filePath)).mtimeMs;
+  const cached = docsCache.get(relPath);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.doc;
+  }
+
   let content = raw;
   if (state.builder) {
     const transformed = await state.builder.runOnLoad(relPath, content);
@@ -113,7 +129,7 @@ async function getDocsForSlug(
     });
   }
 
-  return {
+  const doc = {
     content: result.content,
     compiledSource: result.compiledSource,
     frontmatter,
@@ -121,6 +137,8 @@ async function getDocsForSlug(
     filePath: relPath,
     resolvedContent: content,
   };
+  docsCache.set(relPath, { mtimeMs, doc });
+  return doc;
 }
 
 async function renderDocsServerPage(
@@ -129,12 +147,8 @@ async function renderDocsServerPage(
   pathname: string,
   state: ServerState
 ): Promise<Response> {
-  const title =
-    (typeof doc.frontmatter.title === "string" ? doc.frontmatter.title : "") ||
-    slug.join("/") ||
-    "Docs";
-  const description =
-    typeof doc.frontmatter.description === "string" ? doc.frontmatter.description : "";
+  const title = frontmatterField(doc.frontmatter, "title") || slug.join("/") || "Docs";
+  const description = frontmatterField(doc.frontmatter, "description");
 
   const page = React.createElement(
     DocsLayout,
@@ -143,8 +157,9 @@ async function renderDocsServerPage(
       slug,
       title,
       description,
-      date: doc.frontmatter.date as string | undefined,
-      content: doc.content,
+      date: frontmatterField(doc.frontmatter, "date") || undefined,
+      // Same root-relative SSR as build — see build.ts.
+      content: renderToString(doc.content),
       tocs: doc.tocs,
       filePath: doc.filePath,
       repoUrl: state.docuConfig.repo?.url,
@@ -184,7 +199,7 @@ async function renderDocsServerPage(
       depth,
     });
     html = await state.builder.runTransformHtmlChain(html, ctx);
-    /** unsafe-eval required by mdx-remote hydration — see build.impl.ts */
+    /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */
     return htmlResponse(html, nonce, 200, true);
   }
 

package/.docu/node/server.deno.ts

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

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

@@ -1,12 +1,14 @@
 /**
  * Runtime-neutral dev server — mirror of `server.ts` (Bun-only, protected)
- * driven by a `RuntimeAdapter` from `@docubook/runt` instead of `Bun.serve`,
+ * driven by a `RuntimeAdapter` (./runtime) instead of `Bun.serve`,
  * with manual route matching instead of `Bun.FileSystemRouter`. The page set
  * is static (`/`, `/docs/[[...slug]]`, `/404`), so a router is unnecessary.
  */
 
-import { watch } from "node:fs";
-import type { RuntimeAdapter, ServerHandle } from "@docubook/runt";
+import { watch, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import type { RuntimeAdapter, ServerHandle } from "./runtime";
 import { DOCS_DIR, loadDocuConfig } from "./paths";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
@@ -72,6 +74,18 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
 
   const hmrClients = new Set<ReadableStreamDefaultController>();
 
+  const require = createRequire(import.meta.url);
+  /** Locate the installed @docubook/markdown source dir (workspace link), if any. */
+  function resolveMdxContentSrc(): string | null {
+    try {
+      const pkgDir = dirname(require.resolve("@docubook/markdown/package.json"));
+      const src = join(pkgDir, "src");
+      return existsSync(src) ? src : null;
+    } catch {
+      return null;
+    }
+  }
+
   let hmrTimeout: ReturnType<typeof setTimeout> | null = null;
   const watcher = watch(DOCS_DIR, { recursive: true }, (_event, filename) => {
     if (!filename || (!filename.endsWith(".mdx") && !filename.endsWith(".md"))) return;
@@ -87,12 +101,44 @@ export async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle>
     }, 300);
   });
 
+  // Rebuild the client bundle when component sources change (e.g. the
+  // @docubook/markdown workspace package) so interactive islands pick up
+  // edits, then reload connected clients. MDX edits are handled by the watcher
+  // above — no rebuild needed, content recompiles per request.
+  let srcHmrTimeout: ReturnType<typeof setTimeout> | null = null;
+  const mdxContentSrc = resolveMdxContentSrc();
+  const srcWatcher = mdxContentSrc
+    ? watch(mdxContentSrc, { recursive: true }, (_event, filename) => {
+        if (!filename || !/\.(ts|tsx|js|jsx|css)$/.test(filename)) return;
+        if (srcHmrTimeout) clearTimeout(srcHmrTimeout);
+        srcHmrTimeout = setTimeout(async () => {
+          try {
+            state.assetManifest = await buildClientBundle();
+            logger.warn("[hmr] client bundle rebuilt (component change)");
+          } catch (e) {
+            logger.warn(
+              `[hmr] bundle rebuild failed: ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
+          for (const client of [...hmrClients]) {
+            try {
+              client.enqueue(new TextEncoder().encode("data: reload\n\n"));
+            } catch {
+              hmrClients.delete(client);
+            }
+          }
+        }, 300);
+      })
+    : null;
+
   process.on("SIGINT", () => {
     watcher.close();
+    srcWatcher?.close();
     process.exit(0);
   });
   process.on("SIGTERM", () => {
     watcher.close();
+    srcWatcher?.close();
     process.exit(0);
   });
 

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

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

package/.docu/node/server.ts

@@ -1,4 +1,6 @@
-import { watch } from "node:fs";
+import { watch, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
 import { DOCS_DIR, PAGES_DIR, loadDocuConfig } from "./paths";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
@@ -73,6 +75,18 @@ try {
 
 const hmrClients = new Set<ReadableStreamDefaultController>();
 
+const require = createRequire(import.meta.url);
+/** Locate the installed @docubook/markdown source dir (workspace link), if any. */
+function resolveMdxContentSrc(): string | null {
+  try {
+    const pkgDir = dirname(require.resolve("@docubook/markdown/package.json"));
+    const src = join(pkgDir, "src");
+    return existsSync(src) ? src : null;
+  } catch {
+    return null;
+  }
+}
+
 let hmrTimeout: ReturnType<typeof setTimeout> | null = null;
 const watcher = watch(DOCS_DIR, { recursive: true }, (_event, filename) => {
   if (!filename || (!filename.endsWith(".mdx") && !filename.endsWith(".md"))) return;
@@ -88,12 +102,42 @@ const watcher = watch(DOCS_DIR, { recursive: true }, (_event, filename) => {
   }, 300);
 });
 
+// Rebuild the client bundle when component sources change (e.g. the
+// @docubook/markdown workspace package) so interactive islands pick up
+// edits, then reload connected clients. MDX edits are handled by the watcher
+// above — no rebuild needed, content recompiles per request.
+let srcHmrTimeout: ReturnType<typeof setTimeout> | null = null;
+const mdxContentSrc = resolveMdxContentSrc();
+const srcWatcher = mdxContentSrc
+  ? watch(mdxContentSrc, { recursive: true }, (_event, filename) => {
+      if (!filename || !/\.(ts|tsx|js|jsx|css)$/.test(filename)) return;
+      if (srcHmrTimeout) clearTimeout(srcHmrTimeout);
+      srcHmrTimeout = setTimeout(async () => {
+        try {
+          state.assetManifest = await buildClientBundle();
+          logger.warn("[hmr] client bundle rebuilt (component change)");
+        } catch (e) {
+          logger.warn(`[hmr] bundle rebuild failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        for (const client of [...hmrClients]) {
+          try {
+            client.enqueue(new TextEncoder().encode("data: reload\n\n"));
+          } catch {
+            hmrClients.delete(client);
+          }
+        }
+      }, 300);
+    })
+  : null;
+
 process.on("SIGINT", () => {
   watcher.close();
+  srcWatcher?.close();
   process.exit(0);
 });
 process.on("SIGTERM", () => {
   watcher.close();
+  srcWatcher?.close();
   process.exit(0);
 });
 

package/.docu/pages/docs/[[...slug]].tsx

@@ -1,4 +1,3 @@
-import type { ReactNode } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import DocsBreadcrumb from "../../components/Breadcrumb";
 import Pagination from "../../components/Pagination";
@@ -14,10 +13,15 @@ interface DocsPageProps {
   title: string;
   description?: string;
   date?: string;
-  content: ReactNode;
+  /** SSR'd MDX content HTML — rendered as its own root so client hydration
+   * (separate island root) matches useId-based ids. */
+  content: string;
   tocs: TocItem[];
   filePath: string;
   repoUrl?: string;
+  /** Build-time slug keying into the bundled mdxModules manifest (client.ts). */
+  mdxSlug?: string;
+  /** Dev-only pre-compiled source for the legacy MDXRemote eval path. */
   compiledSource?: string;
 }
 
@@ -30,6 +34,7 @@ export default function DocsPage({
   tocs,
   filePath,
   repoUrl,
+  mdxSlug,
   compiledSource,
 }: DocsPageProps) {
   const pathname = slug.join("/");
@@ -39,7 +44,7 @@ export default function DocsPage({
     <div className="flex w-full flex-1 px-0 pb-4 lg:h-[calc(100vh-4rem)] lg:px-8 lg:pb-8">
       <div
         id="scroll-container"
-        className="bg-base-100 border-base-300 max-lg:scroll-p-54 relative flex w-full flex-col items-start rounded-b-3xl border shadow-md lg:h-full lg:flex-row lg:overflow-y-auto lg:rounded-xl"
+        className="bg-base-100 border-base-300 relative flex w-full flex-col items-start rounded-b-3xl border shadow-md max-lg:scroll-p-54 lg:h-full lg:flex-row lg:overflow-y-auto lg:rounded-xl"
       >
         {/* Mobile bar - island */}
         <div
@@ -60,7 +65,11 @@ export default function DocsPage({
               {description && (
                 <p className="text-muted-foreground -mt-4 text-[16.5px]">{description}</p>
               )}
-              <div id="mdx-content-island">{content}</div>
+              <div
+                id="mdx-content-island"
+                data-mdx-slug={mdxSlug}
+                dangerouslySetInnerHTML={{ __html: content }}
+              />
               {compiledSource && (
                 <script
                   id="mdx-compiled-source"

package/.docu/pages/index.tsx

@@ -61,7 +61,7 @@ export default function IndexPage() {
 
   return (
     <div className="bg-base-100 relative isolate min-h-screen overflow-hidden">
-      <div className="absolute right-4 top-4 z-10" id="theme-island" />
+      <div className="absolute top-4 right-4 z-10" id="theme-island" />
 
       {/* Background gradient blobs */}
       <div