@docubook/flame 1.5.4 → 1.6.0

package/.docu/node/build.impl.ts

@@ -31,7 +31,7 @@ import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { scanMdxFiles } from "./utils";
 import type { BuildCache, CliArgs } from "./types";
-import { generateNonce } from "./security";
+import { generateNonce, cspHeader } from "./security";
 import type { PageMeta, PageContext } from "./plugin";
 import { buildSeoMeta } from "./seo";
 import DocsPage from "../pages/docs/[[...slug]]";
@@ -149,12 +149,14 @@ async function renderDocsPage(
   const depth = slug ? slug.split("/").length : 1;
   const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
+  const csp = cspHeader(nonce, process.env.NODE_ENV !== "production");
   let html = htmlShell({
     title,
     description,
     body,
     favicon,
     seo,
+    csp,
     css: assetManifest.css,
     js: assetManifest.js,
     nonce,
@@ -349,15 +351,17 @@ export async function runBuild(): Promise<void> {
   const landingPage = React.createElement(IndexPage);
   const landingFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
   const landingSeo = buildSeoMeta(docuConfig, docuConfig.meta as Record<string, unknown>, "");
+  const landingNonce = generateNonce();
   const landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",
     description: docuConfig.meta?.description || "",
     body: renderToString(landingPage),
     favicon: landingFavicon,
     seo: landingSeo,
+    csp: cspHeader(landingNonce, process.env.NODE_ENV !== "production"),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: landingNonce,
     themeCss: inlineThemeCss,
   });
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
@@ -368,15 +372,17 @@ export async function runBuild(): Promise<void> {
     React.createElement(NotFoundPage)
   );
   const notFoundFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const notFoundNonce = generateNonce();
   const notFoundHtml = htmlShell({
     title: "404 - Not Found",
     description: "",
     body: renderToString(notFoundPage),
     favicon: notFoundFavicon,
     headExtra: ['<meta name="robots" content="noindex,follow">'],
+    csp: cspHeader(notFoundNonce, process.env.NODE_ENV !== "production"),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: notFoundNonce,
     themeCss: inlineThemeCss,
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);

package/.docu/node/client.ts

@@ -25,6 +25,8 @@ function mountIsland(
 }
 
 function mountIslands() {
+  // forceCreate: SSR sidebar renders <Menu> only; client renders full <Sidebar>
+  // (DesktopSidebar + MobileBar) — structure mismatch forces full createRoot.
   mountIsland(
     "sidebar-island",
     (el) => {
@@ -38,18 +40,16 @@ function mountIslands() {
     true
   );
 
-  mountIsland(
-    "mobile-bar-island",
-    (el) => {
-      const tocs: TocItem[] = safeParseTocs(el.dataset.tocs);
-      return React.createElement(MobileBar, {
-        tocs,
-        title: el.dataset.title || "",
-        repoUrl: el.dataset.repo || "",
-      });
-    },
-    true
-  );
+  // mobile-bar-island SSR div is empty (data attributes only),
+  // so hydrateRoot child check falls through to createRoot automatically.
+  mountIsland("mobile-bar-island", (el) => {
+    const tocs: TocItem[] = safeParseTocs(el.dataset.tocs);
+    return React.createElement(MobileBar, {
+      tocs,
+      title: el.dataset.title || "",
+      repoUrl: el.dataset.repo || "",
+    });
+  });
 
   mountIsland("toc-island", (el) => {
     const tocs: TocItem[] = safeParseTocs(el.dataset.tocs);
@@ -69,7 +69,8 @@ function hydrateMdxContent() {
   try {
     const compiledSource = JSON.parse(sourceEl.textContent || "");
     const components = createMdxComponents();
-    createRoot(island).render(
+    hydrateRoot(
+      island,
       React.createElement(MDXRemote, { compiledSource, scope: {}, frontmatter: {}, components })
     );
   } catch (e) {
@@ -82,3 +83,27 @@ if (document.readyState === "loading") {
 } else {
   mountIslands();
 }
+
+// ── Hash scroll compensation ──────────────────────────────────────
+// After hydration, lazy-rendered content (Mermaid via IntersectionObserver) can
+// shift layout and push the hash target (#section-2) off-screen.
+// Poll with rAF for ~1s and re-scroll if the target is below viewport.
+function scrollToHashOnLoad() {
+  const hash = window.location.hash;
+  if (!hash || hash === "#") return;
+  const id = hash.slice(1);
+  const deadline = performance.now() + 1000;
+  function tick() {
+    const el = document.getElementById(id);
+    if (el) {
+      const top = el.getBoundingClientRect().top;
+      if (top <= window.innerHeight - 100 && top >= 0) return; // already in view
+      el.scrollIntoView();
+      return; // scrolled once, done
+    }
+    if (performance.now() < deadline) requestAnimationFrame(tick);
+  }
+  requestAnimationFrame(tick);
+}
+
+scrollToHashOnLoad();

package/.docu/node/deploy.shared.ts

@@ -1,7 +1,11 @@
 /**
- * Runtime-neutral deploy — mirror of `deploy.ts` (Bun-only, protected) for
- * Node.js and Deno. Instead of spawning `bun run build`, it runs the neutral
- * build in-process, then prepares `.docu/dist` for GitHub Pages.
+ * Runtime-neutral deploy — 3 modes:
+ *   1. `flame deploy`           → build + generate GitHub Actions workflow
+ *   2. `flame deploy --docker`  → build + generate Docker deployment files
+ *   3. `flame deploy --docker --silent` → same as #2, minimal output
+ *
+ * Mirror of deploy.ts (Bun-only, protected) for Node.js and Deno.
+ * Runs the neutral build in-process, then prepares .docu/dist.
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
@@ -12,26 +16,157 @@ import { DIST_DIR, PROJECT_ROOT } from "./paths";
 const WORKFLOW_DIR = join(PROJECT_ROOT, ".github/workflows");
 const WORKFLOW_FILE = join(WORKFLOW_DIR, "deploy.yml");
 
-export async function runDeploy(): Promise<void> {
-  console.log("📦 Building for production...\n");
+export const HEADERS_FILE = `/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+`;
+
+const isDocker = !!process.env.FLAME_DEPLOY_DOCKER;
+const isSilent = !!process.env.FLAME_DEPLOY_SILENT;
 
+/** Logger that no-ops all non-error output in silent mode. */
+const log = isSilent
+  ? { info: () => {}, ok: () => {}, created: () => {}, out: () => {} }
+  : {
+      info: (m: string) => console.log(m),
+      ok: () => console.log("\n✅ Ready to deploy!"),
+      created: (m: string) => console.log(m),
+      out: (m: string) => console.log(m),
+    };
+
+async function runBuild() {
   process.env.NODE_ENV = "production";
+  if (isSilent) {
+    process.env.FLAME_BUILD_SILENT = "1";
+    process.env.LOG_LEVEL = "error";
+  }
   const { runBuildCli } = await import("./build.impl");
   await runBuildCli();
+}
 
-  // Add .nojekyll
-  await writeFile(join(DIST_DIR, ".nojekyll"), "");
+async function writeDockerFiles() {
+  const dockerDir = PROJECT_ROOT;
+
+  if (!existsSync(join(dockerDir, "Dockerfile"))) {
+    await writeFile(
+      join(dockerDir, "Dockerfile"),
+      `FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/.docu/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+USER nginx
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`
+    );
+    log.created("📄 Created Dockerfile");
+  }
+
+  if (!existsSync(join(dockerDir, "nginx.conf"))) {
+    await writeFile(
+      join(dockerDir, "nginx.conf"),
+      `server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  gzip on;
+  gzip_types text/html text/css application/javascript image/svg+xml;
+
+  # Security headers (HSTS effective when HTTPS is terminated upstream)
+  add_header X-Frame-Options "DENY" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  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;
+
+  location /assets/ {
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    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;
+  }
+
+  location /docs/assets/ {
+    expires 7d;
+    add_header Cache-Control "public";
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    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;
+  }
+
+  location / {
+    try_files $uri $uri.html $uri/ =404;
+  }
+}
+`
+    );
+    log.created("📄 Created nginx.conf");
+  }
 
-  // Generate GitHub Actions workflow
+  if (!existsSync(join(dockerDir, ".dockerignore"))) {
+    await writeFile(
+      join(dockerDir, ".dockerignore"),
+      `node_modules
+.git
+*.DS_Store
+.docu/dist
+.docu/lib
+.env
+.env.*
+.npmrc
+*.log
+`
+    );
+    log.created("📄 Created .dockerignore");
+  }
+}
+
+async function writeGhaWorkflow() {
   if (!existsSync(WORKFLOW_FILE)) {
     await mkdir(WORKFLOW_DIR, { recursive: true });
     await writeFile(WORKFLOW_FILE, GITHUB_ACTIONS_WORKFLOW);
-    console.log("\n📄 Created .github/workflows/deploy.yml");
+    log.created("📄 Created .github/workflows/deploy.yml");
+  }
+}
+
+export async function runDeploy(): Promise<void> {
+  log.info("📦 Building for production...\n");
+  await runBuild();
+
+  // Common: .nojekyll + _headers
+  await writeFile(join(DIST_DIR, ".nojekyll"), "");
+  await writeFile(join(DIST_DIR, "_headers"), HEADERS_FILE);
+
+  if (isDocker) {
+    await writeDockerFiles();
+  } else {
+    await writeGhaWorkflow();
   }
 
-  console.log("\n✅ Ready to deploy!");
-  console.log("   Output: .docu/dist/");
-  console.log("   Push to GitHub and enable Pages (Settings → Pages → Source: GitHub Actions)");
+  log.ok();
+  log.out("   Output: .docu/dist/");
+  if (isDocker) {
+    log.out("   Run: docker build -t my-docs . && docker run -p 80:80 my-docs");
+  } else {
+    log.out("   Push to GitHub and enable Pages (Settings → Pages → Source: GitHub Actions)");
+  }
 }
 
 const GITHUB_ACTIONS_WORKFLOW = `name: Deploy to GitHub Pages

package/.docu/node/deploy.ts

@@ -1,56 +1,165 @@
 /**
- * Deploy script - prepares .docu/dist for GitHub Pages
+ * Deploy script — 3 modes:
+ *   1. `flame deploy`           → build + generate GitHub Actions workflow
+ *   2. `flame deploy --docker`  → build + generate Docker deployment files
+ *   3. `flame deploy --docker --silent` → same as #2, minimal output
  *
- * Usage: bun deploy
- *   Runs build, adds .nojekyll, and generates GitHub Actions workflow.
+ * Bun-native path — uses Bun.write() and Bun.spawn().
  */
 
-import { writeFile, mkdir } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DIST_DIR, PROJECT_ROOT } from "./paths";
+import { HEADERS_FILE } from "./deploy.shared";
+
+export { HEADERS_FILE };
 
 const WORKFLOW_DIR = join(PROJECT_ROOT, ".github/workflows");
 const WORKFLOW_FILE = join(WORKFLOW_DIR, "deploy.yml");
 
-const HEADERS_FILE = `/assets/*
-  Cache-Control: public, max-age=31536000, immutable
+const isDocker = !!process.env.FLAME_DEPLOY_DOCKER;
+const isSilent = !!process.env.FLAME_DEPLOY_SILENT;
 
-/assets/chunks/*
-  Cache-Control: public, max-age=31536000, immutable
-`;
+/** Logger that no-ops all non-error output in silent mode. */
+const log = isSilent
+  ? { info: () => {}, ok: () => {}, created: () => {}, out: () => {} }
+  : {
+      info: (m: string) => console.log(m),
+      ok: () => console.log("\n✅ Ready to deploy!"),
+      created: (m: string) => console.log(m),
+      out: (m: string) => console.log(m),
+    };
 
-async function deploy() {
-  console.log("📦 Building for production...\n");
-
-  // Run build
+async function runBuild() {
   const build = Bun.spawn(["bun", "run", "build"], {
-    stdout: "inherit",
-    stderr: "inherit",
+    stdout: isSilent ? "ignore" : "inherit",
+    stderr: isSilent ? "ignore" : "inherit",
   });
   const exitCode = await build.exited;
   if (exitCode !== 0) {
     console.error("\n❌ Build failed");
     process.exit(1);
   }
+}
 
-  // Add .nojekyll
-  await writeFile(join(DIST_DIR, ".nojekyll"), "");
+export const NGINX_CONF = `server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  gzip on;
+  gzip_types text/html text/css application/javascript image/svg+xml;
+
+  # Security headers (server-level, inherited by all locations)
+  # HSTS effective when HTTPS is terminated upstream (reverse proxy / LB)
+  add_header X-Frame-Options "DENY" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  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;
+
+  location /assets/ {
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    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;
+  }
 
-  // _headers: long-cache immutable assets for Netlify/Cloudflare Pages.
-  // GitHub Pages ignores it (its CDN caches separately) — harmless to emit.
-  await writeFile(join(DIST_DIR, "_headers"), HEADERS_FILE);
+  location /docs/assets/ {
+    expires 7d;
+    add_header Cache-Control "public";
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    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;
+  }
 
-  // Generate GitHub Actions workflow
+  location / {
+    try_files $uri $uri.html $uri/ =404;
+  }
+}
+`;
+
+export const DOCKERFILE_BUN = `FROM oven/bun:1 AS builder
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
+
+FROM nginx:alpine
+COPY --from=builder /app/.docu/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+USER nginx
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+
+export const DOCKERIGNORE = `node_modules
+.git
+*.DS_Store
+.docu/dist
+.docu/lib
+.env
+.env.*
+.npmrc
+*.log
+`;
+
+async function writeDockerFiles() {
+  const dockerDir = PROJECT_ROOT;
+
+  if (!existsSync(join(dockerDir, "Dockerfile"))) {
+    await Bun.write(join(dockerDir, "Dockerfile"), DOCKERFILE_BUN);
+    log.created("📄 Created Dockerfile");
+  }
+
+  if (!existsSync(join(dockerDir, "nginx.conf"))) {
+    await Bun.write(join(dockerDir, "nginx.conf"), NGINX_CONF);
+    log.created("📄 Created nginx.conf");
+  }
+
+  if (!existsSync(join(dockerDir, ".dockerignore"))) {
+    await Bun.write(join(dockerDir, ".dockerignore"), DOCKERIGNORE);
+    log.created("📄 Created .dockerignore");
+  }
+}
+
+async function writeGhaWorkflow() {
   if (!existsSync(WORKFLOW_FILE)) {
     await mkdir(WORKFLOW_DIR, { recursive: true });
-    await writeFile(WORKFLOW_FILE, GITHUB_ACTIONS_WORKFLOW);
-    console.log("\n📄 Created .github/workflows/deploy.yml");
+    await Bun.write(WORKFLOW_FILE, GITHUB_ACTIONS_WORKFLOW);
+    log.created("📄 Created .github/workflows/deploy.yml");
+  }
+}
+
+async function deploy() {
+  log.info("📦 Building for production...\n");
+  await runBuild();
+
+  // Common: .nojekyll + _headers
+  await Bun.write(join(DIST_DIR, ".nojekyll"), "");
+  await Bun.write(join(DIST_DIR, "_headers"), HEADERS_FILE);
+
+  if (isDocker) {
+    await writeDockerFiles();
+  } else {
+    await writeGhaWorkflow();
   }
 
-  console.log("\n✅ Ready to deploy!");
-  console.log("   Output: .docu/dist/");
-  console.log("   Push to GitHub and enable Pages (Settings → Pages → Source: GitHub Actions)");
+  log.ok();
+  log.out("   Output: .docu/dist/");
+  if (isDocker) {
+    log.out("   Run: docker build -t my-docs . && docker run -p 80:80 my-docs");
+  } else {
+    log.out("   Push to GitHub and enable Pages (Settings → Pages → Source: GitHub Actions)");
+  }
 }
 
 const GITHUB_ACTIONS_WORKFLOW = `name: Deploy to GitHub Pages
@@ -103,7 +212,9 @@ jobs:
         uses: actions/deploy-pages@v4
 `;
 
-deploy().catch((err) => {
-  console.error("Deploy failed:", err);
-  process.exit(1);
-});
+if (import.meta.main) {
+  deploy().catch((err) => {
+    console.error("Deploy failed:", err);
+    process.exit(1);
+  });
+}

package/.docu/node/html.shared.ts

@@ -79,6 +79,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <title>${escapeHtml(title)}</title>
   <meta name="description" content="${escapeHtml(description)}">
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${escapeHtml(resolvePath(favicon))}">` : ""}${themeStyle}
+  <link rel="preload" href="${escapeHtml(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${escapeHtml(assetPrefix + css)}">
   ${csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">` : ""}
   ${seoTags}
@@ -86,6 +87,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
 </head>
 <body>
   <div id="root">${body}</div>
+  <link rel="modulepreload" href="${escapeHtml(assetPrefix + js)}">
   <script type="module"${nonceAttr} src="${escapeHtml(assetPrefix + js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
 </body>
 </html>`;

package/.docu/node/html.ts

@@ -1,30 +1,5 @@
-import type { SeoMeta } from "./seo";
-
-export interface HtmlShellOptions {
-  title: string;
-  description: string;
-  body: string;
-  favicon: string;
-  css: string;
-  js: string;
-  nonce?: string;
-  /**
-   * Content-Security-Policy value (from `cspHeader()` in security.ts).
-   * When provided, injects `<meta http-equiv="Content-Security-Policy">` in `<head>`.
-   * Essential for static deployment where HTTP headers cannot be set.
-   */
-  csp?: string;
-  extraScripts?: string;
-  themeCss?: string;
-  /** Depth from document root (0=root, 1=subdir, 2=sub/subdir). Used for relative asset paths. */
-  depth?: number;
-  /** HTML strings to inject before `</head>` (from plugin `injectHead` hooks). */
-  headExtra?: string[];
-  /** HTML strings to inject before `</body>`, after the main script (from plugin `injectBody` hooks). */
-  bodyExtra?: string[];
-  /** SEO meta tags derived from config + frontmatter */
-  seo?: SeoMeta;
-}
+import type { HtmlShellOptions } from "./html.shared";
+export type { HtmlShellOptions };
 
 export function htmlShell(opts: HtmlShellOptions): string {
   const {
@@ -69,6 +44,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <title>${Bun.escapeHTML(title)}</title>
   <meta name="description" content="${Bun.escapeHTML(description)}">
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(resolvePath(favicon))}">` : ""}${themeStyle}
+  <link rel="preload" href="${Bun.escapeHTML(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${Bun.escapeHTML(assetPrefix + css)}">
   ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(csp)}">` : ""}
   ${seoTags}
@@ -76,6 +52,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
 </head>
 <body>
   <div id="root">${body}</div>
+  <link rel="modulepreload" href="${Bun.escapeHTML(assetPrefix + js)}">
   <script type="module"${nonceAttr} src="${Bun.escapeHTML(assetPrefix + js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
 </body>
 </html>`;