@docubook/flame 2.0.2 → 2.1.0

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

@@ -25,12 +25,17 @@ import {
 import {
   DOCS_DIR,
   DIST_DIR,
+  DOCS_OUT_DIR,
   ASSETS_DIR,
   CACHE_FILE,
   DOCS_ASSETS_DIR,
   PROJECT_ROOT,
   PAGES_DIR,
   loadDocuConfig,
+  servedBasePath,
+  docsDepth,
+  deployPath,
+  assertValidBasePath,
 } from "./paths";
 import { htmlShell } from "./html.shared";
 import { generateSearchIndex } from "./search-indexer";
@@ -39,7 +44,8 @@ import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
-import { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
+import { scanMdxFiles, resolveDocsIndexSource } from "./server-utils";
+import { defaultFavicon } from "./paths";
 import type { AssetManifest, BuildCache, BuildCacheMeta, CliArgs } from "./types";
 import { isCacheEntry } from "./types";
 import {
@@ -47,6 +53,7 @@ import {
   atomicWriteFile,
   hashMdxSources,
   hookMemoryPressure,
+  renderToolchainStamp,
   runtimeStamp,
 } from "./cache-key";
 import { clearDerivedPageCaches } from "./mdx";
@@ -76,7 +83,15 @@ async function readCache(): Promise<BuildCache> {
       const data = await readFile(CACHE_FILE, "utf-8");
       const parsed = JSON.parse(data) as BuildCache;
       const meta = parsed.__meta__ as BuildCacheMeta | undefined;
-      if (!meta || meta.version !== BUILD_CACHE_VERSION || meta.runtime !== runtimeStamp()) {
+      // `render` covers the framework's own rendering sources: a template or
+      // meta-tag edit changes output without touching any MDX file, so an
+      // older cache must not be trusted after one.
+      if (
+        !meta ||
+        meta.version !== BUILD_CACHE_VERSION ||
+        meta.runtime !== runtimeStamp() ||
+        meta.render !== renderToolchainStamp()
+      ) {
         return {};
       }
       return parsed;
@@ -94,6 +109,7 @@ function stampCache(cache: BuildCache): void {
     builtAt: Date.now(),
     version: BUILD_CACHE_VERSION,
     runtime: runtimeStamp(),
+    render: renderToolchainStamp(),
   };
 }
 
@@ -245,8 +261,8 @@ async function renderDocsPage(
   const headExtra = builder?.collectHead(ctx);
   const bodyExtra = builder?.collectBody(ctx);
 
-  const depth = slug ? slug.split("/").length : 1;
-  const favicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const depth = docsDepth(slug, servedBasePath());
+  const favicon = docuConfig.meta?.favicon || defaultFavicon();
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
   // MDX content hydrates from the bundled ESM module (mdx-hydrate), not
   // new Function — no 'unsafe-eval' needed in the CSP.
@@ -263,6 +279,7 @@ async function renderDocsPage(
     nonce,
     themeCss: inlineThemeCss,
     depth,
+    basePath: servedBasePath(),
     headExtra,
     bodyExtra,
   });
@@ -295,6 +312,11 @@ export async function runBuild(): Promise<void> {
 
   hookMemoryPressure(clearDerivedPageCaches);
 
+  // Normalized prefixes (case, whitespace, unservable characters) and values
+  // that cannot be honored would otherwise only surface after the whole build —
+  // report them, or stop before anything is written.
+  for (const warning of assertValidBasePath()) logger.warn(warning.message);
+
   logger.buildStart();
 
   if (args.clean) {
@@ -309,7 +331,7 @@ export async function runBuild(): Promise<void> {
   await mkdir(DIST_DIR, { recursive: true });
   await mkdir(ASSETS_DIR, { recursive: true });
 
-  await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DIST_DIR, "docs", "assets"));
+  await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DOCS_OUT_DIR, "assets"));
 
   const mdxFiles = await scanMdxFiles(DOCS_DIR);
   const cache = args.force ? {} : await readCache();
@@ -363,6 +385,13 @@ export async function runBuild(): Promise<void> {
   // key so the index page hydrates too. Its render has its own try/catch; skip
   // on error.
   const indexSource = resolveDocsIndexSource(DOCS_DIR);
+  const docsIndexPath = join(DOCS_OUT_DIR, "index.html");
+  // If the source was removed since the previous build, don't ship stale docs
+  // output. At the deployment root, this path belongs to the landing page.
+  if (!indexSource && DOCS_OUT_DIR !== DIST_DIR) {
+    const { rm } = await import("node:fs/promises");
+    await rm(docsIndexPath, { force: true });
+  }
   if (indexSource) {
     try {
       const indexRaw = await readFile(indexSource, "utf-8");
@@ -426,7 +455,7 @@ export async function runBuild(): Promise<void> {
     const rebuildDecision = shouldRebuild(file.path, file.mtime, cache);
 
     if (rebuildDecision === "no" && !builder) {
-      const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+      const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
       if (existsSync(outputPath) && !assetsChanged) {
         skipped++;
         continue;
@@ -448,7 +477,7 @@ export async function runBuild(): Promise<void> {
       const cached = cache[file.path];
       if (isCacheEntry(cached) && cached.hash === contentHash) {
         if (!assetsChanged) {
-          const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+          const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
           if (existsSync(outputPath)) {
             cache[file.path] = { ...cached, mtime: file.mtime, builtAt: Date.now() };
             skipped++;
@@ -474,7 +503,7 @@ export async function runBuild(): Promise<void> {
           builder,
           pageNonce
         );
-        const outputPath = join(DIST_DIR, "docs", `${capturedFile.path}.html`);
+        const outputPath = join(DOCS_OUT_DIR, `${capturedFile.path}.html`);
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, html);
         cache[capturedFile.path] = {
@@ -508,21 +537,19 @@ export async function runBuild(): Promise<void> {
         builder,
         generateNonce()
       );
-      await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-      await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
+      if (DOCS_OUT_DIR !== DIST_DIR) {
+        await mkdir(DOCS_OUT_DIR, { recursive: true });
+        await writeFile(docsIndexPath, indexHtml);
+      }
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       errors.push(`index: ${msg}`);
       console.error(`\n❌ Failed to build index: ${msg}\n`);
     }
-  } else {
-    const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
-    errors.push(`index: ${msg}`);
-    console.error(`\n❌ Failed to build index: ${msg}\n`);
   }
 
   const landingPage = React.createElement(IndexPage);
-  const landingFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const landingFavicon = docuConfig.meta?.favicon || defaultFavicon();
   const landingSeo = buildSeoMeta(
     docuConfig,
     docuConfig.meta as unknown as Record<string, unknown>,
@@ -548,14 +575,18 @@ export async function runBuild(): Promise<void> {
     js: landingContext.assets.js,
     nonce: landingNonce,
     themeCss: inlineThemeCss,
+    basePath: servedBasePath(),
     headExtra: builder?.collectHead(landingContext),
     bodyExtra: builder?.collectBody(landingContext),
   });
   if (builder) landingHtml = await builder.runTransformHtmlChain(landingHtml, landingContext);
+  // The landing page always owns `/`. At a root deployment the docs index
+  // would collide with it, so the index write above is skipped there — the
+  // docs root page simply does not exist.
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
 
   const notFoundPage = React.createElement(NotFoundPage);
-  const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const notFoundFavicon = docuConfig.meta?.favicon || defaultFavicon();
   const notFoundNonce = generateNonce();
   const notFoundContext: PageContext = {
     pageType: "notFound",
@@ -583,6 +614,8 @@ export async function runBuild(): Promise<void> {
     // Served as the static-host fallback at ANY requested path — relative
     // depth can never be right there, so use root-absolute asset URLs.
     absoluteAssets: true,
+    basePath: servedBasePath(),
+    deployPath: deployPath(),
   });
   if (builder) notFoundHtml = await builder.runTransformHtmlChain(notFoundHtml, notFoundContext);
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
@@ -596,7 +629,7 @@ export async function runBuild(): Promise<void> {
       slug: f.path,
       title: f.path.split("/").pop() || f.path,
       filePath: join(DOCS_DIR, f.path),
-      outputPath: join(DIST_DIR, "docs", `${f.path}.html`),
+      outputPath: join(DOCS_OUT_DIR, `${f.path}.html`),
     }));
     await builder.runOnEnd(pages, { assetManifest, outDir: DIST_DIR });
   }

package/.docu/node/build.ts

@@ -17,12 +17,17 @@ import {
 import {
   DOCS_DIR,
   DIST_DIR,
+  DOCS_OUT_DIR,
   ASSETS_DIR,
   CACHE_FILE,
   DOCS_ASSETS_DIR,
   PROJECT_ROOT,
   PAGES_DIR,
   loadDocuConfig,
+  servedBasePath,
+  docsDepth,
+  deployPath,
+  assertValidBasePath,
 } from "./paths";
 import { htmlShell } from "./html";
 import { generateSearchIndex } from "./search-indexer";
@@ -31,7 +36,8 @@ import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
-import { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
+import { scanMdxFiles, resolveDocsIndexSource } from "./server-utils";
+import { defaultFavicon } from "./paths";
 import type { AssetManifest, BuildCache, BuildCacheMeta, CliArgs } from "./types";
 import { isCacheEntry } from "./types";
 import {
@@ -39,6 +45,7 @@ import {
   atomicWriteFile,
   hashMdxSources,
   hookMemoryPressure,
+  renderToolchainStamp,
   runtimeStamp,
 } from "./cache-key";
 import { clearDerivedPageCaches } from "./mdx";
@@ -73,7 +80,15 @@ async function readCache(): Promise<BuildCache> {
       // output without changing page content — a stale cache would false-hit.
       // Discard when the version stamp or runtime fingerprint mismatches.
       const meta = parsed.__meta__ as BuildCacheMeta | undefined;
-      if (!meta || meta.version !== BUILD_CACHE_VERSION || meta.runtime !== runtimeStamp()) {
+      // `render` covers the framework's own rendering sources: a template or
+      // meta-tag edit changes output without touching any MDX file, so an
+      // older cache must not be trusted after one.
+      if (
+        !meta ||
+        meta.version !== BUILD_CACHE_VERSION ||
+        meta.runtime !== runtimeStamp() ||
+        meta.render !== renderToolchainStamp()
+      ) {
         return {};
       }
       return parsed;
@@ -92,6 +107,7 @@ function stampCache(cache: BuildCache): void {
     builtAt: Date.now(),
     version: BUILD_CACHE_VERSION,
     runtime: runtimeStamp(),
+    render: renderToolchainStamp(),
   };
 }
 
@@ -243,8 +259,8 @@ async function renderDocsPage(
   const headExtra = builder?.collectHead(ctx);
   const bodyExtra = builder?.collectBody(ctx);
 
-  const depth = slug ? slug.split("/").length : 1;
-  const favicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const depth = docsDepth(slug, servedBasePath());
+  const favicon = docuConfig.meta?.favicon || defaultFavicon();
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
   // Parity with build.impl.ts: static hosts without header control (GitHub
   // Pages) rely on the <meta> CSP for the per-page script policy.
@@ -261,6 +277,7 @@ async function renderDocsPage(
     nonce,
     themeCss: inlineThemeCss,
     depth,
+    basePath: servedBasePath(),
     headExtra,
     bodyExtra,
   });
@@ -294,6 +311,11 @@ async function build() {
   // OS runs low on memory (long CI builds). No-op on older runtimes.
   hookMemoryPressure(clearDerivedPageCaches);
 
+  // Normalized prefixes (case, whitespace, unservable characters) and values
+  // that cannot be honored would otherwise only surface after the whole build —
+  // report them, or stop before anything is written.
+  for (const warning of assertValidBasePath()) logger.warn(warning.message);
+
   logger.buildStart();
 
   if (args.clean) {
@@ -308,7 +330,7 @@ async function build() {
   await mkdir(DIST_DIR, { recursive: true });
   await mkdir(ASSETS_DIR, { recursive: true });
 
-  await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DIST_DIR, "docs", "assets"));
+  await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DOCS_OUT_DIR, "assets"));
 
   const mdxFiles = await scanMdxFiles(DOCS_DIR);
   const cache = args.force ? {} : await readCache();
@@ -362,6 +384,13 @@ async function build() {
   // key so the index page hydrates too. Its render has its own try/catch; skip
   // on error.
   const indexSource = resolveDocsIndexSource(DOCS_DIR);
+  const docsIndexPath = join(DOCS_OUT_DIR, "index.html");
+  // If the source was removed since the previous build, don't ship stale docs
+  // output. At the deployment root, this path belongs to the landing page.
+  if (!indexSource && DOCS_OUT_DIR !== DIST_DIR) {
+    const { rm } = await import("node:fs/promises");
+    await rm(docsIndexPath, { force: true });
+  }
   if (indexSource) {
     try {
       const indexRaw = await readFile(indexSource, "utf-8");
@@ -425,7 +454,7 @@ async function build() {
     const rebuildDecision = shouldRebuild(file.path, file.mtime, cache);
 
     if (rebuildDecision === "no" && !builder) {
-      const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+      const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
       if (existsSync(outputPath) && !assetsChanged) {
         skipped++;
         continue;
@@ -447,7 +476,7 @@ async function build() {
       const cached = cache[file.path];
       if (isCacheEntry(cached) && cached.hash === contentHash) {
         if (!assetsChanged) {
-          const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+          const outputPath = join(DOCS_OUT_DIR, `${file.path}.html`);
           if (existsSync(outputPath)) {
             cache[file.path] = { ...cached, mtime: file.mtime, builtAt: Date.now() };
             skipped++;
@@ -472,7 +501,7 @@ async function build() {
           builder,
           pageNonce
         );
-        const outputPath = join(DIST_DIR, "docs", `${capturedFile.path}.html`);
+        const outputPath = join(DOCS_OUT_DIR, `${capturedFile.path}.html`);
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, html);
         cache[capturedFile.path] = {
@@ -505,21 +534,19 @@ async function build() {
         builder,
         generateNonce()
       );
-      await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-      await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
+      if (DOCS_OUT_DIR !== DIST_DIR) {
+        await mkdir(DOCS_OUT_DIR, { recursive: true });
+        await writeFile(docsIndexPath, indexHtml);
+      }
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       errors.push(`index: ${msg}`);
       console.error(`\n❌ Failed to build index: ${msg}\n`);
     }
-  } else {
-    const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
-    errors.push(`index: ${msg}`);
-    console.error(`\n❌ Failed to build index: ${msg}\n`);
   }
 
   const landingPage = React.createElement(IndexPage);
-  const landingFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const landingFavicon = docuConfig.meta?.favicon || defaultFavicon();
   const landingSeo = buildSeoMeta(
     docuConfig,
     docuConfig.meta as unknown as Record<string, unknown>,
@@ -545,14 +572,18 @@ async function build() {
     js: landingContext.assets.js,
     nonce: landingNonce,
     themeCss: inlineThemeCss,
+    basePath: servedBasePath(),
     headExtra: builder?.collectHead(landingContext),
     bodyExtra: builder?.collectBody(landingContext),
   });
   if (builder) landingHtml = await builder.runTransformHtmlChain(landingHtml, landingContext);
+  // The landing page always owns `/`. At a root deployment the docs index
+  // would collide with it, so the index write above is skipped there — the
+  // docs root page simply does not exist.
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
 
   const notFoundPage = React.createElement(NotFoundPage);
-  const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const notFoundFavicon = docuConfig.meta?.favicon || defaultFavicon();
   const notFoundNonce = generateNonce();
   const notFoundContext: PageContext = {
     pageType: "notFound",
@@ -580,6 +611,8 @@ async function build() {
     // Served as the static-host fallback at ANY requested path — relative
     // depth can never be right there, so use root-absolute asset URLs.
     absoluteAssets: true,
+    basePath: servedBasePath(),
+    deployPath: deployPath(),
   });
   if (builder) notFoundHtml = await builder.runTransformHtmlChain(notFoundHtml, notFoundContext);
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
@@ -593,7 +626,7 @@ async function build() {
       slug: f.path,
       title: f.path.split("/").pop() || f.path,
       filePath: join(DOCS_DIR, f.path),
-      outputPath: join(DIST_DIR, "docs", `${f.path}.html`),
+      outputPath: join(DOCS_OUT_DIR, `${f.path}.html`),
     }));
     await builder.runOnEnd(pages, { assetManifest, outDir: DIST_DIR });
   }

package/.docu/node/cache-key.ts

@@ -1,16 +1,47 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
-import { FRAMEWORK_ROOT, STYLES_DIR, resolveProjectFile } from "./paths";
+import { FRAMEWORK_ROOT, STYLES_DIR, resolveProjectFile, basePath, deployPath } from "./paths";
 
 /**
  * Build cache version — bump when the toolchain output contract changes
  * (e.g. Bun.build barrel optimization, Tailwind CLI upgrade). Old caches
  * with a mismatched version are discarded on read (see build.ts readCache).
+ *
+ * v6: pages became base-path aware (`meta.basePath`), and the resolved value
+ * is folded into `basePathStamp()` below. Bumping here also invalidates any
+ * cache written by an earlier config, so a base-path edit can never be
+ * silently skipped as "unchanged".
  */
-export const BUILD_CACHE_VERSION = 5;
+export const BUILD_CACHE_VERSION = 6;
 
-/** Toolchain fingerprint: Bun version on Bun, Deno version on Deno, Node elsewhere. */
+/**
+ * Resolved docs URL prefix and deployment path, part of every cache key.
+ *
+ * The page cache is keyed by relative MDX path and the bundle/asset slots are
+ * hashed from MDX source alone — neither changes when only `meta.basePath` or
+ * `meta.baseURL`'s path changes. Without this stamp, editing either would leave
+ * every key untouched and the build would skip every page, emitting HTML that
+ * still points at the old prefix.
+ */
+export function basePathStamp(): string {
+  return prefixStamp(basePath(), deployPath());
+}
+
+/**
+ * Compose the cache stamp from both prefixes that shape generated URLs: the
+ * docs prefix and the host's deployment path (from `meta.baseURL`). Either one
+ * changing has to invalidate the cache, or a warm cache keeps serving HTML that
+ * points at the old location.
+ */
+export function prefixStamp(resolvedBasePath: string, deploymentPath: string): string {
+  if (deploymentPath.length === 0) return resolvedBasePath;
+  return `${resolvedBasePath || "/"}@${deploymentPath}`;
+}
+
+/**
+ * Toolchain fingerprint: Bun version on Bun, Deno version on Deno, Node elsewhere.
+ */
 export function runtimeStamp(): string {
   const g = globalThis as Record<string, unknown>;
   const bun = g.Bun as { version?: string } | undefined;
@@ -23,6 +54,59 @@ export function runtimeStamp(): string {
   return "node-unknown";
 }
 
+/**
+ * Framework source files that shape rendered HTML.
+ *
+ * Page cache entries are keyed by MDX source alone, so editing the renderer
+ * (a template tweak, a new meta tag, base-path plumbing) would otherwise leave
+ * every page a cache hit and keep serving HTML built by the old code. Hashing
+ * these sources makes a framework edit invalidate the pages it affects.
+ */
+const RENDER_SOURCE_FILES = [
+  ".docu/node/html.ts",
+  ".docu/node/html.shared.ts",
+  ".docu/node/seo.ts",
+  ".docu/node/utils.ts",
+  ".docu/node/paths.ts",
+  ".docu/node/base-path.ts",
+  ".docu/node/mdx.ts",
+  ".docu/node/search-indexer.ts",
+  ".docu/node/build.ts",
+  ".docu/node/build.impl.ts",
+  ".docu/node/server-routes.ts",
+  ".docu/components/DocsLayout.tsx",
+  ".docu/components/Navbar.tsx",
+  ".docu/pages/index.tsx",
+  ".docu/pages/404.tsx",
+  ".docu/pages/docs/[[...slug]].tsx",
+] as const;
+
+let renderStampCache: string | null = null;
+
+/**
+ * Fingerprint of the framework's rendering sources.
+ *
+ * Memoized per process — the files cannot change mid-build, and hashing them
+ * on every page would dominate build time. A missing file contributes nothing
+ * so a partial install still yields a stable (if weaker) stamp.
+ */
+export function renderToolchainStamp(): string {
+  if (renderStampCache !== null) return renderStampCache;
+  const h = createHash("sha256");
+  h.update(`v${BUILD_CACHE_VERSION}`);
+  for (const rel of RENDER_SOURCE_FILES) {
+    const file = join(FRAMEWORK_ROOT, rel);
+    try {
+      if (!existsSync(file)) continue;
+      h.update(rel).update("\0").update(readFileSync(file, "utf-8"));
+    } catch {
+      // unreadable source — skip it rather than break the build
+    }
+  }
+  renderStampCache = h.digest("hex").slice(0, 16);
+  return renderStampCache;
+}
+
 /**
  * True when a CSS file can change Tailwind v4 output.
  * v4 is CSS-first: `@theme`, `@source`, `@plugin`, `@custom-variant`,
@@ -230,6 +314,8 @@ export function computeTailwindCacheKey(
   h.update("\0");
   h.update(runtimeStamp());
   h.update("\0");
+  h.update(basePathStamp());
+  h.update("\0");
   h.update(`v${BUILD_CACHE_VERSION}`);
   return h.digest("hex").slice(0, 16);
 }
@@ -304,7 +390,9 @@ export function hookMemoryPressure(clear: () => void): void {
 export function hashMdxSources(mdxSources: Record<string, string>): string {
   const h = createHash("sha256");
   const slugs = Object.keys(mdxSources).sort();
-  h.update(`v${BUILD_CACHE_VERSION}:${runtimeStamp()}:`);
+  h.update(
+    `v${BUILD_CACHE_VERSION}:${runtimeStamp()}:${basePathStamp()}:${renderToolchainStamp()}:`
+  );
   for (const slug of slugs) {
     h.update(slug);
     h.update("\0");

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

@@ -1,7 +1,22 @@
 import type { DocuRoute, DocuConfig } from "./types";
-import { loadDocuConfig } from "./paths";
+import { loadDocuConfig, resolveBasePath, resolveDeployPath } from "./paths";
 import { resolveRoutes } from "./fs-scanner";
 
 const docuConfig = loadDocuConfig();
 export const routes: DocuRoute[] = resolveRoutes(docuConfig.routes || []);
 export const config = docuConfig as unknown as DocuConfig;
+
+/**
+ * URL prefix the site is served under (`""` at the domain root, else `/prefix`).
+ * Components use this instead of assuming `/docs`, so a subpath deployment does
+ * not request assets from the domain root.
+ */
+export const basePath: string = resolveBasePath(docuConfig);
+
+/**
+ * Path the host serves the dist root under (`""` at an origin root, `/repo` for
+ * a GitHub Pages project site — see `resolveDeployPath`). Root-absolute browser
+ * requests (the search index) build their URL from it, because the client
+ * bundle cannot read `docu.json` at runtime.
+ */
+export const deployPath: string = resolveDeployPath(docuConfig);

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

@@ -11,7 +11,7 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { DIST_DIR, PROJECT_ROOT, FRAMEWORK_ROOT } from "./paths";
+import { DIST_DIR, PROJECT_ROOT, FRAMEWORK_ROOT, servedBasePath } from "./paths";
 
 const FLAME_VERSION = JSON.parse(
   readFileSync(resolve(FRAMEWORK_ROOT, "package.json"), "utf-8")
@@ -20,7 +20,49 @@ const FLAME_VERSION = JSON.parse(
 const WORKFLOW_DIR = join(PROJECT_ROOT, ".github/workflows");
 const WORKFLOW_FILE = join(WORKFLOW_DIR, "deploy.yml");
 
-export const NGINX_CONF = `server {
+/**
+ * Nginx content-assets block.
+ *
+ * Two distinct asset trees:
+ *  - `/assets/` — hash-named client bundles, written to the dist root, immutable.
+ *  - `<prefix>/assets/` — user content assets copied from `docs/assets`,
+ *    revalidated after 7d.
+ *
+ * When the prefix is empty (root deployment) both trees land on `/assets/`, and
+ * nginx rejects duplicate location blocks — so the content tree is omitted and
+ * the immutable bundle rules win. Non-hashed content assets then inherit the
+ * 1y immutable header; that is a deliberate trade for a valid config, and root
+ * deployments are the uncommon case.
+ */
+export function buildNginxConf(basePath: string): string {
+  // nginx `location` names must be plain URI prefixes; anything else (spaces,
+  // braces, semicolons) fails `nginx -t` and the container never starts.
+  // Unsafe prefixes simply lose the content-assets cache block — the default
+  // location still serves the files, the same trade root deployments make.
+  const safePrefix = /^\/[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(basePath);
+  if (basePath.length > 0 && !safePrefix) {
+    console.warn(
+      `[flame] basePath "${basePath}" contains characters nginx cannot use in a location block; ` +
+        "omitting the content-assets caching block (assets still served)"
+    );
+  }
+  const contentAssetsBlock =
+    safePrefix && basePath.length > 0
+      ? `
+  location ${basePath}/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;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; 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'" always;
+  }
+`
+      : "";
+
+  return `server {
   listen 80;
   server_name _;
   root /usr/share/nginx/html;
@@ -58,18 +100,7 @@ export const NGINX_CONF = `server {
     add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
     add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; 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'" 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;
-    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; 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'" always;
-  }
-
+${contentAssetsBlock}
   location = /404.html { }
 
   location / {
@@ -77,6 +108,10 @@ export const NGINX_CONF = `server {
   }
 }
 `;
+}
+
+/** Backward-compatible default config (root-level `/docs` prefix). */
+export const NGINX_CONF = buildNginxConf("/docs");
 
 export const DOCKERIGNORE = `node_modules
 *.DS_Store
@@ -260,6 +295,7 @@ export const HEADERS_FILE = `/*
 `;
 
 const isDocker = !!process.env.FLAME_DEPLOY_DOCKER;
+
 const isSilent = !!process.env.FLAME_DEPLOY_SILENT;
 const isCi = !!process.env.FLAME_DEPLOY_CI;
 
@@ -300,7 +336,7 @@ async function writeDockerFiles() {
   }
 
   if (!existsSync(join(dockerDir, "nginx.conf"))) {
-    await writeFile(join(dockerDir, "nginx.conf"), NGINX_CONF);
+    await writeFile(join(dockerDir, "nginx.conf"), buildNginxConf(servedBasePath()));
     log.created("📄 Created nginx.conf");
   }