npm - @docubook/flame - Versions diffs - 1.1.0 → 1.2.1 - Mend

@docubook/flame 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/.docu/node/build.ts CHANGED Viewed

@@ -16,7 +16,7 @@ import {
 } from "./paths";
 import { htmlShell as createHtmlShell } from "./html";
 import { generateSearchIndex } from "./search-indexer";
-import { buildClientBundle } from "./hydrate";
+import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
 import type { BuildCache, CliArgs } from "./types";
@@ -95,6 +95,8 @@ export function shouldRebuild(path: string, mtime: number, cache: BuildCache): b
 let assetManifest = { js: "client.js", css: "client.css" };
+let inlineThemeCss: string | undefined;
 function htmlShell(title: string, description: string, body: string): string {
   const favicon = docuConfig.meta?.favicon || "/favicon.ico";
   return createHtmlShell({
@@ -104,6 +106,7 @@ function htmlShell(title: string, description: string, body: string): string {
     favicon,
     css: assetManifest.css,
     js: assetManifest.js,
+    themeCss: inlineThemeCss,
   });
 }
@@ -189,6 +192,8 @@ async function build() {
   assetManifest = await buildClientBundle();
   logger.bundleDone(Math.round(performance.now() - t));
+  inlineThemeCss = computeInlineThemeCss();
   const lastManifest = cache["__assets__"];
   const assetsChanged =
     !lastManifest || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;

package/.docu/node/html.ts CHANGED Viewed

@@ -7,11 +7,13 @@ export interface HtmlShellOptions {
   js: string;
   nonce?: string;
   extraScripts?: string;
+  themeCss?: string;
 }
 export function htmlShell(opts: HtmlShellOptions): string {
-  const { title, description, body, favicon, css, js, nonce, extraScripts } = opts;
+  const { title, description, body, favicon, css, js, nonce, extraScripts, themeCss } = opts;
   const nonceAttr = nonce ? ` nonce="${Bun.escapeHTML(nonce)}"` : "";
+  const themeStyle = themeCss ? `\n  <style${nonceAttr}>${Bun.escapeHTML(themeCss)}</style>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -19,7 +21,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${Bun.escapeHTML(title)}</title>
   <meta name="description" content="${Bun.escapeHTML(description)}">
-  <link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(favicon)}">
+  <link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(favicon)}">${themeStyle}
   <link rel="stylesheet" href="/assets/${Bun.escapeHTML(css)}">
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>
 </head>

package/.docu/node/hydrate.ts CHANGED Viewed

@@ -1,8 +1,12 @@
 import { join } from "node:path";
 import { mkdir, readdir, unlink } from "node:fs/promises";
+import { resolveTheme, generateThemeCss, presetRegistry } from "@docubook/themes-colors";
 import { ASSETS_DIR, LIB_DIR, STYLES_DIR, loadDocuConfig } from "./paths";
 import { resolveRoutes } from "./fs-scanner";
 import type { DocuRoute } from "./types";
+import type { ThemeConfig } from "@docubook/themes-colors";
+const themeRegistry = presetRegistry;
 async function cleanOldBundles() {
   try {
@@ -19,6 +23,53 @@ async function cleanOldBundles() {
   }
 }
+/**
+ * Read the effective theme config with this priority:
+ * 1. FLAME_THEME env var (CLI --theme flag)
+ * 2. docu.json theme.colors field
+ */
+export function getThemeConfig(): ThemeConfig | undefined {
+  if (process.env.FLAME_THEME) {
+    return process.env.FLAME_THEME;
+  }
+  const config = loadDocuConfig();
+  return config.themes?.colors;
+}
+/**
+ * Append theme CSS to compiled Tailwind output based on theme config.
+ */
+export function buildThemeCss(baseCss: string, themeConfig: unknown): string {
+  try {
+    const resolved = resolveTheme(themeConfig as ThemeConfig | undefined | null, themeRegistry);
+    return baseCss + "\n" + generateThemeCss(resolved);
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to resolve theme CSS: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return baseCss;
+  }
+}
+/**
+ * Compute inline theme CSS for FOUC prevention.
+ * Returns undefined if no theme is configured or on error.
+ */
+export function computeInlineThemeCss(): string | undefined {
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) {
+      const resolved = resolveTheme(themeColors, themeRegistry);
+      return generateThemeCss(resolved);
+    }
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to compute inline theme CSS: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return undefined;
+}
 export async function buildClientBundle(): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
   await cleanOldBundles();
@@ -93,7 +144,20 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
     const err = await new Response(proc.stderr).text();
     throw new Error(`Tailwind CSS build failed:\n${err}`);
   }
-  const cssContent = await Bun.file(tmpCss).arrayBuffer();
+  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);

package/.docu/node/preview.ts CHANGED Viewed

@@ -3,19 +3,10 @@ import { resolve } from "node:path";
 import { logger } from "./logger";
 import { DIST_DIR } from "./paths";
 import { getContentType } from "./utils";
+import { SECURITY_HEADERS, generateNonce, cspHeader, injectNonce } from "./security";
 const PORT = process.env.PORT || "4173";
-const SECURITY_HEADERS: Record<string, string> = {
-  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
-  "X-Frame-Options": "DENY",
-  "X-Content-Type-Options": "nosniff",
-  "Referrer-Policy": "strict-origin-when-cross-origin",
-  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
-  "Content-Security-Policy":
-    "default-src 'self'; script-src 'self' 'sha256-4XrQ+xtH2goQdpEv7dRmUWACF3uhF9KRPpgayFex7QU=' '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'",
-};
 logger.buildStart();
 if (!existsSync(DIST_DIR)) {
@@ -50,22 +41,42 @@ const notFoundPath = resolve(DIST_DIR, "404.html");
 const server = Bun.serve({
   port: PORT,
-  fetch(req) {
+  async fetch(req) {
     const url = new URL(req.url);
     const pathname = decodeURIComponent(url.pathname);
     const filePath = resolveFile(pathname);
     if (filePath) {
       const contentType = getContentType(filePath);
-      const headers: Record<string, string> = { "Content-Type": contentType };
-      if (contentType === "text/html") Object.assign(headers, SECURITY_HEADERS);
-      return new Response(Bun.file(filePath), { headers });
+      if (contentType === "text/html") {
+        const nonce = generateNonce();
+        const html = await Bun.file(filePath).text();
+        const modified = injectNonce(html, nonce);
+        return new Response(modified, {
+          headers: {
+            "Content-Type": "text/html",
+            ...SECURITY_HEADERS,
+            "Content-Security-Policy": cspHeader(nonce, true),
+          },
+        });
+      }
+      return new Response(Bun.file(filePath), {
+        headers: { "Content-Type": contentType },
+      });
     }
     if (existsSync(notFoundPath)) {
-      return new Response(Bun.file(notFoundPath), {
+      const nonce = generateNonce();
+      const html = await Bun.file(notFoundPath).text();
+      const modified = injectNonce(html, nonce);
+      return new Response(modified, {
         status: 404,
-        headers: { "Content-Type": "text/html", ...SECURITY_HEADERS },
+        headers: {
+          "Content-Type": "text/html",
+          ...SECURITY_HEADERS,
+          "Content-Security-Policy": cspHeader(nonce, true),
+        },
       });
     }

package/.docu/node/security.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { resolve } from "node:path";
 export const SECURITY_HEADERS: Record<string, string> = {
   "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
   "X-Frame-Options": "DENY",
@@ -10,10 +12,13 @@ export function generateNonce(): string {
   return crypto.randomUUID();
 }
-export function cspHeader(nonce: string): string {
+export function cspHeader(nonce: string, allowEval = false): string {
+  const scriptSrc = allowEval
+    ? `script-src 'self' 'nonce-${nonce}' 'unsafe-eval'`
+    : `script-src 'self' 'nonce-${nonce}'`;
   return [
     "default-src 'self'",
-    `script-src 'self' 'nonce-${nonce}' 'unsafe-eval'`,
+    scriptSrc,
     "style-src 'self' 'unsafe-inline'",
     "img-src 'self' https: data:",
     "font-src 'self' data:",
@@ -23,13 +28,38 @@ export function cspHeader(nonce: string): string {
   ].join("; ");
 }
-export function htmlResponse(html: string, nonce: string, status = 200): Response {
+export function isPathSafe(pathname: string, baseDir: string): boolean {
+  const decoded = decodeURIComponent(pathname);
+  const resolved = resolve(baseDir, decoded.slice(1));
+  const baseDirSlash = baseDir.endsWith("/") ? baseDir : baseDir + "/";
+  return resolved === baseDir || resolved.startsWith(baseDirSlash);
+}
+export function isSlugSafe(slug: string, docsDir: string): boolean {
+  const resolved = resolve(docsDir, slug);
+  const docsDirSlash = docsDir.endsWith("/") ? docsDir : docsDir + "/";
+  return resolved === docsDir || resolved.startsWith(docsDirSlash);
+}
+export function injectNonce(html: string, nonce: string): string {
+  return html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
+    if (/nonce\s*=/i.test(match)) return match;
+    return match.replace(/>$/, ` nonce="${nonce}">`);
+  });
+}
+export function htmlResponse(
+  html: string,
+  nonce: string,
+  status = 200,
+  allowEval = false
+): Response {
   return new Response(html, {
     status,
     headers: {
       "Content-Type": "text/html",
       ...SECURITY_HEADERS,
-      "Content-Security-Policy": cspHeader(nonce),
+      "Content-Security-Policy": cspHeader(nonce, allowEval),
     },
   });
 }

package/.docu/node/server.ts CHANGED Viewed

@@ -11,11 +11,11 @@ import DocsPage from "../pages/docs/[[...slug]]";
 import NotFoundPage from "../pages/404";
 import IndexPage from "../pages/index";
 import { DocsLayout } from "../components/DocsLayout";
-import { buildClientBundle } from "./hydrate";
+import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { generateSearchIndex } from "./search-indexer";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
-import { SECURITY_HEADERS, generateNonce, htmlResponse } from "./security";
+import { SECURITY_HEADERS, generateNonce, isPathSafe, isSlugSafe, htmlResponse } from "./security";
 import { htmlShell as createHtmlShell, hmrScript } from "./html";
 const docuConfig = loadDocuConfig();
@@ -31,6 +31,8 @@ let t = performance.now();
 const assetManifest = await buildClientBundle();
 logger.bundleDone(Math.round(performance.now() - t));
+const inlineThemeCss = computeInlineThemeCss();
 logger.indexStart();
 t = performance.now();
 const records = await generateSearchIndex();
@@ -91,13 +93,13 @@ function createHtmlResponse(
     js: assetManifest.js,
     nonce,
     extraScripts: hmrScript(nonce),
+    themeCss: inlineThemeCss,
   });
-  return htmlResponse(html, nonce, status);
+  return htmlResponse(html, nonce, status, process.env.NODE_ENV !== "production");
 }
 async function getDocsForSlug(slug: string) {
-  const resolved = resolve(DOCS_DIR, slug);
-  if (!resolved.startsWith(DOCS_DIR)) return null;
+  if (!isSlugSafe(slug, DOCS_DIR)) return null;
   const paths = [
     join(DOCS_DIR, slug, "index.mdx"),
@@ -215,9 +217,9 @@ function handleIndex(): Response {
 }
 function serveStatic(pathname: string): Response | null {
+  if (!isPathSafe(pathname, DIST_DIR)) return null;
   const decoded = decodeURIComponent(pathname);
   const assetPath = resolve(DIST_DIR, decoded.slice(1));
-  if (!assetPath.startsWith(DIST_DIR)) return null;
   try {
     const s = statSync(assetPath);
     if (s.isFile()) {
@@ -231,7 +233,9 @@ function serveStatic(pathname: string): Response | null {
   if (decoded.startsWith("/docs/assets/")) {
     const docsAsset = resolve(DOCS_DIR, "assets", decoded.replace("/docs/assets/", ""));
-    if (!docsAsset.startsWith(resolve(DOCS_DIR, "assets"))) return null;
+    const docsAssetsDir = resolve(DOCS_DIR, "assets");
+    const docsAssetsDirSlash = docsAssetsDir.endsWith("/") ? docsAssetsDir : docsAssetsDir + "/";
+    if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirSlash)) return null;
     try {
       const s = statSync(docsAsset);
       if (s.isFile()) {

package/.docu/node/types.ts CHANGED Viewed

@@ -66,6 +66,8 @@ export interface HomeConfig {
   features?: HomeFeature[];
 }
+import type { ThemeConfig } from "@docubook/themes-colors";
 export interface DocuConfig {
   meta: DocuMeta;
   home?: HomeConfig;
@@ -73,6 +75,9 @@ export interface DocuConfig {
   footer: DocuFooter;
   repo: RepoConfig;
   routes: DocuRoute[];
+  themes?: {
+    colors: ThemeConfig;
+  };
 }
 export interface BuildCache {

package/README.md CHANGED Viewed

@@ -124,6 +124,94 @@ The `home` section configures your landing page with a hero section and feature
 | `hero.actions`     | Array of CTA buttons with `text`, `link`, `theme`, `icon` |
 | `features`         | Array of feature cards with `icon`, `title`, `description`, `link`  |
+### Theme Colors
+Flame uses `@docubook/themes-colors` for its config-driven color system. Configure via `docu.json`:
+```json
+{
+  "themes": {
+    "colors": "default"
+  }
+}
+```
+#### Preset Themes
+Use a preset name as a string. Three built-in presets are available:
+|     Name      |    Description    |  Hue   |
+| ------------- | ----------------- | ------ |
+| `"default"`   | Modern Blue theme | ~210   |
+| `"freshlime"` | Fresh Lime theme  | ~85    |
+| `"coffee"`    | Rich Coffee theme | ~25–35 |
+```json
+{
+  "themes": {
+    "colors": "freshlime"
+  }
+}
+```
+#### Custom Hex Colors
+Define a custom primary color as a hex value. The full 24-variable palette is auto-generated from it:
+```json
+{
+  "themes": {
+    "colors": {
+      "primary": "#FF5733"
+    }
+  }
+}
+```
+| Property  |      Type      | Required |                            Description                            |
+| --------- | -------------- | -------- | ----------------------------------------------------------------- |
+| `primary` | `string` (hex) | ✅ Yes    | Primary brand color. A full light + dark scale is auto-generated. |
+##### What gets auto-generated from `primary`
+A single hex color generates **24 CSS variables × 2 modes** (light `:root` + dark `.dark`) plus **12 syntax highlighting tokens × 2 modes** — all derived from the primary color.
+|                    Token                     |        Description         |
+| -------------------------------------------- | -------------------------- |
+| `--background` / `--foreground`              | Page background & text     |
+| `--card` / `--card-foreground`               | Card surface & text        |
+| `--popover` / `--popover-foreground`         | Popover surface & text     |
+| `--primary` / `--primary-foreground`         | Primary brand color & text |
+| `--secondary` / `--secondary-foreground`     | Secondary color & text     |
+| `--muted` / `--muted-foreground`             | Muted surface & text       |
+| `--accent` / `--accent-foreground`           | Accent color & text        |
+| `--destructive` / `--destructive-foreground` | Destructive action & text  |
+| `--border`                                   | Border color               |
+| `--input`                                    | Input field border         |
+| `--ring`                                     | Focus ring color           |
+| `--radius`                                   | Border radius value        |
+| `--base-100` / `--base-200` / `--base-300`   | DaisyUI surface layers     |
+| `--base-content`                             | DaisyUI content color      |
+#### CLI Override
+Override any theme without editing `docu.json`:
+```bash
+flame dev --theme freshlime
+flame build --theme coffee
+flame preview --theme default
+```
+#### Priority
+Theme resolution follows this order (first match wins):
+1. `--theme` CLI flag (e.g., `flame dev --theme coffee`)
+2. `docu.json` → `themes.colors`
+3. Falls back to `default` preset
+---
 ### Routes
 When `routes` is an empty array `[]`, Flame automatically scans your `docs/` folder at build-time and generates the sidebar navigation from the directory structure. Folders become collapsible sections, and `.mdx`/`.md` files become links — sorted alphabetically.
@@ -249,6 +337,11 @@ Copy `.env.example` to `.env` to customize:
 # Server port (default: 3000)
 PORT=3000
+# Theme preset (optional — overrides docu.json themes.colors)
+# FLAME_THEME=default
+# FLAME_THEME=freshlime
+# FLAME_THEME=coffee
 # Error Monitoring (optional)
 SENTRY_DSN=https://your-dsn@sentry.io/project-id
 ```

package/bin/cli.js CHANGED Viewed

@@ -16,6 +16,12 @@ const COMMAND_MAP = {
 const command = process.argv[2];
+// Parse --theme flag: set env before importing build script
+const themeIndex = process.argv.indexOf("--theme");
+if (themeIndex !== -1 && themeIndex + 1 < process.argv.length) {
+  process.env.FLAME_THEME = process.argv[themeIndex + 1];
+}
 if (!command || command === "--help" || command === "-h") {
   console.log(`
   @docubook/flame — A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.
@@ -31,7 +37,8 @@ if (!command || command === "--help" || command === "-h") {
     init      Scaffold a new project in current directory
   Options:
-    --help    Show this help message
+    --help        Show this help message
+    --theme <name>  Override theme preset (e.g. freshlime, coffee). Works with dev, build, preview.
 `);
   process.exit(0);
 }

package/docu.schema.json CHANGED Viewed

@@ -117,6 +117,35 @@
       "type": "array",
       "description": "Documentation navigation routes. Leave empty for auto-detection from docs/ folder.",
       "items": { "$ref": "#/$defs/route" }
+    },
+    "themes": {
+      "type": "object",
+      "description": "Color themes configuration. Use preset name or custom hex values.",
+      "additionalProperties": false,
+      "properties": {
+        "colors": {
+          "description": "Theme colors — preset name (e.g. \"default\", \"freshlime\", \"coffee\") or custom hex object",
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": ["default", "freshlime", "coffee"]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "primary": {
+                  "type": "string",
+                  "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+                  "description": "Primary brand color in hex format"
+                }
+              },
+              "required": ["primary"]
+            }
+          ]
+        }
+      },
+      "required": ["colors"]
     }
   },
   "$defs": {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -51,9 +51,10 @@
     "lucide-react": "^1.14.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@docubook/ui-react": "^0.1.3",
     "@docubook/mdx-content": "^3.2.1",
-    "@docubook/core": "^1.7.0"
+    "@docubook/core": "^1.7.0",
+    "@docubook/themes-colors": "^0.10.1",
+    "@docubook/ui-react": "^0.1.3"
   },
   "peerDependencies": {
     "@sentry/bun": "^9.0.0"

package/template/.env.example CHANGED Viewed

@@ -1,5 +1,10 @@
 # Server
 PORT=3000
+# Theme (optional — overrides docu.json themes.colors)
+# FLAME_THEME=default
+# FLAME_THEME=freshlime
+# FLAME_THEME=coffee
 # Error Monitoring (optional)
 # SENTRY_DSN=https://your-dsn@sentry.io/project-id

package/template/docu.json CHANGED Viewed

@@ -6,6 +6,9 @@
     "baseURL": "http://localhost:3000",
     "favicon": "/docs/assets/images/favicon.ico"
   },
+  "themes": {
+    "colors": "default"
+  },
   "home": {
     "hero": {
       "tagline": "#MyDocs",