davaux 0.8.0

package/src/cli.ts

@@ -0,0 +1,502 @@
+import { createReadStream, existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { createRequire } from 'node:module'
+import { extname, join, resolve } from 'node:path'
+import { collectCss, generateIslandsEntry, islandServerPlugin } from './build/plugins.js'
+import { collectEsbuildPlugins, collectScannerSuffixes, pathsToAlias } from './config.js'
+import { handleBuildError } from './errors.js'
+
+const [, , command, ...args] = process.argv
+const cwd = process.cwd()
+
+switch (command) {
+  case 'create':
+    await runCreate()
+    break
+  case 'create-multisite':
+    await runCreateMultisite()
+    break
+  case 'generate':
+    await runGenerate()
+    break
+  case 'dev':
+    await runDev()
+    break
+  case 'build':
+    await runBuild()
+    break
+  case 'static':
+    await runStatic()
+    break
+  case 'start':
+    await runStart()
+    break
+  case 'preview':
+    await runPreview()
+    break
+  default:
+    console.error(`davaux: unknown command "${command ?? ''}"`)
+    console.error(
+      '  Usage: davaux <create|create-multisite|generate|dev|build|start|static|preview> [options]',
+    )
+    process.exit(1)
+}
+
+async function runCreate() {
+  const { scaffold } = await import('./create.js')
+  await scaffold(args[0], cwd)
+}
+
+async function runCreateMultisite() {
+  const { scaffoldMultisite } = await import('./create-multisite.js')
+  await scaffoldMultisite(args[0], cwd)
+}
+
+async function runGenerate() {
+  const { generate } = await import('./generate.js')
+  generate(args, cwd)
+}
+
+async function runDev() {
+  loadEnv(cwd)
+  const serverSrc = resolve(cwd, 'server.ts')
+  if (existsSync(serverSrc)) {
+    console.warn('[davaux] server.ts detected — custom server entry is not used in dev mode')
+    console.warn(
+      '  Use "node --watch --import tsx/esm server.ts" to develop with your custom server',
+    )
+  }
+  const { startDev } = await import('./dev/watch.js')
+  const { loadConfig } = await import('./build/config.js')
+  const config = await loadConfig(cwd)
+  const middlewareSrc = resolve(cwd, 'src', 'middleware.ts')
+  await startDev({
+    cwd,
+    port: Number(getFlag('--port', args) ?? config.server?.port ?? 3000),
+    hostname: getFlag('--hostname', args) ?? config.server?.hostname ?? 'localhost',
+    paths: config.paths,
+    plugins: config.plugins ?? [],
+    external: config.external,
+    middlewareSrc: existsSync(middlewareSrc) ? middlewareSrc : undefined,
+    editor: config.editor,
+  })
+}
+
+// ─── Build ────────────────────────────────────────────────────────────────────
+
+async function runBuild() {
+  rmSync(resolve(cwd, 'dist'), { recursive: true, force: true })
+
+  const { build } = await import('esbuild')
+  const { loadConfig } = await import('./build/config.js')
+  const config = await loadConfig(cwd)
+  const davauxPlugins = config.plugins ?? []
+  const extraPlugins = collectEsbuildPlugins(davauxPlugins)
+  const extraSuffixes = collectScannerSuffixes(davauxPlugins)
+  const userAlias = pathsToAlias(config.paths ?? {})
+  const routesDir = resolve(cwd, 'src', 'routes')
+  const islandsDir = resolve(cwd, 'src', 'islands')
+
+  if (!existsSync(routesDir)) {
+    console.error(`[davaux] No routes directory found at ${routesDir}`)
+    process.exit(1)
+  }
+
+  const { scanRoutes } = await import('./router/scanner.js')
+  const { scanIslands } = await import('./router/scanner.js')
+  const { routes, layouts, middlewares, errorPage } = await scanRoutes(routesDir, extraSuffixes)
+  const islands = await scanIslands(islandsDir)
+
+  const outDir = resolve(cwd, 'dist')
+  const serverEntries = [
+    ...routes.map((r) => r.filePath),
+    ...layouts.map((l) => l.filePath),
+    ...middlewares.map((m) => m.filePath),
+    ...(errorPage ? [errorPage] : []),
+  ]
+
+  const serverExternal = ['node:*', 'davaux', ...(config.external ?? [])]
+
+  if (serverEntries.length === 0) {
+    console.log('[davaux] No routes found — nothing to build.')
+  } else {
+    await build({
+      entryPoints: serverEntries,
+      outdir: outDir,
+      outbase: routesDir,
+      format: 'esm',
+      platform: 'node',
+      target: 'node22',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux',
+      external: serverExternal,
+      alias: { ...userAlias, 'davaux/client': 'davaux/signal' },
+      sourcemap: true,
+      plugins: [islandServerPlugin(islandsDir), ...extraPlugins],
+    }).catch((err) => handleBuildError('Server build', err))
+    console.log(
+      `[davaux] Built ${routes.length} route(s) and ${layouts.length} layout(s) to ${outDir}`,
+    )
+  }
+
+  // Build src/middleware.ts separately if it exists (not under routesDir, so needs its own outfile)
+  const middlewareSrc = resolve(cwd, 'src', 'middleware.ts')
+  if (existsSync(middlewareSrc)) {
+    await build({
+      entryPoints: [middlewareSrc],
+      outfile: resolve(outDir, 'middleware.js'),
+      format: 'esm',
+      platform: 'node',
+      target: 'node22',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux',
+      external: serverExternal,
+      alias: { ...userAlias, 'davaux/client': 'davaux/signal' },
+      sourcemap: true,
+    }).catch((err) => handleBuildError('Middleware build', err))
+  }
+
+  const clientScripts: string[] = []
+
+  // Islands client bundle (auto-generated from scanned islands)
+  if (islands.length > 0) {
+    const islandsOutFile = resolve(cwd, 'dist', '_davaux', 'islands.js')
+    await build({
+      stdin: {
+        contents: generateIslandsEntry(islands),
+        loader: 'ts',
+        resolveDir: cwd,
+      },
+      outfile: islandsOutFile,
+      format: 'esm',
+      platform: 'browser',
+      target: 'es2022',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux/client',
+      alias: userAlias,
+      tsconfigRaw: JSON.stringify({
+        compilerOptions: { jsx: 'react-jsx', jsxImportSource: 'davaux/client' },
+      }),
+      sourcemap: true,
+      plugins: [...extraPlugins],
+    }).catch((err) => handleBuildError('Islands build', err))
+    clientScripts.push('/_davaux/islands.js')
+    console.log(`[davaux] Built islands bundle (${islands.length} island(s))`)
+  }
+
+  // Optional user-authored client bundle
+  const clientEntry = resolve(cwd, 'src', 'client.ts')
+  if (existsSync(clientEntry)) {
+    const clientOutFile = resolve(cwd, 'dist', '_davaux', 'client.js')
+    await build({
+      entryPoints: [clientEntry],
+      outfile: clientOutFile,
+      format: 'esm',
+      platform: 'browser',
+      target: 'es2022',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux/client',
+      alias: userAlias,
+      tsconfigRaw: JSON.stringify({
+        compilerOptions: { jsx: 'react-jsx', jsxImportSource: 'davaux/client' },
+      }),
+      sourcemap: true,
+      plugins: [...extraPlugins],
+    }).catch((err) => handleBuildError('Client build', err))
+    clientScripts.push('/_davaux/client.js')
+    console.log(`[davaux] Built client bundle to ${clientOutFile}`)
+  }
+
+  // Collect CSS side-effect outputs from all builds into a single stylesheet
+  const stylesOutFile = resolve(cwd, 'dist', '_davaux', 'styles.css')
+  const hasCss = await collectCss(outDir, stylesOutFile, true)
+  if (hasCss) console.log('[davaux] Collected CSS into dist/_davaux/styles.css')
+
+  // Copy partial-updates polyfills (self-detecting — no-op when native support lands)
+  try {
+    const r = createRequire(import.meta.url)
+    const templateForCjs = r.resolve('template-for-polyfill')
+    const templateForJs = readFileSync(
+      templateForCjs.replace(/template-for-polyfill\.cjs$/, 'template-for-polyfill.js'),
+      'utf-8',
+    )
+    const htmlSettersMain = r.resolve('html-setters-polyfill')
+    const htmlSettersJs = readFileSync(
+      htmlSettersMain.replace(/index\.js$/, 'index.min.js'),
+      'utf-8',
+    )
+    writeFileSync(
+      resolve(cwd, 'dist', '_davaux', 'partial-updates.js'),
+      `${templateForJs}\n${htmlSettersJs}`,
+    )
+  } catch {
+    console.warn('[davaux] Could not copy partial-updates polyfills — install template-for-polyfill and html-setters-polyfill if you use ctx.defer()')
+  }
+
+  // Compile server.ts if present — enables custom server entry (HTTPS, clustering, etc.)
+  const serverSrc = resolve(cwd, 'server.ts')
+  if (existsSync(serverSrc)) {
+    await build({
+      entryPoints: [serverSrc],
+      outfile: resolve(outDir, 'server.js'),
+      format: 'esm',
+      platform: 'node',
+      target: 'node22',
+      bundle: true,
+      external: [...serverExternal, 'davaux/*'],
+      sourcemap: true,
+    }).catch((err) => handleBuildError('Server entry build', err))
+    console.log('[davaux] Built server.ts → dist/server.js')
+  }
+}
+
+// ─── Static ───────────────────────────────────────────────────────────────────
+
+async function runStatic() {
+  loadEnv(cwd)
+  await runBuild()
+
+  const { generateStatic } = await import('./ssg.js')
+  const { scanRoutes } = await import('./router/scanner.js')
+  const { loadConfig } = await import('./build/config.js')
+  const config = await loadConfig(cwd)
+
+  const distDir = resolve(cwd, 'dist')
+  const publicDir = resolve(cwd, 'public')
+  const outDir = resolve(cwd, getFlag('--out', args) ?? config.ssg?.outDir ?? 'out')
+
+  const islandsFile = resolve(distDir, '_davaux', 'islands.js')
+  const clientFile = resolve(distDir, '_davaux', 'client.js')
+  const stylesFile = resolve(distDir, '_davaux', 'styles.css')
+
+  const clientScripts: string[] = []
+  if (existsSync(islandsFile)) clientScripts.push('/_davaux/islands.js')
+  if (existsSync(clientFile)) clientScripts.push('/_davaux/client.js')
+
+  const clientStylesheets: string[] = []
+  if (existsSync(stylesFile)) clientStylesheets.push('/_davaux/styles.css')
+
+  const scan = await scanRoutes(distDir)
+
+  const middlewareDist = resolve(distDir, 'middleware.js')
+  await generateStatic({
+    outDir,
+    distDir,
+    publicDir,
+    scan,
+    clientScripts,
+    clientStylesheets,
+    appMiddlewarePath: existsSync(middlewareDist) ? middlewareDist : undefined,
+    trailingSlash: config.ssg?.trailingSlash,
+    basePath: config.ssg?.basePath,
+    notFound: config.ssg?.notFound,
+    sitemap: config.ssg?.sitemap,
+  })
+}
+
+// ─── Preview ─────────────────────────────────────────────────────────────────
+
+async function runPreview() {
+  const { loadConfig } = await import('./build/config.js')
+  const config = await loadConfig(cwd)
+  const outDir = resolve(cwd, getFlag('--dir', args) ?? config.ssg?.outDir ?? 'out')
+  const port = Number(getFlag('--port', args) ?? config.server?.port ?? 4173)
+  const hostname = getFlag('--hostname', args) ?? 'localhost'
+
+  if (!existsSync(outDir)) {
+    console.error(`[davaux] Preview directory not found: ${outDir}`)
+    console.error('  Run "davaux static" first to generate the output.')
+    process.exit(1)
+  }
+
+  function serveFile(
+    res: import('node:http').ServerResponse,
+    filePath: string,
+    status = 200,
+  ): boolean {
+    if (existsSync(filePath) && statSync(filePath).isFile()) {
+      res.writeHead(status, {
+        'Content-Type': MIME[extname(filePath)] ?? 'application/octet-stream',
+      })
+      createReadStream(filePath).pipe(res)
+      return true
+    }
+    return false
+  }
+
+  const server = createServer((req, res) => {
+    const pathname = new URL(req.url ?? '/', 'http://x').pathname
+    const safePath = join(outDir, pathname)
+
+    if (!safePath.startsWith(`${outDir}/`) && safePath !== outDir) {
+      res.writeHead(403, { 'Content-Type': 'text/plain' })
+      res.end('Forbidden')
+      return
+    }
+
+    if (serveFile(res, safePath)) return
+    if (serveFile(res, join(safePath, 'index.html'))) return
+
+    const notFoundPage = join(outDir, '404.html')
+    if (serveFile(res, notFoundPage, 404)) return
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' })
+    res.end('Not found')
+  })
+
+  server.listen(port, hostname, () => {
+    console.log(`\n  davaux preview  http://${hostname}:${port}`)
+    console.log(`  Serving: ${outDir}\n`)
+  })
+}
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const MIME: Record<string, string> = {
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.html': 'text/html',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+}
+
+async function runStart() {
+  loadEnv(cwd)
+  const distDir = resolve(cwd, 'dist')
+  const publicDir = resolve(cwd, 'public')
+  const islandsFile = resolve(cwd, 'dist', '_davaux', 'islands.js')
+  const clientFile = resolve(cwd, 'dist', '_davaux', 'client.js')
+  const polyfillFile = resolve(cwd, 'dist', '_davaux', 'partial-updates.js')
+
+  const { loadConfig } = await import('./build/config.js')
+  const { scanRoutes } = await import('./router/scanner.js')
+  const { buildApp } = await import('./router/handler.js')
+  const { startServer } = await import('./server/index.js')
+
+  const [config, scanResult] = await Promise.all([loadConfig(cwd), scanRoutes(distDir)])
+
+  const stylesFile = resolve(cwd, 'dist', '_davaux', 'styles.css')
+  const middlewareDist = resolve(distDir, 'middleware.js')
+  const clientScripts: string[] = []
+  if (existsSync(islandsFile)) clientScripts.push('/_davaux/islands.js')
+  if (existsSync(clientFile)) clientScripts.push('/_davaux/client.js')
+  const clientStylesheets: string[] = []
+  if (existsSync(stylesFile)) clientStylesheets.push('/_davaux/styles.css')
+
+  const app = buildApp(
+    scanResult,
+    false,
+    clientScripts,
+    clientStylesheets,
+    existsSync(middlewareDist) ? middlewareDist : undefined,
+    '',
+    false,
+    config.oml?.cache,
+  )
+
+  const serveStatics = (req: IncomingMessage, res: ServerResponse): Promise<boolean> => {
+    const path = req.url?.split('?')[0] ?? '/'
+
+    if (path === '/_davaux/styles.css' && existsSync(stylesFile)) {
+      res.writeHead(200, { 'Content-Type': 'text/css' })
+      createReadStream(stylesFile).pipe(res)
+      return Promise.resolve(true)
+    }
+
+    if (path === '/_davaux/islands.js' && existsSync(islandsFile)) {
+      res.writeHead(200, { 'Content-Type': 'application/javascript' })
+      createReadStream(islandsFile).pipe(res)
+      return Promise.resolve(true)
+    }
+
+    if (path === '/_davaux/client.js' && existsSync(clientFile)) {
+      res.writeHead(200, { 'Content-Type': 'application/javascript' })
+      createReadStream(clientFile).pipe(res)
+      return Promise.resolve(true)
+    }
+
+    if (path === '/_davaux/partial-updates.js' && existsSync(polyfillFile)) {
+      res.writeHead(200, { 'Content-Type': 'application/javascript' })
+      createReadStream(polyfillFile).pipe(res)
+      return Promise.resolve(true)
+    }
+
+    if (existsSync(publicDir)) {
+      const filePath = join(publicDir, new URL(path, 'http://x').pathname)
+      if (
+        (filePath.startsWith(`${publicDir}/`) || filePath === publicDir) &&
+        existsSync(filePath) &&
+        statSync(filePath).isFile()
+      ) {
+        res.writeHead(200, {
+          'Content-Type': MIME[extname(filePath)] ?? 'application/octet-stream',
+        })
+        createReadStream(filePath).pipe(res)
+        return Promise.resolve(true)
+      }
+    }
+
+    return Promise.resolve(false)
+  }
+
+  const serverDist = resolve(distDir, 'server.js')
+  if (existsSync(serverDist)) {
+    const serverMod = await import(serverDist)
+    if (typeof serverMod.default !== 'function') {
+      console.error(
+        '[davaux] dist/server.js must export a default function: (app: CompiledApp, serveStatics) => void',
+      )
+      process.exit(1)
+    }
+    await serverMod.default(app, serveStatics)
+  } else {
+    startServer(app, {
+      port: Number(getFlag('--port', args) ?? config.server?.port ?? 3000),
+      hostname: getFlag('--hostname', args) ?? config.server?.hostname ?? 'localhost',
+      onRequest: serveStatics,
+    })
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function getFlag(name: string, argv: string[]): string | undefined {
+  const idx = argv.indexOf(name)
+  return idx !== -1 ? argv[idx + 1] : undefined
+}
+
+function loadEnv(cwd: string): void {
+  for (const name of ['.env', '.env.local']) {
+    const filePath = resolve(cwd, name)
+    if (!existsSync(filePath)) continue
+    const content = readFileSync(filePath, 'utf-8')
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eq = trimmed.indexOf('=')
+      if (eq === -1) continue
+      const key = trimmed.slice(0, eq).trim()
+      if (!key) continue
+      let value = trimmed.slice(eq + 1).trim()
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      }
+      if (!(key in process.env)) process.env[key] = value
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,197 @@
+import type { Plugin } from 'esbuild'
+import type { RouteType } from './types.js'
+
+// ─── Plugin API ───────────────────────────────────────────────────────────────
+
+/**
+ * A Davaux plugin — extends the framework with new route file types and/or
+ * esbuild transforms. Implement this interface and return it from a factory
+ * function, then pass it to `plugins` in `davaux.config.ts`.
+ *
+ * @example
+ * // packages/my-plugin/src/index.ts
+ * import type { DavauxPlugin } from 'davaux/config'
+ * export function myPlugin(): DavauxPlugin {
+ *   return {
+ *     name: 'my-plugin',
+ *     esbuild: [myEsbuildPlugin()],
+ *     scanner: { suffixes: [['.page.myext', 'page']] },
+ *   }
+ * }
+ */
+export interface DavauxPlugin {
+  name: string
+  /** esbuild plugins contributed to every build context (server routes, islands, client) */
+  esbuild?: Plugin[]
+  /** Additional route file suffixes the scanner should recognize */
+  scanner?: {
+    suffixes: [suffix: string, type: RouteType][]
+  }
+}
+
+/** Collect esbuild plugins from an array of DavauxPlugins. */
+export function collectEsbuildPlugins(plugins: DavauxPlugin[] = []): Plugin[] {
+  return plugins.flatMap((p) => p.esbuild ?? [])
+}
+
+/** Collect scanner suffix entries from an array of DavauxPlugins. */
+export function collectScannerSuffixes(plugins: DavauxPlugin[] = []): [string, RouteType][] {
+  return plugins.flatMap((p) => p.scanner?.suffixes ?? [])
+}
+
+// ─── User-facing config type ──────────────────────────────────────────────────
+
+export interface EditorConfig {
+  /**
+   * Opt-in to the visual editor and inspector overlay.
+   * Must be explicitly set to `true` — disabled by default so the editor
+   * endpoints and inspector script are never exposed unless intended.
+   */
+  enabled?: boolean
+  /** Floating inspector/editor badge options. */
+  badge?: {
+    /** Corner of the viewport where the badge appears. Default: `'bottom-right'` */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+    /** Custom label text shown on the badge. Default: `'Inspector'` */
+    label?: string
+  }
+  /**
+   * Force a specific colour scheme for the editor UI instead of auto-detecting
+   * from the inspected page's theme attribute.
+   */
+  theme?: 'auto' | 'dark' | 'light'
+  /**
+   * Raw CSS string injected into the editor frame's `<style>` tag.
+   * Use this to override colours, hide elements, or adjust layout.
+   */
+  css?: string
+  /**
+   * Path to a CSS file (relative to the project root) whose contents are
+   * injected into the editor frame. Merged with `css` if both are provided.
+   * The file is re-read on each request in dev mode, so changes apply without a restart.
+   */
+  cssFile?: string
+}
+
+export interface DavauxConfig {
+  /** Server defaults for `davaux dev`, `davaux start`, and `davaux preview`. CLI flags (--port, --hostname) take priority over these. */
+  server?: {
+    port?: number
+    hostname?: string
+  }
+  /**
+   * Import path aliases, using the same glob syntax as `tsconfig.json` `paths`.
+   * Each entry is forwarded to esbuild `alias` in every build context so TypeScript
+   * and the bundler stay in sync without any extra plugin.
+   *
+   * @example
+   * import { defineConfig } from 'davaux/config'
+   * export default defineConfig({
+   *   paths: { '@/*': './src/*' },
+   * })
+   */
+  paths?: Record<string, string>
+  /**
+   * Davaux plugins — each plugin can contribute esbuild transforms and/or
+   * register new route file extensions with the scanner.
+   *
+   * @example
+   * import { defineConfig } from 'davaux/config'
+   * import { markdown } from '@davaux/markdown'
+   * export default defineConfig({
+   *   plugins: [markdown()],
+   * })
+   */
+  plugins?: DavauxPlugin[]
+  /**
+   * Additional packages to exclude from esbuild bundling. Useful for packages
+   * that use native bindings or CJS `require()` that cannot be bundled into ESM.
+   * Each entry is added to the esbuild `external` list alongside `node:*` and `davaux`.
+   *
+   * @example
+   * import { defineConfig } from 'davaux/config'
+   * export default defineConfig({
+   *   external: ['@libsql/client', 'libsql'],
+   * })
+   */
+  external?: string[]
+  /** Visual editor and inspector overlay configuration. Disabled by default — set `enabled: true` to opt in. */
+  editor?: EditorConfig
+  /**
+   * OML (Object Markup Language) options. OML is the intermediate representation
+   * used by the visual editor and production page caching.
+   */
+  oml?: {
+    /**
+     * Control which routes use OML tree construction and result caching in production.
+     * By default no routes are cached — this must be explicitly configured.
+     *
+     * Use `include` for apps that are mostly dynamic with a few cacheable routes,
+     * or `exclude` for apps that are mostly static with a few dynamic routes.
+     * Routes not covered by the cache config use the string renderer directly in
+     * production — no OML tree is built and no result is stored.
+     *
+     * @example
+     * // Whitelist — only these routes are cached
+     * oml: { cache: { include: ['/', '/blog/:slug', '/docs/*'] } }
+     *
+     * // Blacklist — all routes cached except these
+     * oml: { cache: { exclude: ['/dashboard', '/account/*'] } }
+     */
+    cache?: OmlCacheConfig
+  }
+  /** Options that only apply to `davaux static` (static site generation). */
+  ssg?: {
+    /**
+     * Override the default `out/` output directory.
+     * The `--out` CLI flag takes priority over this value.
+     */
+    outDir?: string
+    /**
+     * Trailing slash behaviour for generated output files.
+     * - `'always'` (default) — `/about` → `out/about/index.html` (served as `/about/`)
+     * - `'never'` — `/about` → `out/about.html` (served as `/about`)
+     */
+    trailingSlash?: 'always' | 'never'
+    /**
+     * Path prefix for subdirectory deployments (e.g. `'/docs'` for GitHub Pages
+     * at `user.github.io/my-project/`). Prepended to all injected `/_davaux/*`
+     * script and stylesheet URLs in the generated HTML.
+     */
+    basePath?: string
+    /**
+     * Generate a `404.html` at the root of `outDir` for static hosts
+     * (Netlify, GitHub Pages) that serve it on unmatched paths.
+     * Defaults to `true` when an `_error.tsx` exists in the routes directory.
+     */
+    notFound?: boolean
+    /**
+     * Auto-generate a `sitemap.xml` from all rendered routes.
+     * Pass `{ baseUrl: 'https://example.com' }` to enable.
+     * Pass `false` to explicitly disable.
+     */
+    sitemap?: false | { baseUrl: string }
+  }
+}
+
+/**
+ * Convert tsconfig-style `paths` glob entries to esbuild `alias` entries.
+ * `'@/*': './src/*'` → `'@': './src'`
+ */
+export function pathsToAlias(paths: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(paths).map(([k, v]) => [k.replace(/\/\*$/, ''), v.replace(/\/\*$/, '')]),
+  )
+}
+
+/**
+ * Controls which routes use OML tree construction and caching in production.
+ * Use `include` to whitelist specific URL patterns, or `exclude` to blacklist them.
+ * Patterns support `:param` (single dynamic segment) and `*` (any characters).
+ */
+export type OmlCacheConfig = { include: string[] } | { exclude: string[] }
+
+/** Wraps a config object for TypeScript inference — returns it unchanged. */
+export function defineConfig(config: DavauxConfig): DavauxConfig {
+  return config
+}