@docubook/flame 1.5.4 → 1.6.0

package/.docu/node/hydrate.node.ts

@@ -58,10 +58,42 @@ function resolveTailwindBin(): string {
   return join(dirname(pkgPath), binRel);
 }
 
-/** Run Tailwind CLI to produce minified CSS. */
-async function runTailwind(outputCss: string): Promise<void> {
+/** Compute a cache key from globals.css + theme config content. */
+function tailwindCacheKey(): string {
+  const globalsPath = join(STYLES_DIR, "globals.css");
+  const globalsContent = existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+  let themeSuffix = "";
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) {
+      themeSuffix = JSON.stringify(themeColors);
+    }
+  } catch {
+    // theme config unavailable — proceed without it
+  }
+  return createHash("md5")
+    .update(globalsContent + themeSuffix)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * Build Tailwind CSS with content-based caching.
+ * If a CSS file for the current input hash already exists, skip the subprocess.
+ * Returns the filename (e.g. "client-abc123.css") and CSS content.
+ */
+async function buildTailwindCss(key: string): Promise<{ file: string; content: string }> {
+  const cachedFile = `client-${key}.css`;
+  const cachedPath = join(ASSETS_DIR, cachedFile);
+
+  if (existsSync(cachedPath)) {
+    const content = readFileSync(cachedPath, "utf-8");
+    return { file: cachedFile, content };
+  }
+
+  const tmpCss = join(ASSETS_DIR, `_tmp-${key}.css`);
   const bin = resolveTailwindBin();
-  const twArgs = ["-i", join(STYLES_DIR, "globals.css"), "-o", outputCss, "--minify"];
+  const twArgs = ["-i", join(STYLES_DIR, "globals.css"), "-o", tmpCss, "--minify"];
   const isDeno = "Deno" in globalThis;
   const args = isDeno ? ["run", "-A", bin, ...twArgs] : [bin, ...twArgs];
   try {
@@ -70,6 +102,31 @@ async function runTailwind(outputCss: string): Promise<void> {
     const stderr = (err as { stderr?: string }).stderr ?? String(err);
     throw new Error(`Tailwind CSS build failed:\n${stderr}`, { cause: err });
   }
+
+  let cssContent = await readFile(tmpCss, "utf-8");
+  await unlink(tmpCss);
+
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) {
+      cssContent = buildThemeCss(cssContent, themeColors);
+    }
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to resolve theme config, falling back to globals.css only: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  // Use the same input-derived key for lookup and output — if inputs change,
+  // the key changes, cache busting works without a separate content hash.
+  const cssFile = `client-${key}.css`;
+  const outPath = join(ASSETS_DIR, cssFile);
+
+  if (!existsSync(outPath)) {
+    await writeFile(outPath, cssContent);
+  }
+
+  return { file: cssFile, content: cssContent };
 }
 
 const NODE_BUILTINS_RE = new RegExp(
@@ -111,8 +168,10 @@ function scanDirLucideIcons(dir: string, set: Set<string>): void {
         }
       }
     }
-  } catch {
-    /* skip unreadable dirs */
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to scan lucide icons: ${err instanceof Error ? err.message : String(err)}`
+    );
   }
 }
 
@@ -138,7 +197,8 @@ function collectAllLucideIcons(): string[] {
 /** Build the client JS bundle and Tailwind CSS. */
 export async function buildClientBundle(): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
-  await cleanOldBundles();
+  const twKey = tailwindCacheKey();
+  await cleanOldBundles(new Set([`client-${twKey}.css`]));
 
   const nodeEnv = process.env.NODE_ENV || "development";
   const esbuild = await import("esbuild");
@@ -153,10 +213,8 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
       bundle: true,
       outdir: ASSETS_DIR,
       entryNames: "client-[hash]",
-      chunkNames: "chunks/[name]-[hash]",
       platform: "browser",
       format: "esm",
-      splitting: true,
       minify: nodeEnv === "production",
       define: { "process.env.NODE_ENV": JSON.stringify(nodeEnv) },
       jsx: "automatic",
@@ -185,17 +243,17 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
               if (args.namespace === "lucide-virt") {
                 return { path: getLucideRealEntry(), namespace: "file" };
               }
-              // Files that do dynamic name lookups (namespace import)
-              // need the full barrel — bypass the virtual module.
+              // mdx-content 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.endsWith("/.docu/components/Lucide.tsx") ||
-                  normalized.includes("/mdx-content/dist/")
-                ) {
+                if (normalized.includes("/mdx-content/dist/")) {
                   return { path: getLucideRealEntry(), namespace: "file" };
                 }
               }
+              // All other files get tree-shaken via the virtual module.
+              // Lucide.tsx renders only config-defined icons, which are
+              // collected by extractConfigIcons() + collectAllLucideIcons().
               return { path: args.path, namespace: "lucide-virt" };
             });
             build.onLoad({ filter: /.*/, namespace: "lucide-virt" }, () => {
@@ -226,7 +284,6 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
             });
           },
         },
-
       ],
     });
   } finally {
@@ -235,10 +292,7 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
     await esbuild.stop();
   }
 
-  // With splitting enabled esbuild emits the entry plus shared/dynamic chunks.
-  // `entryPoint` is set on the user entry AND on every dynamic-import chunk
-  // (esbuild treats dynamic imports as entry points), so match the resolved
-  // source path instead of grabbing the first truthy `entryPoint`.
+  // The single entry produces one output. Match resolved source path.
   const { outputs } = result.metafile!;
   const jsOutput = Object.keys(outputs).find((p) => {
     const o = outputs[p];
@@ -249,26 +303,7 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
   }
   const jsFile = basename(jsOutput);
 
-  const tmpCss = join(ASSETS_DIR, "_tmp.css");
-  await runTailwind(tmpCss);
-
-  let cssContent = await readFile(tmpCss, "utf-8");
-
-  try {
-    const themeColors = getThemeConfig();
-    if (themeColors) {
-      cssContent = buildThemeCss(cssContent, themeColors);
-    }
-  } catch (err) {
-    console.warn(
-      `[flame] Failed to resolve theme config, falling back to globals.css only: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-
-  const cssHash = createHash("md5").update(cssContent).digest("hex").slice(0, 8);
-  const cssFile = `client-${cssHash}.css`;
-  await writeFile(join(ASSETS_DIR, cssFile), cssContent);
-  await unlink(tmpCss);
+  const { file: cssFile } = await buildTailwindCss(twKey);
 
   await writeFile(join(ASSETS_DIR, "manifest.json"), JSON.stringify({ js: jsFile, css: cssFile }));
 

package/.docu/node/hydrate.ts

@@ -1,5 +1,7 @@
 import { join } from "node:path";
 import { mkdir, unlink } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { resolveTheme, generateThemeCss, presetRegistry } from "@docubook/themes-colors";
 import { ASSETS_DIR, cleanOldBundles, LIB_DIR, STYLES_DIR, loadDocuConfig } from "./paths";
 import { resolveRoutes } from "./fs-scanner";
@@ -55,24 +57,86 @@ export function computeInlineThemeCss(): string | undefined {
   return undefined;
 }
 
+/** Compute Tailwind cache key from globals.css + theme config. */
+function twCacheKey(): string {
+  const globalsPath = join(STYLES_DIR, "globals.css");
+  const globals = existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+  let themeSuffix = "";
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) themeSuffix = JSON.stringify(themeColors);
+  } catch {
+    // theme config unavailable — proceed without
+  }
+  return createHash("md5")
+    .update(globals + themeSuffix)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/** Run Tailwind CLI, caching by content hash. */
+async function buildTailwindCss(key: string): Promise<{ file: string; content: string }> {
+  const cachedFile = `client-${key}.css`;
+  const cachedPath = join(ASSETS_DIR, cachedFile);
+
+  if (existsSync(cachedPath)) {
+    const content = await Bun.file(cachedPath).text();
+    return { file: cachedFile, content };
+  }
+
+  const tmpCss = join(ASSETS_DIR, `_tmp-${key}.css`);
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "x",
+      "@tailwindcss/cli",
+      "-i",
+      join(STYLES_DIR, "globals.css"),
+      "-o",
+      tmpCss,
+      "--minify",
+    ],
+    { stdout: "ignore", stderr: "pipe" }
+  );
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`Tailwind CSS build failed:\n${err}`);
+  }
+
+  let cssContent = await Bun.file(tmpCss).text();
+  await unlink(tmpCss);
+
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) cssContent = buildThemeCss(cssContent, themeColors);
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to resolve theme config: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  // Use the same input-derived key for lookup and output — if inputs change,
+  // the key changes, cache busting works without a separate content hash.
+  const cssFile = `client-${key}.css`;
+  const outPath = join(ASSETS_DIR, cssFile);
+  if (!existsSync(outPath)) await Bun.write(outPath, cssContent);
+
+  return { file: cssFile, content: cssContent };
+}
+
 export async function buildClientBundle(): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
-  await cleanOldBundles();
+  const twKey = twCacheKey();
+  await cleanOldBundles(new Set([`client-${twKey}.css`]));
 
   const nodeEnv = process.env.NODE_ENV || "development";
   const result = await Bun.build({
     entrypoints: [join(LIB_DIR, "client.ts")],
     outdir: ASSETS_DIR,
-    format: "esm",
-    splitting: true,
-    naming: {
-      entry: "client-[hash].[ext]",
-      chunk: "chunks/[name]-[hash].[ext]",
-      asset: "[name]-[hash].[ext]",
-    },
+    naming: "client-[hash].[ext]",
     target: "browser",
     minify: nodeEnv === "production",
-    optimizeImports: ["lucide-react"],
     define: { "process.env.NODE_ENV": JSON.stringify(nodeEnv) },
     plugins: [
       {
@@ -92,7 +156,6 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
           });
         },
       },
-
     ],
   });
 
@@ -104,50 +167,13 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
   if (!result.outputs[0]) {
     throw new Error("Client bundle produced no output files");
   }
-  // With splitting enabled Bun emits entry + chunk artifacts; select the entry
-  // explicitly rather than by position (chunks may precede it in the array).
   const entry = result.outputs.find((o) => o.kind === "entry-point");
   if (!entry) {
     throw new Error("Client bundle produced no entry-point output");
   }
   const jsFile = entry.path.split("/").pop()!;
-  const tmpCss = join(ASSETS_DIR, "_tmp.css");
-  const proc = Bun.spawn(
-    [
-      "bun",
-      "x",
-      "@tailwindcss/cli",
-      "-i",
-      join(STYLES_DIR, "globals.css"),
-      "-o",
-      tmpCss,
-      "--minify",
-    ],
-    { stdout: "ignore", stderr: "pipe" }
-  );
-  await proc.exited;
-  if (proc.exitCode !== 0) {
-    const err = await new Response(proc.stderr).text();
-    throw new Error(`Tailwind CSS build failed:\n${err}`);
-  }
 
-  let cssContent = await Bun.file(tmpCss).text();
-
-  try {
-    const themeColors = getThemeConfig();
-    if (themeColors) {
-      cssContent = buildThemeCss(cssContent, themeColors);
-    }
-  } catch (err) {
-    console.warn(
-      `[flame] Failed to resolve theme config, falling back to globals.css only: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-
-  const cssHash = new Bun.CryptoHasher("md5").update(cssContent).digest("hex").slice(0, 8);
-  const cssFile = `client-${cssHash}.css`;
-  await Bun.write(join(ASSETS_DIR, cssFile), cssContent);
-  await unlink(tmpCss);
+  const { file: cssFile } = await buildTailwindCss(twKey);
 
   await Bun.write(join(ASSETS_DIR, "manifest.json"), JSON.stringify({ js: jsFile, css: cssFile }));
 

package/.docu/node/paths.ts

@@ -32,11 +32,12 @@ export const DOCU_CONFIG_PATH = join(PROJECT_ROOT, "docu.json");
 // Config singleton
 let _config: DocuConfig | null = null;
 
-/** Clean stale client bundles and split chunks from a previous build. */
-export async function cleanOldBundles() {
+/** Clean stale client bundles from a previous build. */
+export async function cleanOldBundles(preserve?: Set<string>) {
   try {
     const files = await readdir(ASSETS_DIR);
     for (const file of files) {
+      if (preserve?.has(file)) continue;
       if (file.startsWith("client.") || file.startsWith("client-")) {
         await unlink(join(ASSETS_DIR, file));
       }
@@ -46,12 +47,13 @@ export async function cleanOldBundles() {
       console.error("Failed to clean old bundles:", (err as Error).message);
     }
   }
-  // Stale split chunks accumulate across builds (content-hashed names); drop
-  // the whole chunks dir so only the new build's chunks remain.
   try {
     await rm(join(ASSETS_DIR, "chunks"), { recursive: true, force: true });
   } catch (err) {
-    console.error("Failed to clean old chunks:", (err as Error).message);
+    // chunks dir may not exist, or permission error — log to avoid silent failure
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.warn("[flame] Failed to clean chunks dir:", (err as Error).message);
+    }
   }
 }
 

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

@@ -279,7 +279,8 @@ export function serveStatic(pathname: string): Response | null {
 
 export function serverErrorResponse(error: unknown): Response {
   const msg = error instanceof Error ? error.message : "Unknown error";
-  const st = error instanceof Error ? error.stack : undefined;
+  const st =
+    process.env.NODE_ENV !== "production" && error instanceof Error ? error.stack : undefined;
   return new Response(errorHtml(msg, st), {
     status: 500,
     headers: {

package/bin/cli.js

@@ -12,10 +12,13 @@ const __dirname = import.meta.dirname;
 // Deno's npm compat layer may expose `Bun` via globals, check execPath first.
 const runtime =
   process.env.FLAME_RUNTIME ||
-  (process.execPath.includes("deno") ? "deno" :
-   typeof Bun !== "undefined" ? "bun" :
-   typeof Deno !== "undefined" ? "deno" :
-   "node");
+  (process.execPath.includes("deno")
+    ? "deno"
+    : typeof Bun !== "undefined"
+      ? "bun"
+      : typeof Deno !== "undefined"
+        ? "deno"
+        : "node");
 
 const COMMAND_MAP = {
   bun: {
@@ -48,11 +51,15 @@ if (!COMMAND_MAP) {
 
 const command = process.argv[2];
 
-// Parse --theme flag: set env before importing build script
+// Parse flags
 const themeIndex = process.argv.indexOf("--theme");
 if (themeIndex !== -1 && themeIndex + 1 < process.argv.length) {
   process.env.FLAME_THEME = process.argv[themeIndex + 1];
 }
+const hasDocker = process.argv.includes("--docker");
+const hasSilent = process.argv.includes("--silent");
+if (hasDocker) process.env.FLAME_DEPLOY_DOCKER = "1";
+if (hasSilent) process.env.FLAME_DEPLOY_SILENT = "1";
 
 if (!command || command === "--help" || command === "-h") {
   console.log(`
@@ -71,6 +78,8 @@ if (!command || command === "--help" || command === "-h") {
   Options:
     --help        Show this help message
     --theme <name>  Override theme preset (e.g. freshlime, coffee). Works with dev, build, preview.
+    --docker      Generate Docker deployment files (Dockerfile + nginx.conf). Works with deploy.
+    --silent      Suppress non-essential output. Works with deploy.
 `);
   process.exit(0);
 }
@@ -120,11 +129,15 @@ if (command === "init") {
     }
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 
+    // Runtime detection via shebang (#!/usr/bin/env node) makes typeof Bun
+    // unavailable — check for bun.lock as a reliable Bun indicator.
+    const isBun = existsSync(join(targetDir, "bun.lock"));
+    const pkgManager = runtime === "deno" ? "deno" : isBun ? "bun" : "node";
     const nextSteps = {
       bun: "    bun install\n    bun run dev",
       node: "    npm install\n    npm run dev",
       deno: "    deno task dev\n\n  ⚠️  If you see a freshness error, run:\n    DENO_ALLOW_NEWER=true deno task dev",
-    }[runtime];
+    }[pkgManager];
     console.log(`\n  ✓ Project scaffolded!\n\n  Next steps:\n${nextSteps}\n`);
     process.exit(0);
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -55,7 +55,7 @@
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
     "@docubook/core": "^1.8.2",
-    "@docubook/mdx-content": "^3.4.4",
+    "@docubook/mdx-content": "^3.4.5",
     "@docubook/runt": "^1.0.0",
     "@docubook/themes-colors": "^1.0.2",
     "@docubook/ui-react": "^1.0.0"

package/.docu/lib/build.impl-CPFOQ7JW.js

@@ -1,12 +0,0 @@
-import {
-  runBuild,
-  runBuildCli
-} from "./chunk-NYCIAZTI.js";
-import "./chunk-C67LPMQA.js";
-import "./chunk-EOK6KATZ.js";
-import "./chunk-GXQB4ETN.js";
-import "./chunk-J5NMYSBJ.js";
-export {
-  runBuild,
-  runBuildCli
-};

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

@@ -1,79 +0,0 @@
-import {
-  DIST_DIR,
-  PROJECT_ROOT
-} from "./chunk-J5NMYSBJ.js";
-
-// .docu/node/deploy.shared.ts
-import { writeFile, mkdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-var WORKFLOW_DIR = join(PROJECT_ROOT, ".github/workflows");
-var WORKFLOW_FILE = join(WORKFLOW_DIR, "deploy.yml");
-async function runDeploy() {
-  console.log("\u{1F4E6} Building for production...\n");
-  process.env.NODE_ENV = "production";
-  const { runBuildCli } = await import("./build.impl-CPFOQ7JW.js");
-  await runBuildCli();
-  await writeFile(join(DIST_DIR, ".nojekyll"), "");
-  if (!existsSync(WORKFLOW_FILE)) {
-    await mkdir(WORKFLOW_DIR, { recursive: true });
-    await writeFile(WORKFLOW_FILE, GITHUB_ACTIONS_WORKFLOW);
-    console.log("\n\u{1F4C4} Created .github/workflows/deploy.yml");
-  }
-  console.log("\n\u2705 Ready to deploy!");
-  console.log("   Output: .docu/dist/");
-  console.log("   Push to GitHub and enable Pages (Settings \u2192 Pages \u2192 Source: GitHub Actions)");
-}
-var GITHUB_ACTIONS_WORKFLOW = `name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - run: npm install
-
-      - run: npm run build
-
-      - name: Add .nojekyll
-        run: touch .docu/dist/.nojekyll
-
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: .docu/dist
-
-  deploy:
-    environment:
-      name: github-pages
-      url: \${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
-`;
-
-export {
-  runDeploy
-};