@docubook/flame 2.0.3 → 2.1.0

package/.docu/lib/{server.impl-CZ4eMe5L.js → server.impl-DcyZhPA_.js}

@@ -1,7 +1,7 @@
-import { a as DOCS_DIR, c as PAGES_DIR, f as loadDocuConfig, l as PROJECT_ROOT, r as DIST_DIR } from "./paths-Cbz-dj4s.js";
-import { D as loadPlugins, E as BuildPluginBuilder, a as IndexPage, b as buildClientBundle, c as captureException, f as compileMdx, i as DocsLayout, l as initSentry, m as frontmatterField, n as hmrScript, o as NotFoundPage, r as htmlShell, s as DocsPage, t as errorHtml, u as generateSearchIndex, x as computeInlineThemeCss } from "./html.shared-CsEFmy_Y.js";
-import { _ as isSlugSafe, a as getContentType, g as isPathSafe, l as stripDocsHtmlSuffix, m as htmlResponse, p as generateNonce, u as SECURITY_HEADERS, y as wrapPluginResponse } from "./utils-B_CoyKie.js";
-import { t as logger } from "./logger-DFKQUy8M.js";
+import { E as resolveBasePath, O as stripDocsHtmlSuffix, S as docsDepth, _ as loadDocuConfig, a as DOCS_DIR, f as assertValidBasePath, h as defaultFavicon, l as PAGES_DIR, r as DIST_DIR, u as PROJECT_ROOT, w as matchDocsSlug, y as servedBasePath } from "./paths-CHXABfXa.js";
+import { D as BuildPluginBuilder, O as loadPlugins, a as IndexPage, b as buildClientBundle, c as captureException, f as compileMdx, i as DocsLayout, l as initSentry, m as frontmatterField, n as hmrScript, o as NotFoundPage, r as htmlShell, s as DocsPage, t as errorHtml, u as generateSearchIndex, x as computeInlineThemeCss } from "./html.shared-RPCM1y5Q.js";
+import { c as htmlResponse, d as isSlugSafe, i as SECURITY_HEADERS, p as wrapPluginResponse, s as generateNonce, t as getContentType, u as isPathSafe } from "./server-utils-BYWB7A6T.js";
+import { t as logger } from "./logger-DYFD47f8.js";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, statSync, watch } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -11,7 +11,7 @@ import { renderToString } from "react-dom/server";
 //#region .docu/node/server-routes.ts
 async function createHtmlResponse(title, description, body, status, state, pageType, page, depth = 0) {
 	const nonce = generateNonce();
-	const favicon = state.docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+	const favicon = state.docuConfig.meta?.favicon || defaultFavicon();
 	const assets = state.assetManifest[pageType];
 	const context = {
 		...page,
@@ -32,6 +32,8 @@ async function createHtmlResponse(title, description, body, status, state, pageT
 		headExtra: state.builder?.collectHead(context),
 		bodyExtra: state.builder?.collectBody(context),
 		depth,
+		basePath: servedBasePath(),
+		deployPath: "",
 		absoluteAssets: status === 404
 	});
 	if (state.builder) html = await state.builder.runTransformHtmlChain(html, context);
@@ -112,7 +114,7 @@ async function renderDocsServerPage(doc, slug, pathname, state) {
 		compiledSource: doc.compiledSource
 	}));
 	const body = renderToString(page);
-	const depth = slug.length || 1;
+	const depth = docsDepth(slug.join("/"), servedBasePath());
 	return createHtmlResponse(title, description, body, 200, state, "docs", {
 		slug: slug.join("/"),
 		filePath: doc.filePath,
@@ -129,14 +131,14 @@ async function renderPage(Component, title, description, status, state, props =
 }
 async function handleDocsIndex(state) {
 	const doc = await getDocsForSlug("", state);
-	if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, 1);
-	return renderDocsServerPage(doc, [], "/docs", state);
+	if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, docsDepth("", servedBasePath()));
+	return renderDocsServerPage(doc, [], servedBasePath() || "/", state);
 }
 async function handleDocsRoute(slug, state) {
 	const path = slug.join("/");
 	const doc = await getDocsForSlug(path, state);
-	if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, slug.length || 1);
-	return renderDocsServerPage(doc, slug, `/docs/${path}`, state);
+	if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state, {}, docsDepth(path, servedBasePath()));
+	return renderDocsServerPage(doc, slug, `${servedBasePath()}/${path}`, state);
 }
 async function handleIndex(state) {
 	const page = React.createElement(IndexPage);
@@ -164,9 +166,10 @@ function serveStatic(pathname) {
 	} catch (err) {
 		if (err.code !== "ENOENT") throw err;
 	}
-	if (decoded.startsWith("/docs/assets/")) {
+	const docsAssetsPrefix = `${servedBasePath()}/assets/`;
+	if (decoded.startsWith(docsAssetsPrefix)) {
 		const docsAssetsDir = resolve(DOCS_DIR, "assets");
-		const requestedRelative = decoded.slice(13);
+		const requestedRelative = decoded.slice(docsAssetsPrefix.length);
 		const docsAsset = resolve(docsAssetsDir, requestedRelative);
 		const docsAssetsDirWithSep = docsAssetsDir.endsWith("/") ? docsAssetsDir : docsAssetsDir + "/";
 		if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirWithSep)) return null;
@@ -200,6 +203,8 @@ function serverErrorResponse(error) {
 */
 async function runServer(adapter) {
 	const docuConfig = loadDocuConfig();
+	const resolvedBasePath = resolveBasePath(docuConfig);
+	for (const warning of assertValidBasePath()) logger.warn(warning.message);
 	const parsedPort = parseInt(process.env.PORT ?? "3000", 10);
 	const PORT = Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535 ? parsedPort : 3e3;
 	logger.buildStart();
@@ -283,7 +288,7 @@ async function runServer(adapter) {
 	let handle = null;
 	const fetchHandler = async (req) => {
 		const url = new URL(req.url);
-		const pathname = stripDocsHtmlSuffix(url.pathname);
+		const pathname = stripDocsHtmlSuffix(url.pathname, resolvedBasePath);
 		const startTime = performance.now();
 		if (builder) {
 			const pluginResponse = await builder.runHandleRequest(req, {
@@ -320,11 +325,11 @@ async function runServer(adapter) {
 			}
 			let response;
 			if (pathname === "/") response = await handleIndex(state);
-			else if (pathname === "/docs" || pathname === "/docs/") response = await handleDocsIndex(state);
-			else if (pathname.startsWith("/docs/")) {
-				const slug = pathname.slice(6).split("/").filter(Boolean);
-				response = slug.length === 0 ? await handleDocsIndex(state) : await handleDocsRoute(slug, state);
-			} else response = await handleNotFound(state);
+			else {
+				const docsSlug = matchDocsSlug(pathname, resolvedBasePath);
+				if (docsSlug) response = docsSlug.length === 0 ? await handleDocsIndex(state) : await handleDocsRoute(docsSlug, state);
+				else response = await handleNotFound(state);
+			}
 			logger.request(req.method, pathname, response.status, Math.round(performance.now() - startTime));
 			return response;
 		} catch (err) {
@@ -346,4 +351,4 @@ async function runServer(adapter) {
 //#endregion
 export { runServer as t };
 
-//# sourceMappingURL=server.impl-CZ4eMe5L.js.map
+//# sourceMappingURL=server.impl-DcyZhPA_.js.map

package/.docu/lib/server.impl-DcyZhPA_.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.impl-DcyZhPA_.js","names":[],"sources":["../node/server-routes.ts","../node/server.impl.ts"],"sourcesContent":["import { readFile, stat } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { readFileSync, statSync } from \"node:fs\";\nimport React, { type ReactNode } from \"react\";\nimport { renderToString } from \"react-dom/server\";\nimport { compileMdx, frontmatterField } from \"./mdx\";\nimport { getContentType } from \"./server-utils\";\nimport { defaultFavicon } from \"./paths\";\nimport { DOCS_DIR, DIST_DIR, PAGES_DIR, PROJECT_ROOT, servedBasePath, docsDepth } from \"./paths\";\nimport { BuildPluginBuilder } from \"./plugin-builder\";\nimport type { PageContext, PageType } from \"./plugin\";\nimport type { AssetEntry, AssetManifest, DocuConfig, TocItem } from \"./types\";\nimport DocsPage from \"../pages/docs/[[...slug]]\";\nimport NotFoundPage from \"../pages/404\";\nimport IndexPage from \"../pages/index\";\nimport { DocsLayout } from \"../components/DocsLayout\";\nimport { generateNonce, isPathSafe, isSlugSafe, htmlResponse, SECURITY_HEADERS } from \"./security\";\nimport { htmlShell as createHtmlShell, hmrScript, errorHtml } from \"./html.shared\";\n\nexport interface ServerState {\n  docuConfig: DocuConfig;\n  assetManifest: AssetManifest;\n  inlineThemeCss?: string;\n  builder: BuildPluginBuilder | null;\n}\n\nasync function createHtmlResponse(\n  title: string,\n  description: string,\n  body: string,\n  status: number,\n  state: ServerState,\n  pageType: PageType,\n  page: Omit<PageContext, \"pageType\" | \"assets\" | \"config\">,\n  depth = 0\n): Promise<Response> {\n  const nonce = generateNonce();\n  const favicon = state.docuConfig.meta?.favicon || defaultFavicon();\n  const assets: AssetEntry = state.assetManifest[pageType];\n  const context: PageContext = {\n    ...page,\n    pageType,\n    assets,\n    config: state.docuConfig,\n  };\n  let html = createHtmlShell({\n    title,\n    description,\n    body,\n    favicon,\n    css: assets.css,\n    js: assets.js,\n    nonce,\n    extraScripts: hmrScript(nonce),\n    themeCss: state.inlineThemeCss,\n    headExtra: state.builder?.collectHead(context),\n    bodyExtra: state.builder?.collectBody(context),\n    depth,\n    basePath: servedBasePath(),\n    // Dev serves the project from the origin root, so the host's deployment\n    // path never applies here — only the static build writes it into HTML.\n    deployPath: \"\",\n    // 404 pages can be requested at arbitrary depths (e.g. a noLink section\n    // path typed in the address bar) — relative asset paths would resolve\n    // against the wrong directory and break CSS/JS.\n    absoluteAssets: status === 404,\n  });\n  if (state.builder) html = await state.builder.runTransformHtmlChain(html, context);\n  /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */\n  return htmlResponse(html, nonce, status, true);\n}\n\n// Dev-only memo: compileMdx per request is ~70ms; repeat navigations with\n// an unchanged file (same mtime) reuse the compiled result. The dev server\n// has no other per-page cache — without this every navigation re-parses MDX.\n// ponytail: unbounded Map is fine — docs sites have a handful of pages; cap\n// with an LRU only if a project exceeds thousands of routes.\nconst docsCache = new Map<\n  string,\n  { mtimeMs: number; doc: NonNullable<Awaited<ReturnType<typeof getDocsForSlug>>> }\n>();\n\nasync function getDocsForSlug(\n  slug: string,\n  state: ServerState\n): Promise<{\n  content: ReactNode;\n  compiledSource: string;\n  frontmatter: Record<string, unknown>;\n  tocs: TocItem[];\n  filePath: string;\n  resolvedContent: string;\n} | null> {\n  if (!isSlugSafe(slug, DOCS_DIR)) return null;\n\n  const paths = [\n    resolve(DOCS_DIR, slug, \"index.mdx\"),\n    resolve(DOCS_DIR, `${slug}.mdx`),\n    resolve(DOCS_DIR, slug, \"index.md\"),\n    resolve(DOCS_DIR, `${slug}.md`),\n  ];\n\n  const resolvedDocsDir = resolve(DOCS_DIR);\n  let filePath: string | null = null;\n  let raw: string | null = null;\n  for (const p of paths) {\n    const resolvedCandidate = resolve(p);\n    if (\n      resolvedCandidate !== resolvedDocsDir &&\n      !resolvedCandidate.startsWith(resolvedDocsDir + \"/\")\n    ) {\n      continue;\n    }\n    try {\n      raw = await readFile(resolvedCandidate, \"utf-8\");\n      filePath = resolvedCandidate;\n      break;\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") throw err;\n    }\n  }\n  if (!filePath || !raw) return null;\n\n  const relPath = filePath.replace(PROJECT_ROOT + \"/\", \"\");\n\n  const mtimeMs = (await stat(filePath)).mtimeMs;\n  const cached = docsCache.get(relPath);\n  if (cached && cached.mtimeMs === mtimeMs) {\n    return cached.doc;\n  }\n\n  let content = raw;\n  if (state.builder) {\n    const transformed = await state.builder.runOnLoad(relPath, content);\n    if (transformed?.contents) {\n      content = transformed.contents;\n    }\n  }\n\n  const remarkPlugins = state.builder?.collectRemarkPlugins();\n  const rehypePlugins = state.builder?.collectRehypePlugins();\n  const result = await compileMdx(content, relPath, undefined, remarkPlugins, rehypePlugins);\n\n  let frontmatter = result.frontmatter as Record<string, unknown>;\n  if (state.builder) {\n    frontmatter = await state.builder.runTransformFrontmatterChain(frontmatter, {\n      slug,\n      filePath: relPath,\n      content,\n    });\n  }\n\n  const doc = {\n    content: result.content,\n    compiledSource: result.compiledSource,\n    frontmatter,\n    tocs: result.tocs,\n    filePath: relPath,\n    resolvedContent: content,\n  };\n  docsCache.set(relPath, { mtimeMs, doc });\n  return doc;\n}\n\nasync function renderDocsServerPage(\n  doc: NonNullable<Awaited<ReturnType<typeof getDocsForSlug>>>,\n  slug: string[],\n  pathname: string,\n  state: ServerState\n): Promise<Response> {\n  const title = frontmatterField(doc.frontmatter, \"title\") || slug.join(\"/\") || \"Docs\";\n  const description = frontmatterField(doc.frontmatter, \"description\");\n\n  const page = React.createElement(\n    DocsLayout,\n    { repoUrl: state.docuConfig.repo?.url, pathname },\n    React.createElement(DocsPage, {\n      slug,\n      title,\n      description,\n      date: frontmatterField(doc.frontmatter, \"date\") || undefined,\n      // Same root-relative SSR as build — see build.ts.\n      content: renderToString(doc.content),\n      tocs: doc.tocs,\n      filePath: doc.filePath,\n      repoUrl: state.docuConfig.repo?.url,\n      compiledSource: doc.compiledSource,\n    })\n  );\n\n  const body = renderToString(page);\n\n  // Same relative climb as the static build — see docsDepth.\n  const depth = docsDepth(slug.join(\"/\"), servedBasePath());\n\n  return createHtmlResponse(\n    title,\n    description,\n    body,\n    200,\n    state,\n    \"docs\",\n    {\n      slug: slug.join(\"/\"),\n      filePath: doc.filePath,\n      frontmatter: doc.frontmatter,\n      content: doc.resolvedContent,\n    },\n    depth\n  );\n}\n\nasync function renderPage(\n  Component: React.ComponentType<Record<string, unknown>>,\n  title: string,\n  description: string,\n  status: number,\n  state: ServerState,\n  props: Record<string, unknown> = {},\n  depth = 0\n): Promise<Response> {\n  const body = renderToString(React.createElement(Component, props));\n  return createHtmlResponse(\n    title,\n    description,\n    body,\n    status,\n    state,\n    \"notFound\",\n    {\n      slug: \"404\",\n      filePath: resolve(PAGES_DIR, \"404.tsx\"),\n      frontmatter: {},\n    },\n    depth\n  );\n}\n\nexport async function handleDocsIndex(state: ServerState): Promise<Response> {\n  const doc = await getDocsForSlug(\"\", state);\n  if (!doc)\n    return renderPage(\n      NotFoundPage,\n      \"404 - Not Found\",\n      \"\",\n      404,\n      state,\n      {},\n      docsDepth(\"\", servedBasePath())\n    );\n  return renderDocsServerPage(doc, [], servedBasePath() || \"/\", state);\n}\n\nexport async function handleDocsRoute(slug: string[], state: ServerState): Promise<Response> {\n  const path = slug.join(\"/\");\n  const doc = await getDocsForSlug(path, state);\n  if (!doc)\n    return renderPage(\n      NotFoundPage,\n      \"404 - Not Found\",\n      \"\",\n      404,\n      state,\n      {},\n      docsDepth(path, servedBasePath())\n    );\n  return renderDocsServerPage(doc, slug, `${servedBasePath()}/${path}`, state);\n}\n\nexport async function handleIndex(state: ServerState): Promise<Response> {\n  const page = React.createElement(IndexPage);\n  const body = renderToString(page);\n  return createHtmlResponse(\n    state.docuConfig.meta?.title || \"DocuBook\",\n    state.docuConfig.meta?.description || \"\",\n    body,\n    200,\n    state,\n    \"home\",\n    {\n      slug: \"\",\n      filePath: resolve(PAGES_DIR, \"index.tsx\"),\n      frontmatter: { ...state.docuConfig.meta } as Record<string, unknown>,\n    }\n  );\n}\n\nexport async function handleNotFound(state: ServerState, depth = 0): Promise<Response> {\n  return renderPage(NotFoundPage, \"404 - Not Found\", \"\", 404, state, {}, depth);\n}\n\nexport function serveStatic(pathname: string): Response | null {\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(pathname);\n  } catch {\n    return null;\n  }\n  if (!isPathSafe(pathname, DIST_DIR)) return null;\n  const assetPath = resolve(DIST_DIR, decoded.slice(1));\n  try {\n    const s = statSync(assetPath);\n    if (s.isFile()) {\n      return new Response(readFileSync(assetPath), {\n        headers: { \"Content-Type\": getContentType(pathname) },\n      });\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") throw err;\n  }\n\n  const docsAssetsPrefix = `${servedBasePath()}/assets/`;\n  if (decoded.startsWith(docsAssetsPrefix)) {\n    const docsAssetsDir = resolve(DOCS_DIR, \"assets\");\n    const requestedRelative = decoded.slice(docsAssetsPrefix.length);\n    const docsAsset = resolve(docsAssetsDir, requestedRelative);\n    const docsAssetsDirWithSep = docsAssetsDir.endsWith(\"/\") ? docsAssetsDir : docsAssetsDir + \"/\";\n    if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirWithSep)) return null;\n    try {\n      const s = statSync(docsAsset);\n      if (s.isFile()) {\n        return new Response(readFileSync(docsAsset), {\n          headers: { \"Content-Type\": getContentType(pathname) },\n        });\n      }\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") throw err;\n    }\n  }\n  return null;\n}\n\nexport function serverErrorResponse(error: unknown): Response {\n  const msg = error instanceof Error ? error.message : \"Unknown error\";\n  const st =\n    process.env.NODE_ENV !== \"production\" && error instanceof Error ? error.stack : undefined;\n  return new Response(errorHtml(msg, st), {\n    status: 500,\n    headers: {\n      \"Content-Type\": \"text/html\",\n      ...SECURITY_HEADERS,\n      \"Content-Security-Policy\": \"default-src 'none'; style-src 'unsafe-inline'\",\n    },\n  });\n}\n","/**\n * Runtime-neutral dev server — mirror of `server.ts` (Bun-only, protected)\n * driven by a `RuntimeAdapter` (./runtime) instead of `Bun.serve`,\n * with manual route matching instead of `Bun.FileSystemRouter`. The page set\n * is static (`/`, `/docs/[[...slug]]`, `/404`), so a router is unnecessary.\n */\n\nimport { watch, existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { createRequire } from \"node:module\";\nimport type { RuntimeAdapter, ServerHandle } from \"./runtime\";\nimport { DOCS_DIR, loadDocuConfig, resolveBasePath, assertValidBasePath } from \"./paths\";\nimport { loadPlugins } from \"./plugin-loader\";\nimport { BuildPluginBuilder } from \"./plugin-builder\";\nimport { buildClientBundle, computeInlineThemeCss } from \"./hydrate.node\";\nimport { generateSearchIndex } from \"./search-indexer\";\nimport { logger } from \"./logger\";\nimport { initSentry, captureException } from \"./sentry\";\nimport {\n  serveStatic,\n  handleDocsIndex,\n  handleDocsRoute,\n  handleIndex,\n  handleNotFound,\n  serverErrorResponse,\n  type ServerState,\n} from \"./server-routes\";\nimport { wrapPluginResponse } from \"./security\";\nimport { matchDocsSlug, stripDocsHtmlSuffix } from \"./utils\";\n\nexport async function runServer(adapter: RuntimeAdapter): Promise<ServerHandle> {\n  const docuConfig = loadDocuConfig();\n  const resolvedBasePath = resolveBasePath(docuConfig);\n\n  // Report normalized prefixes (and stop on a value that cannot be honored)\n  // before the server announces a site that would be built somewhere else.\n  for (const warning of assertValidBasePath()) logger.warn(warning.message);\n\n  const parsedPort = parseInt(process.env.PORT ?? \"3000\", 10);\n  const PORT =\n    Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535 ? parsedPort : 3000;\n\n  logger.buildStart();\n\n  await initSentry();\n\n  logger.bundleStart();\n  let t = performance.now();\n  const assetManifest = await buildClientBundle();\n  logger.bundleDone(Math.round(performance.now() - t));\n\n  const inlineThemeCss = computeInlineThemeCss();\n\n  logger.indexStart();\n  t = performance.now();\n  const records = await generateSearchIndex();\n  logger.indexDone(records, Math.round(performance.now() - t));\n\n  logger.routes();\n\n  // Plugin setup — all hooks active (onLoad, remark/rehype, frontmatter, head/body, html transform, handleRequest)\n  const pluginsConfig = docuConfig.plugins ?? [];\n  const builder = pluginsConfig.length > 0 ? new BuildPluginBuilder(docuConfig) : null;\n\n  if (builder) {\n    const plugins = await loadPlugins(pluginsConfig);\n\n    for (const plugin of plugins) {\n      await plugin.setup(builder);\n    }\n    await builder.runOnStart();\n  }\n\n  const state: ServerState = {\n    docuConfig,\n    assetManifest,\n    inlineThemeCss,\n    builder,\n  };\n\n  const hmrClients = new Set<ReadableStreamDefaultController>();\n\n  const require = createRequire(import.meta.url);\n  /** Locate the installed @docubook/markdown source dir (workspace link), if any. */\n  function resolveMdxContentSrc(): string | null {\n    try {\n      const pkgDir = dirname(require.resolve(\"@docubook/markdown/package.json\"));\n      const src = join(pkgDir, \"src\");\n      return existsSync(src) ? src : null;\n    } catch {\n      return null;\n    }\n  }\n\n  let hmrTimeout: ReturnType<typeof setTimeout> | null = null;\n  const watcher = watch(DOCS_DIR, { recursive: true }, (_event, filename) => {\n    if (!filename || (!filename.endsWith(\".mdx\") && !filename.endsWith(\".md\"))) return;\n    if (hmrTimeout) clearTimeout(hmrTimeout);\n    hmrTimeout = setTimeout(() => {\n      for (const client of [...hmrClients]) {\n        try {\n          client.enqueue(new TextEncoder().encode(\"data: reload\\n\\n\"));\n        } catch {\n          hmrClients.delete(client);\n        }\n      }\n    }, 300);\n  });\n\n  // Rebuild the client bundle when component sources change (e.g. the\n  // @docubook/markdown workspace package) so interactive islands pick up\n  // edits, then reload connected clients. MDX edits are handled by the watcher\n  // above — no rebuild needed, content recompiles per request.\n  let srcHmrTimeout: ReturnType<typeof setTimeout> | null = null;\n  const mdxContentSrc = resolveMdxContentSrc();\n  const srcWatcher = mdxContentSrc\n    ? watch(mdxContentSrc, { recursive: true }, (_event, filename) => {\n        if (!filename || !/\\.(ts|tsx|js|jsx|css)$/.test(filename)) return;\n        if (srcHmrTimeout) clearTimeout(srcHmrTimeout);\n        srcHmrTimeout = setTimeout(async () => {\n          try {\n            state.assetManifest = await buildClientBundle();\n            logger.warn(\"[hmr] client bundle rebuilt (component change)\");\n          } catch (e) {\n            logger.warn(\n              `[hmr] bundle rebuild failed: ${e instanceof Error ? e.message : String(e)}`\n            );\n          }\n          for (const client of [...hmrClients]) {\n            try {\n              client.enqueue(new TextEncoder().encode(\"data: reload\\n\\n\"));\n            } catch {\n              hmrClients.delete(client);\n            }\n          }\n        }, 300);\n      })\n    : null;\n\n  process.on(\"SIGINT\", () => {\n    watcher.close();\n    srcWatcher?.close();\n    process.exit(0);\n  });\n  process.on(\"SIGTERM\", () => {\n    watcher.close();\n    srcWatcher?.close();\n    process.exit(0);\n  });\n\n  let handle: ServerHandle | null = null;\n\n  const fetchHandler = async (req: Request): Promise<Response> => {\n    const url = new URL(req.url);\n    // Generated links carry `.html` (matching the static build output);\n    // route them to the same handler as their extensionless form.\n    const pathname = stripDocsHtmlSuffix(url.pathname, resolvedBasePath);\n    const startTime = performance.now();\n\n    if (builder) {\n      const pluginResponse = await builder.runHandleRequest(req, {\n        port: handle?.port ?? PORT,\n        hostname: handle?.hostname ?? \"localhost\",\n        assetManifest: state.assetManifest,\n      });\n      if (pluginResponse) {\n        const securedResponse = wrapPluginResponse(pluginResponse, true);\n        logger.request(\n          req.method,\n          pathname,\n          securedResponse.status,\n          Math.round(performance.now() - startTime)\n        );\n        return securedResponse;\n      }\n    }\n\n    try {\n      if (pathname === \"/__hmr\") {\n        const stream = new ReadableStream({\n          start(controller) {\n            hmrClients.add(controller);\n            controller.enqueue(new TextEncoder().encode(\"data: connected\\n\\n\"));\n          },\n          cancel(controller) {\n            hmrClients.delete(controller);\n          },\n        });\n        return new Response(stream, {\n          headers: {\n            \"Content-Type\": \"text/event-stream\",\n            \"Cache-Control\": \"no-cache\",\n            Connection: \"keep-alive\",\n          },\n        });\n      }\n\n      if (pathname.startsWith(\"/assets/\") || /\\.\\w+$/.test(pathname)) {\n        const staticRes = serveStatic(pathname);\n        if (staticRes) return staticRes;\n      }\n\n      let response: Response;\n\n      // The landing page owns `/` in every deployment. At the deployment root\n      // (`meta.basePath: \"\"`) docs would otherwise claim it, but the build\n      // skips the docs index there — so dev must not serve it either.\n      // Static assets were already handled above, so a root deployment may\n      // still match every other path as a docs route.\n      if (pathname === \"/\") {\n        response = await handleIndex(state);\n      } else {\n        const docsSlug = matchDocsSlug(pathname, resolvedBasePath);\n        if (docsSlug) {\n          response =\n            docsSlug.length === 0\n              ? await handleDocsIndex(state)\n              : await handleDocsRoute(docsSlug, state);\n        } else {\n          response = await handleNotFound(state);\n        }\n      }\n\n      logger.request(\n        req.method,\n        pathname,\n        response.status,\n        Math.round(performance.now() - startTime)\n      );\n      return response;\n    } catch (err) {\n      captureException(err, { method: req.method, pathname });\n      logger.request(req.method, pathname, 500, Math.round(performance.now() - startTime));\n      return serverErrorResponse(err);\n    }\n  };\n\n  handle = await adapter.serve(fetchHandler, { port: PORT, idleTimeout: 255 });\n\n  logger.ready(handle.port, true);\n  return handle;\n}\n"],"mappings":"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"}

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

@@ -1,5 +1,5 @@
 import { t as nodeAdapter } from "./node-DPTySdwG.js";
-import { t as runServer } from "./server.impl-CZ4eMe5L.js";
+import { t as runServer } from "./server.impl-DcyZhPA_.js";
 //#region .docu/node/server.node.ts
 await runServer(nodeAdapter);
 //#endregion

package/.docu/node/base-path.ts

@@ -0,0 +1,306 @@
+import type { DocuConfig } from "./types";
+
+/**
+ * Pure base-path helpers shared by server modules and client-side components.
+ *
+ * This module MUST stay free of Node built-ins (`node:path`, `node:fs`) and of
+ * modules that evaluate them at import time (like `./paths`): it is bundled
+ * into the client, where `import.meta.dirname` and `process.cwd()` do not
+ * exist. All functions here are string operations over a resolved prefix.
+ */
+
+/** Default URL prefix the docs site is served under. Kept as `/docs` so
+ * existing deployments keep byte-identical output. */
+export const DEFAULT_BASE_PATH = "/docs";
+
+/**
+ * Normalize a configured base path into `/prefix` form with no trailing slash.
+ * `""` and `"/"` mean "served at the domain root"; a missing value is not
+ * handled here — `resolveBasePath` owns the default. Absolute URLs
+ * (`https://host/x`) contribute only their pathname, so a `meta.baseURL` can be
+ * passed straight in.
+ */
+export function normalizeBasePath(value: string | undefined | null): string {
+  if (typeof value !== "string") return DEFAULT_BASE_PATH;
+  let path = value.trim();
+  if (path.length === 0 || path === "/") return "";
+  try {
+    if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(path)) path = new URL(path).pathname;
+  } catch {
+    // malformed URL — fall through and treat the raw value as a path
+  }
+  path = `/${path.replace(/^\/+|\/+$/g, "")}`;
+  return path === "/" ? "" : path;
+}
+
+/**
+ * Resolve the docs URL prefix from config.
+ *
+ * An explicit `meta.basePath` wins, including `""` for a root deployment.
+ * Otherwise `/docs` (the historical behaviour).
+ *
+ * Deliberately NOT derived from `meta.baseURL`'s pathname: `baseURL` is the
+ * origin + deployment root and `basePath` is the prefix beneath it. Deriving
+ * one from the other's pathname double-counts that path — the SEO/canonical
+ * builder appends the prefix to `baseURL`, so `baseURL: ".../repo"` deriving
+ * `basePath: "/repo"` produced `.../repo/repo/...`. They must be configured
+ * independently; the schema documents both.
+ */
+export function resolveBasePath(config?: DocuConfig | null): string {
+  const meta = config?.meta;
+  if (typeof meta?.basePath !== "string") return DEFAULT_BASE_PATH;
+  // Root forms (`""`, `"/"`, `"///"`) stay root. Everything else is
+  // canonicalized so routing, output directories and every generated URL agree
+  // on one spelling — `"/Docs"` and `"/docs me"` are honored as `"/docs"`
+  // and `"/docs-me"` (reported by `validateBasePath`).
+  if (normalizeBasePath(meta.basePath) === "") return "";
+  return canonicalBasePath(meta.basePath) || DEFAULT_BASE_PATH;
+}
+
+/**
+ * Deployment-root path contributed by the host, taken from `meta.baseURL`:
+ * `""` when the origin serves the dist at `/`, `/repo` for a GitHub Pages
+ * project site (which serves the artifact under `<origin>/repo/`).
+ *
+ * Distinct from the base path — `basePath` is the prefix *inside* the dist,
+ * this is the prefix *above* it. Only root-absolute references need it (the 404
+ * fallback and the search index); relative ones line up already because pages
+ * and assets share the deployment root.
+ */
+export function resolveDeployPath(config?: DocuConfig | null): string {
+  const raw = config?.meta?.baseURL;
+  if (typeof raw !== "string") return "";
+  try {
+    return normalizeBasePath(new URL(raw).pathname);
+  } catch {
+    // Not an absolute URL. A root-relative value is still a usable path; a bare
+    // hostname without a scheme is a config mistake, not a prefix — ignore it.
+    return raw.startsWith("/") ? normalizeBasePath(raw) : "";
+  }
+}
+
+export interface BasePathIssue {
+  /** `error` blocks the build; `warning` only reports. */
+  level: "error" | "warning";
+  message: string;
+}
+
+/**
+ * Canonical prefix form: lowercase segments with whitespace collapsed to dashes
+ * and characters a static host cannot serve dropped (`"/Docs"` → `"/docs"`,
+ * `"/docs me"` → `"/docs-me"`). Structural normalization runs first, so an
+ * absolute value (`https://host/x`) works too. Returns `""` when nothing
+ * servable is left, which callers treat as a config mistake rather than a
+ * silent root deployment.
+ */
+export function canonicalBasePath(value: string): string {
+  const structural = normalizeBasePath(value);
+  if (structural === "") return "";
+  // Whitespace and unservable characters fold away, then dot segments are
+  // dropped: a prefix is a URL path *and* an output directory, so `.`/`..`
+  // would either escape the dist or resolve differently than the URL does.
+  const cleaned = structural
+    .replace(/\s+/g, "-")
+    .replace(/[^A-Za-z0-9\-._~/]+/g, "")
+    .split("/")
+    .filter((segment) => segment.length > 0 && segment !== "." && segment !== "..")
+    .join("/")
+    .replace(/-{2,}/g, "-")
+    .toLowerCase();
+  return cleaned.length > 0 ? `/${cleaned}` : "";
+}
+
+/**
+ * Validate an authored `meta.basePath`.
+ *
+ * `resolveBasePath` normalizes what a static host cannot serve, so this reports
+ * what it had to change instead of blocking the build: only a non-string value
+ * (which cannot be normalized) is an error. Warnings name the reasons and the
+ * canonical value, so the author can fix `docu.json` and keep the editor schema
+ * — which only accepts the canonical form — quiet.
+ */
+export function validateBasePath(value: unknown): BasePathIssue[] {
+  if (value === undefined) return [];
+  if (typeof value !== "string") {
+    return [
+      {
+        level: "error",
+        message: `must be a string (received ${
+          value === null ? "null" : typeof value
+        }) — remove it or set "${DEFAULT_BASE_PATH}"`,
+      },
+    ];
+  }
+
+  // `""`, `"/"`, `"///"` and whitespace-only values all mean the deployment
+  // root, which is always servable.
+  const structural = normalizeBasePath(value);
+  if (structural === "") return [];
+
+  const canonical = canonicalBasePath(value);
+  if (canonical === "") {
+    return [
+      {
+        level: "warning",
+        message: `"${value}" has no characters a static host can serve — falling back to "${DEFAULT_BASE_PATH}"`,
+      },
+    ];
+  }
+  if (canonical === structural) return [];
+
+  const segments = structural.replace(/^\/+/, "");
+  const reasons: string[] = [];
+  if (/\s/.test(segments)) reasons.push("whitespace");
+  // Whitespace is already reported above — list only the other unservable
+  // characters here, or the message prints a blank `( )`.
+  const invalid = [
+    ...new Set(segments.replace(/[\s]/g, "").replace(/[A-Za-z0-9\-._~/]/g, "")),
+  ].join(" ");
+  if (invalid.length > 0) reasons.push(`characters that need percent-encoding (${invalid})`);
+  if (segments !== segments.toLowerCase()) reasons.push("non-lowercase letters");
+  if (/\.\.|(^|\/)\.(\/|$)|--|\/\//.test(segments))
+    reasons.push("dot segments or doubled separators");
+
+  return [
+    {
+      level: "warning",
+      message: `"${value}" ${
+        reasons.length > 0 ? `contains ${reasons.join(", ")}` : "is not canonical"
+      } — normalized to "${canonical}"; update docu.json to match`,
+    },
+  ];
+}
+
+/** Join a serve-prefix with a slash-relative path, keeping exactly one slash. */
+export function withBasePath(path: string, resolvedBasePath: string = DEFAULT_BASE_PATH): string {
+  const suffix = path.length === 0 || path === "/" ? "" : `/${path.replace(/^\/+|\/+$/g, "")}`;
+  return `${resolvedBasePath}${suffix}`;
+}
+
+/** Prefix a root-relative asset path (e.g. `/assets/x.js`) with the base path. */
+export function assetHref(assetPath: string, resolvedBasePath: string = DEFAULT_BASE_PATH): string {
+  return withBasePath(assetPath, resolvedBasePath);
+}
+
+/**
+ * Apply the base path to a docs route unless it already carries it.
+ * Idempotent, which matters because routes are prefixed at more than one
+ * layer (nav components, SEO, search indexer) and a route may already be
+ * absolute when it reaches us.
+ */
+export function applyBasePath(path: string, resolvedBasePath: string = DEFAULT_BASE_PATH): string {
+  if (resolvedBasePath.length === 0) return path;
+  if (path === resolvedBasePath || path.startsWith(`${resolvedBasePath}/`)) return path;
+  return withBasePath(path, resolvedBasePath);
+}
+
+/**
+ * Is `pathname` inside the docs site?
+ *
+ * True under the configured prefix (when there is one) and for paths still
+ * authored with the default `/docs` prefix — those are what callers re-base.
+ * Anything else is a sibling route on the same origin (an app at `/app`, a
+ * status page) and has to be left exactly as the author wrote it.
+ */
+export function isDocsPath(
+  pathname: string,
+  resolvedBasePath: string = DEFAULT_BASE_PATH
+): boolean {
+  if (
+    resolvedBasePath.length > 0 &&
+    (pathname === resolvedBasePath || pathname.startsWith(`${resolvedBasePath}/`))
+  ) {
+    return true;
+  }
+  return pathname === DEFAULT_BASE_PATH || pathname.startsWith(`${DEFAULT_BASE_PATH}/`);
+}
+
+/**
+ * Point an author-written root-relative content path at the configured prefix.
+ *
+ * Authors reference content assets as they appear on disk
+ * (`/docs/assets/images/favicon.ico`, `/docs/assets/images/og.png`). When the
+ * site is served under a different prefix that leading segment must be
+ * rewritten, otherwise the asset 404s at the old path. Paths that already carry
+ * the configured prefix, or sit outside the default one, are left untouched.
+ */
+export function rebaseContentPath(
+  path: string,
+  resolvedBasePath: string = DEFAULT_BASE_PATH
+): string {
+  // A path already carrying the configured prefix is final. At the deployment
+  // root ("") no path can carry it, so that guard must not swallow the
+  // default-prefix rewrite below.
+  if (
+    resolvedBasePath.length > 0 &&
+    (path === resolvedBasePath || path.startsWith(`${resolvedBasePath}/`))
+  ) {
+    return path;
+  }
+  // The authored default prefix collapses to the deployment root ("") or is
+  // rewritten onto the configured prefix; content assets follow the copy in
+  // `<dist>/<prefix>/assets/`, which is the root at a root deployment.
+  if (path === DEFAULT_BASE_PATH) return resolvedBasePath || "/";
+  if (path.startsWith(`${DEFAULT_BASE_PATH}/`)) {
+    return `${resolvedBasePath}${path.slice(DEFAULT_BASE_PATH.length)}`;
+  }
+  return path;
+}
+
+/** Map an `/{basePath}` request back to its extensionless route (dev server).
+ *  Handles both `/{basePath}/*.html` (pages) and `/{basePath}.html` (the
+ *  directory-index edge case), with `basePath` taken from `meta.basePath`. */
+export function stripDocsHtmlSuffix(
+  pathname: string,
+  resolvedBasePath: string = DEFAULT_BASE_PATH
+): string {
+  if (resolvedBasePath.length === 0) {
+    // Root deployment: docs live at `/…`, so there is no prefix to match. Only
+    // the directory-index edge case can be mapped back safely.
+    return pathname === "/index.html" ? "/" : pathname;
+  }
+  if (pathname === `${resolvedBasePath}.html`) return resolvedBasePath;
+  if (pathname.startsWith(`${resolvedBasePath}/`) && pathname.endsWith(".html"))
+    return pathname.slice(0, -".html".length);
+  return pathname;
+}
+
+/**
+ * Strip the configured docs prefix from a request path, returning the slug
+ * segments. `null` means the request is not a docs route.
+ *
+ * Root deployments match every request (docs own `/`), so the caller must
+ * dispatch `/assets/…` and other static paths to `serveStatic` first — which
+ * both dev servers already do.
+ */
+export function matchDocsSlug(
+  pathname: string,
+  resolvedBasePath: string = DEFAULT_BASE_PATH
+): string[] | null {
+  if (resolvedBasePath.length === 0) {
+    if (pathname !== "/" && pathname.endsWith("/")) return null;
+    return pathname === "/" ? [] : pathname.slice(1).split("/").filter(Boolean);
+  }
+  if (pathname === resolvedBasePath || pathname === `${resolvedBasePath}/`) return [];
+  if (pathname.startsWith(`${resolvedBasePath}/`))
+    return pathname
+      .slice(resolvedBasePath.length + 1)
+      .split("/")
+      .filter(Boolean);
+  return null;
+}
+
+/**
+ * Relative climb from a built page to the dist root — the `../` count the HTML
+ * shell needs for bundle assets.
+ *
+ * A page lands at `<dist>/<basePath>/<slug>.html`, so it reaches the dist root
+ * through the slug's own directories plus every prefix segment. The host's
+ * deployment path is deliberately not counted: pages and assets share it (both
+ * resolve under `<deployPath>/`), so it cancels out of the relative math.
+ */
+export function docsDepth(slug: string, resolvedBasePath: string = DEFAULT_BASE_PATH): number {
+  const pageDirs = slug ? slug.split("/").filter(Boolean).length - 1 : 0;
+  const prefixSegments = resolvedBasePath.split("/").filter(Boolean).length;
+  return Math.max(0, pageDirs) + prefixSegments;
+}