@docubook/flame 1.5.4 → 1.6.1

package/.docu/lib/preview.node.js

@@ -1,9 +1,9 @@
 import {
   runPreview
-} from "./chunk-XLH7Z4QO.js";
+} from "./chunk-P3ZT4S3D.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-GXQB4ETN.js";
-import "./chunk-J5NMYSBJ.js";
+import "./chunk-2VUUBIN3.js";
+import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.node.ts
 import { nodeAdapter } from "@docubook/runt";

package/.docu/lib/server.deno.js

@@ -1,10 +1,10 @@
 import {
   runServer
-} from "./chunk-BDWN6AHQ.js";
-import "./chunk-C67LPMQA.js";
+} from "./chunk-GC62TPBC.js";
+import "./chunk-IJFMQFWW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-GXQB4ETN.js";
-import "./chunk-J5NMYSBJ.js";
+import "./chunk-2VUUBIN3.js";
+import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.deno.ts
 import { denoAdapter } from "@docubook/runt";

package/.docu/lib/server.node.js

@@ -1,10 +1,10 @@
 import {
   runServer
-} from "./chunk-BDWN6AHQ.js";
-import "./chunk-C67LPMQA.js";
+} from "./chunk-GC62TPBC.js";
+import "./chunk-IJFMQFWW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-GXQB4ETN.js";
-import "./chunk-J5NMYSBJ.js";
+import "./chunk-2VUUBIN3.js";
+import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.node.ts
 import { nodeAdapter } from "@docubook/runt";

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,74 +16,291 @@ 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 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;
+  }
+}
+`;
+
+export const DOCKERIGNORE = `node_modules
+.git
+*.DS_Store
+.docu/dist
+.docu/lib
+.env
+.env.*
+.npmrc
+*.log
+`;
 
+export function detectPkgManager(dir: string): {
+  baseImage: string;
+  lockFile: string;
+  installCmd: string;
+  runCmd: string;
+  cache: string;
+  setupAction: string;
+} {
+  const bunLockFile = existsSync(join(dir, "bun.lock"))
+    ? "bun.lock"
+    : existsSync(join(dir, "bun.lockb"))
+      ? "bun.lockb"
+      : null;
+  if (bunLockFile) {
+    return {
+      baseImage: "oven/bun:1",
+      lockFile: bunLockFile,
+      installCmd: "bun install --frozen-lockfile",
+      runCmd: "bun",
+      cache: "",
+      setupAction: "bun",
+    };
+  }
+  if (existsSync(join(dir, "pnpm-lock.yaml"))) {
+    return {
+      baseImage: "node:22-alpine",
+      lockFile: "pnpm-lock.yaml",
+      installCmd: "corepack enable && pnpm install --frozen-lockfile",
+      runCmd: "pnpm",
+      cache: "pnpm",
+      setupAction: "pnpm",
+    };
+  }
+  if (existsSync(join(dir, "yarn.lock"))) {
+    return {
+      baseImage: "node:22-alpine",
+      lockFile: "yarn.lock",
+      installCmd: "yarn install --frozen-lockfile",
+      runCmd: "yarn",
+      cache: "yarn",
+      setupAction: "node",
+    };
+  }
+  // default: npm
+  return {
+    baseImage: "node:22-alpine",
+    lockFile: "package-lock.json",
+    installCmd: "npm ci",
+    runCmd: "npm",
+    cache: "npm",
+    setupAction: "node",
+  };
+}
+
+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;
+  const pm = detectPkgManager(dockerDir);
+
+  if (!existsSync(join(dockerDir, "Dockerfile"))) {
+    await writeFile(
+      join(dockerDir, "Dockerfile"),
+      `FROM ${pm.baseImage} AS builder
+WORKDIR /app
+COPY package.json ${pm.lockFile} ./
+RUN ${pm.installCmd}
+COPY . .
+RUN ${pm.runCmd} 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"), NGINX_CONF);
+    log.created("📄 Created nginx.conf");
+  }
+
+  if (!existsSync(join(dockerDir, ".dockerignore"))) {
+    await writeFile(join(dockerDir, ".dockerignore"), DOCKERIGNORE);
+    log.created("📄 Created .dockerignore");
+  }
+}
+
+function generateWorkflowYml(): string {
+  const pm = detectPkgManager(PROJECT_ROOT);
+
+  const setupSteps: string[] = [
+    "      - uses: actions/checkout@v7",
+    "        with:",
+    "          fetch-depth: 0",
+    "",
+  ];
+
+  if (pm.setupAction === "bun") {
+    setupSteps.push(
+      "      - uses: oven-sh/setup-bun@v2",
+      "        with:",
+      "          bun-version: latest",
+      ""
+    );
+  } else if (pm.setupAction === "pnpm") {
+    setupSteps.push(
+      "      - uses: pnpm/action-setup@v6",
+      "",
+      "      - uses: actions/setup-node@v6",
+      "        with:",
+      "          node-version: 22",
+      `          cache: ${pm.cache}`,
+      ""
+    );
+  } else {
+    // npm / yarn
+    setupSteps.push(
+      "      - uses: actions/setup-node@v6",
+      "        with:",
+      "          node-version: 22",
+      `          cache: ${pm.cache}`,
+      ""
+    );
+  }
 
-  // Generate GitHub Actions workflow
+  return [
+    `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:",
+    ...setupSteps,
+    `      - run: ${pm.installCmd}`,
+    "",
+    `      - run: ${pm.runCmd} 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",
+  ].join("\n");
+}
+
+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 writeFile(WORKFLOW_FILE, generateWorkflowYml());
+    log.created("📄 Created .github/workflows/deploy.yml");
   }
-
-  console.log("\n✅ Ready to deploy!");
-  console.log("   Output: .docu/dist/");
-  console.log("   Push to GitHub and enable Pages (Settings → Pages → Source: GitHub Actions)");
 }
 
-const 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 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();
+  }
+
+  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)");
+  }
+}