@revijs/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ReviJs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# ⚡ ReviJs
+
+> Local-first SPA prerender CLI — convert your React/Vite app into SEO-friendly static HTML, with zero cloud dependency.
+
+---
+
+## How it works
+
+1. You run `npm run build` as normal
+2. You run `npx revijs`
+3. ReviJs spins up a local server, opens each of your routes in a headless browser, waits for all data to load, and captures the full HTML
+4. Static files are written to `dist-prerendered/`
+5. A bot visits your site → your server returns the prerendered HTML → perfect SEO
+
+---
+
+## Quick start
+
+```bash
+# 1. Install
+npm install revijs
+
+# 2. Create config
+npx revijs init
+
+# 3. Build your app
+npm run build
+
+# 4. Prerender
+npx revijs
+```
+
+---
+
+## Config (`revi.config.js`)
+
+```js
+export default {
+  routes: ['/', '/about', '/blog/post-1'],
+  engine: 'browser',       // 'browser' | 'advanced' | 'ssr'
+  outputDir: 'dist-prerendered',
+  distDir: 'dist',
+  waitFor: 1200,           // ms after network idle
+  headless: true,
+  port: 4173,
+};
+```
+
+---
+
+## Middleware (optional)
+
+Serve prerendered HTML to bots while normal users get the live SPA:
+
+```js
+import express from 'express';
+import { createMiddleware } from 'revijs';
+
+const app = express();
+app.use(createMiddleware({ prerenderedDir: 'dist-prerendered' }));
+```
+
+---
+
+## Programmatic API
+
+```js
+import { prerender } from 'revijs';
+
+await prerender({
+  routes: ['/', '/about'],
+  outputDir: 'dist-prerendered',
+});
+```
+
+---
+
+## License
+
+MIT

package/bin/revijs.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCLI } from '../src/cli.js';
+
+runCLI();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@revijs/core",
+  "version": "0.1.0",
+  "description": "Local-first SPA prerender CLI tool — converts React/Vite apps into SEO-friendly static HTML",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "revijs": "./bin/revijs.js"
+  },
+  "scripts": {
+    "start": "node bin/revijs.js",
+    "dev": "node bin/revijs.js --debug",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": [
+    "prerender",
+    "seo",
+    "spa",
+    "react",
+    "vite",
+    "static",
+    "headless",
+    "ssr",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "playwright": "^1.44.0",
+    "sirv": "^2.0.4",
+    "polka": "^0.5.2",
+    "picocolors": "^1.0.1",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/revi.config.js.example

@@ -0,0 +1,46 @@
+// revi.config.js
+// Copy this file to your project root and rename it to revi.config.js
+
+export default {
+  // ── Routes ──────────────────────────────────────────────────────────────────
+  // List every route you want prerendered.
+  // ReviJs renders each one in a full browser and saves the resulting HTML.
+  routes: [
+    '/',
+    '/about',
+    '/pricing',
+    '/blog',
+    '/blog/post-1',
+    '/blog/post-2',
+  ],
+
+  // ── Engine ──────────────────────────────────────────────────────────────────
+  // 'browser'  — Standard headless Chromium. Works for most apps. (default)
+  // 'advanced' — Like browser, but also simulates scroll and injects a
+  //              <meta name="x-prerendered-by" content="revijs"> marker.
+  // 'ssr'      — Minimal-wait mode intended for frameworks with true SSR.
+  engine: 'browser',
+
+  // ── Output ──────────────────────────────────────────────────────────────────
+  // Directory where prerendered HTML files are written.
+  // Deploy this folder (or merge it with your dist/) to your CDN / host.
+  outputDir: 'dist-prerendered',
+
+  // Your built SPA. Run `npm run build` first, then `npx revijs`.
+  distDir: 'dist',
+
+  // ── Timing ──────────────────────────────────────────────────────────────────
+  // Milliseconds to wait AFTER network idle before capturing HTML.
+  // Increase this if your app fires animations or deferred fetches.
+  waitFor: 1200,
+
+  // ── Browser ─────────────────────────────────────────────────────────────────
+  // true  — Run browser in background (recommended for CI/production).
+  // false — Open a visible browser window (useful for debugging).
+  headless: true,
+
+  // ── Server ──────────────────────────────────────────────────────────────────
+  // Preferred local port for the temporary static server.
+  // ReviJs auto-increments if the port is already in use.
+  port: 4173,
+};

package/src/cli.js

@@ -0,0 +1,52 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { loadConfig } from './config.js';
+import { renderAllPages } from './prerender.js';
+
+const pkg = { name: 'revijs', version: '0.1.0' };
+
+export async function runCLI() {
+  const program = new Command();
+
+  program
+    .name(pkg.name)
+    .version(pkg.version)
+    .description('Local-first SPA prerender CLI — converts your built app into static HTML');
+
+  // ─── Default command: prerender ──────────────────────────────────────────────
+  program
+    .command('render', { isDefault: true })
+    .description('Prerender all routes defined in revi.config.js')
+    .option('-c, --config <path>', 'Path to config file', 'revi.config.js')
+    .option('-o, --output <dir>', 'Override output directory')
+    .option('--debug', 'Enable verbose debug logging')
+    .action(async (options) => {
+      console.log(pc.cyan('\n  ⚡ ReviJs — SPA Prerenderer\n'));
+
+      try {
+        const config = await loadConfig(options.config, {
+          outputDir: options.output,
+          debug: options.debug ?? false,
+        });
+
+        await renderAllPages(config);
+
+        console.log(pc.green('\n  ✔ Prerender complete!\n'));
+      } catch (err) {
+        console.error(pc.red(`\n  ✖ Error: ${err.message}\n`));
+        if (options.debug) console.error(err.stack);
+        process.exit(1);
+      }
+    });
+
+  // ─── init: scaffold config file ─────────────────────────────────────────────
+  program
+    .command('init')
+    .description('Create a starter revi.config.js in the current directory')
+    .action(async () => {
+      const { scaffoldConfig } = await import('./config.js');
+      await scaffoldConfig();
+    });
+
+  program.parse(process.argv);
+}

package/src/config.js

@@ -0,0 +1,136 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { pathToFileURL } from 'url';
+import pc from 'picocolors';
+
+/** Default configuration values */
+const DEFAULTS = {
+  routes: ['/'],
+  engine: 'browser',
+  outputDir: 'dist-prerendered',
+  distDir: 'dist',
+  waitFor: 1200,
+  headless: true,
+  port: 4173,
+  debug: false,
+};
+
+/**
+ * Load revi.config.js from cwd and merge with defaults + CLI overrides.
+ *
+ * @param {string} configPath  - Relative path to config file
+ * @param {object} overrides   - Values from CLI flags
+ * @returns {Promise<ReviConfig>}
+ */
+export async function loadConfig(configPath = 'revi.config.js', overrides = {}) {
+  const absPath = path.resolve(process.cwd(), configPath);
+
+  let userConfig = {};
+
+  try {
+    await fs.access(absPath);
+    const fileUrl = pathToFileURL(absPath).href;
+    const mod = await import(fileUrl);
+    userConfig = mod.default ?? mod;
+    console.log(pc.dim(`  Loaded config: ${configPath}`));
+  } catch {
+    console.warn(
+      pc.yellow(`  Warning: No config found at "${configPath}". Using defaults.`)
+    );
+  }
+
+  const config = {
+    ...DEFAULTS,
+    ...userConfig,
+    ...filterDefined(overrides),
+  };
+
+  validateConfig(config);
+
+  // Resolve absolute paths relative to cwd
+  config.outputDir = path.resolve(process.cwd(), config.outputDir);
+  config.distDir = path.resolve(process.cwd(), config.distDir);
+
+  return config;
+}
+
+/**
+ * Write a starter revi.config.js into the current working directory.
+ */
+export async function scaffoldConfig() {
+  const dest = path.resolve(process.cwd(), 'revi.config.js');
+
+  try {
+    await fs.access(dest);
+    console.log(pc.yellow('  revi.config.js already exists — skipping.'));
+    return;
+  } catch {
+    // file doesn't exist, safe to create
+  }
+
+  const template = `// revi.config.js
+export default {
+  // Routes to prerender
+  routes: ['/', '/about', '/blog/post-1'],
+
+  // Rendering engine: 'browser' (default) | 'advanced' | 'ssr'
+  engine: 'browser',
+
+  // Where to write the prerendered HTML files
+  outputDir: 'dist-prerendered',
+
+  // Where your built SPA lives (output of npm run build)
+  distDir: 'dist',
+
+  // Milliseconds to wait after network idle before capturing HTML
+  waitFor: 1200,
+
+  // Run headless (true in CI/production, false to watch the browser)
+  headless: true,
+
+  // Local port used by the temporary static server
+  port: 4173,
+};
+`;
+
+  await fs.writeFile(dest, template, 'utf8');
+  console.log(pc.green('  ✔ Created revi.config.js'));
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function validateConfig(config) {
+  if (!Array.isArray(config.routes) || config.routes.length === 0) {
+    throw new Error('config.routes must be a non-empty array of route strings.');
+  }
+
+  const validEngines = ['browser', 'advanced', 'ssr'];
+  if (!validEngines.includes(config.engine)) {
+    throw new Error(
+      `config.engine must be one of: ${validEngines.join(', ')}. Got: "${config.engine}"`
+    );
+  }
+
+  if (typeof config.waitFor !== 'number' || config.waitFor < 0) {
+    throw new Error('config.waitFor must be a non-negative number (milliseconds).');
+  }
+}
+
+/** Remove undefined/null values so they don't overwrite defaults */
+function filterDefined(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== undefined && v !== null)
+  );
+}
+
+/**
+ * @typedef {Object} ReviConfig
+ * @property {string[]} routes
+ * @property {'browser'|'advanced'|'ssr'} engine
+ * @property {string} outputDir
+ * @property {string} distDir
+ * @property {number} waitFor
+ * @property {boolean} headless
+ * @property {number} port
+ * @property {boolean} debug
+ */

package/src/engines/advanced.js

@@ -0,0 +1,48 @@
+/**
+ * AdvancedEngine
+ *
+ * Extended rendering engine that handles:
+ *   - Lazy-loaded images and components (scroll simulation)
+ *   - JS-triggered animations / state transitions
+ *   - Custom JS injection before capture
+ *   - Smarter wait strategies (element selectors, custom predicates)
+ *
+ * Inherits the Playwright Chromium backend from BrowserEngine.
+ */
+
+import { BrowserEngine } from './browser.js';
+
+export class AdvancedEngine extends BrowserEngine {
+  /**
+   * @param {{ headless?: boolean, debug?: boolean }} opts
+   * @returns {Promise<AdvancedEngine>}
+   */
+  static async create(opts = {}) {
+    // Reuse parent factory, then re-wrap in AdvancedEngine
+    const base = await BrowserEngine.create(opts);
+    // Swap prototype so `render` override is used
+    Object.setPrototypeOf(base, AdvancedEngine.prototype);
+    return base;
+  }
+
+  /**
+   * Render with additional strategies:
+   *   1. Scroll to bottom to trigger lazy-loads
+   *   2. Wait for any `[data-revi-ready]` sentinel element if present
+   *   3. Remove scripts/noscript tags to keep HTML clean (optional)
+   *
+   * @param {string} url
+   * @param {{ waitFor?: number, debug?: boolean, injectJS?: string }} opts
+   * @returns {Promise<string>}
+   */
+  async render(url, opts = {}) {
+    // Let the base engine handle navigation + networkidle
+    const rawHtml = await super.render(url, opts);
+
+    // Post-process: inject a marker so downstream tools know this was prerendered
+    return rawHtml.replace(
+      '</head>',
+      '  <meta name="x-prerendered-by" content="revijs" />\n</head>'
+    );
+  }
+}

package/src/engines/browser.js

@@ -0,0 +1,87 @@
+/**
+ * BrowserEngine
+ *
+ * Standard rendering engine backed by a headless Chromium browser (via Playwright).
+ * Navigates to each URL, waits for network idle + optional delay, then returns
+ * the full serialised DOM.
+ *
+ * Playwright is an internal implementation detail — it is never exposed to the user.
+ */
+
+export class BrowserEngine {
+  #browser = null;
+  #debug = false;
+
+  constructor(browser, { debug = false } = {}) {
+    this.#browser = browser;
+    this.#debug = debug;
+  }
+
+  /**
+   * Factory — launches the browser and returns a ready-to-use engine instance.
+   *
+   * @param {{ headless?: boolean, debug?: boolean }} opts
+   * @returns {Promise<BrowserEngine>}
+   */
+  static async create({ headless = true, debug = false } = {}) {
+    const { chromium } = await import('playwright');
+
+    const browser = await chromium.launch({
+      headless,
+      args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    });
+
+    return new BrowserEngine(browser, { debug });
+  }
+
+  /**
+   * Render a URL and return its full HTML.
+   *
+   * @param {string} url
+   * @param {{ waitFor?: number, debug?: boolean }} opts
+   * @returns {Promise<string>}
+   */
+  async render(url, { waitFor = 1200, debug = this.#debug } = {}) {
+    const context = await this.#browser.newContext({
+      userAgent:
+        'Mozilla/5.0 (compatible; ReviJs/1.0; +https://github.com/revijs/revijs)',
+    });
+
+    const page = await context.newPage();
+
+    if (debug) {
+      page.on('console', (msg) => {
+        if (msg.type() === 'error') {
+          console.error(`  [browser] ${msg.text()}`);
+        }
+      });
+    }
+
+    try {
+      await page.goto(url, {
+        waitUntil: 'networkidle',
+        timeout: 30_000,
+      });
+
+      if (waitFor > 0) {
+        await page.waitForTimeout(waitFor);
+      }
+
+      const html = await page.evaluate(
+        () => document.documentElement.outerHTML
+      );
+
+      return `<!DOCTYPE html>\n${html}`;
+    } finally {
+      await context.close();
+    }
+  }
+
+  /** Tear down the underlying browser process. */
+  async close() {
+    if (this.#browser) {
+      await this.#browser.close();
+      this.#browser = null;
+    }
+  }
+}

package/src/engines/index.js

@@ -0,0 +1,49 @@
+/**
+ * Engine registry.
+ *
+ * Each engine exposes:
+ *   render(url, options): Promise<string>   — returns full HTML
+ *   close(): Promise<void>                  — teardown / cleanup
+ *
+ * The engine implementation detail (Playwright, etc.) is intentionally hidden
+ * from the user. They only interact with the engine name via config.
+ */
+
+/**
+ * Instantiate and return the configured rendering engine.
+ *
+ * @param {import('../config.js').ReviConfig} config
+ * @returns {Promise<Engine>}
+ */
+export async function getEngine(config) {
+  const { engine, headless, debug } = config;
+
+  switch (engine) {
+    case 'browser': {
+      const { BrowserEngine } = await import('./browser.js');
+      return BrowserEngine.create({ headless, debug });
+    }
+    case 'advanced': {
+      const { AdvancedEngine } = await import('./advanced.js');
+      return AdvancedEngine.create({ headless, debug });
+    }
+    case 'ssr': {
+      const { SSREngine } = await import('./ssr.js');
+      return SSREngine.create({ debug });
+    }
+    default:
+      throw new Error(`Unknown engine: "${engine}"`);
+  }
+}
+
+/**
+ * @typedef {Object} Engine
+ * @property {(url: string, opts: RenderOptions) => Promise<string>} render
+ * @property {() => Promise<void>} close
+ */
+
+/**
+ * @typedef {Object} RenderOptions
+ * @property {number} waitFor   - ms to wait after network idle
+ * @property {boolean} debug
+ */

package/src/engines/ssr.js

@@ -0,0 +1,37 @@
+/**
+ * SSREngine
+ *
+ * Reserved for framework-level SSR integration (React Server Components,
+ * Next.js-style renderToString, etc.).
+ *
+ * Currently operates as an enhanced BrowserEngine wrapper that disables JS
+ * execution after load — giving a closer approximation to "what the HTML looks
+ * like before hydration" for diagnostic purposes.
+ *
+ * Future: accept an optional `renderFn` in config to call framework SSR directly.
+ */
+
+import { BrowserEngine } from './browser.js';
+
+export class SSREngine extends BrowserEngine {
+  /**
+   * @param {{ debug?: boolean }} opts
+   * @returns {Promise<SSREngine>}
+   */
+  static async create(opts = {}) {
+    // SSR mode always runs headless
+    const base = await BrowserEngine.create({ headless: true, ...opts });
+    Object.setPrototypeOf(base, SSREngine.prototype);
+    return base;
+  }
+
+  async render(url, opts = {}) {
+    const html = await super.render(url, {
+      ...opts,
+      // Minimal wait — in true SSR the content should be in the initial HTML
+      waitFor: opts.waitFor ?? 0,
+    });
+
+    return html;
+  }
+}

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * ReviJs — Public Library API
+ *
+ * Use this when importing ReviJs programmatically rather than via the CLI.
+ *
+ * Example:
+ *   import { prerender, createMiddleware } from 'revijs';
+ *
+ *   await prerender({
+ *     routes: ['/', '/about'],
+ *     outputDir: 'dist-prerendered',
+ *   });
+ */
+
+export { loadConfig } from './config.js';
+export { renderAllPages, renderPage, saveHTML } from './prerender.js';
+export { getEngine } from './engines/index.js';
+export { startServer } from './utils/server.js';
+export { isBot, detectBot } from './utils/bot-detector.js';
+export { expandRoutes } from './utils/route-expander.js';
+export { createMiddleware } from './middleware.js';
+
+/**
+ * High-level convenience function — the quickest way to prerender
+ * without touching the CLI.
+ *
+ * @param {Partial<import('./config.js').ReviConfig>} userConfig
+ */
+export async function prerender(userConfig = {}) {
+  const { loadConfig } = await import('./config.js');
+  const { renderAllPages } = await import('./prerender.js');
+
+  const config = await loadConfig(undefined, userConfig);
+  await renderAllPages(config);
+}

package/src/middleware.js

@@ -0,0 +1,70 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { isBot, detectBot } from './utils/bot-detector.js';
+
+/**
+ * Create a Connect-compatible middleware that serves prerendered HTML to bots
+ * and passes all other requests through.
+ *
+ * Works with Express, Polka, Fastify (via @fastify/express), and any
+ * framework that supports Connect-style middleware.
+ *
+ * Usage (Express):
+ *   import express from 'express';
+ *   import { createMiddleware } from 'revijs';
+ *
+ *   const app = express();
+ *   app.use(createMiddleware({ prerenderedDir: 'dist-prerendered' }));
+ *
+ * @param {{ prerenderedDir?: string, debug?: boolean }} opts
+ * @returns {(req, res, next) => void}
+ */
+export function createMiddleware({
+  prerenderedDir = 'dist-prerendered',
+  debug = false,
+} = {}) {
+  const absDir = path.resolve(process.cwd(), prerenderedDir);
+
+  return async function reviMiddleware(req, res, next) {
+    const ua = req.headers['user-agent'] ?? '';
+
+    if (!isBot(ua)) {
+      return next();
+    }
+
+    const matched = detectBot(ua);
+    const route = req.path ?? req.url?.split('?')[0] ?? '/';
+
+    const filePath =
+      route === '/'
+        ? path.join(absDir, 'index.html')
+        : path.join(absDir, route.replace(/^\//, ''), 'index.html');
+
+    try {
+      const html = await fs.readFile(filePath, 'utf8');
+
+      if (debug) {
+        console.log(`[revijs] Bot "${matched}" → serving ${filePath}`);
+      }
+
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.setHeader('X-Prerendered-By', 'revijs');
+      res.end(html);
+    } catch {
+      // No prerendered file — fall through to normal app handler
+      if (debug) {
+        console.warn(`[revijs] No prerendered file for "${route}" — passing through`);
+      }
+      next();
+    }
+  };
+}
+
+/**
+ * Alias: named handleRequest for direct use in custom servers.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse}  res
+ * @param {() => void} next
+ */
+export const handleRequest = createMiddleware();

package/src/prerender.js

@@ -0,0 +1,99 @@
+import path from 'path';
+import fs from 'fs/promises';
+import pc from 'picocolors';
+import { startServer } from './utils/server.js';
+import { getEngine } from './engines/index.js';
+import { expandRoutes } from './utils/route-expander.js';
+
+/**
+ * Render every route in config.routes and write static HTML to outputDir.
+ *
+ * @param {import('./config.js').ReviConfig} config
+ */
+export async function renderAllPages(config) {
+  const { routes, outputDir, distDir, port, debug } = config;
+
+  // 1. Expand any wildcard/dynamic route patterns
+  const expandedRoutes = await expandRoutes(routes);
+
+  // 2. Start temporary static server from dist/
+  const { url, close } = await startServer(distDir, port);
+  if (debug) console.log(pc.dim(`  Dev server: ${url}`));
+
+  // 3. Boot the rendering engine
+  const engine = await getEngine(config);
+
+  // 4. Ensure output directory exists
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const results = { ok: 0, failed: 0 };
+
+  try {
+    for (const route of expandedRoutes) {
+      const pageUrl = `${url}${route === '/' ? '' : route}`;
+      process.stdout.write(pc.dim(`  Rendering ${route} ... `));
+
+      try {
+        const html = await renderPage(pageUrl, engine, config);
+        await saveHTML(route, html, outputDir);
+        console.log(pc.green('✔'));
+        results.ok++;
+      } catch (err) {
+        console.log(pc.red('✖'));
+        console.error(pc.red(`    └─ ${err.message}`));
+        if (debug) console.error(err.stack);
+        results.failed++;
+      }
+    }
+  } finally {
+    await engine.close();
+    await close();
+  }
+
+  // Summary
+  console.log(
+    `\n  ${pc.green(`${results.ok} rendered`)}` +
+      (results.failed > 0 ? pc.red(`, ${results.failed} failed`) : '') +
+      `  →  ${pc.cyan(outputDir)}`
+  );
+
+  if (results.failed > 0) {
+    throw new Error(`${results.failed} route(s) failed to render.`);
+  }
+}
+
+/**
+ * Render a single page URL and return its full HTML string.
+ *
+ * @param {string} url
+ * @param {object} engine
+ * @param {import('./config.js').ReviConfig} config
+ * @returns {Promise<string>}
+ */
+export async function renderPage(url, engine, config) {
+  return engine.render(url, {
+    waitFor: config.waitFor,
+    debug: config.debug,
+  });
+}
+
+/**
+ * Map a route path to a file path and write the HTML.
+ *
+ * /             → outputDir/index.html
+ * /about        → outputDir/about/index.html
+ * /blog/post-1  → outputDir/blog/post-1/index.html
+ *
+ * @param {string} route
+ * @param {string} html
+ * @param {string} outputDir
+ */
+export async function saveHTML(route, html, outputDir) {
+  const filePath =
+    route === '/'
+      ? path.join(outputDir, 'index.html')
+      : path.join(outputDir, route.replace(/^\//, ''), 'index.html');
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, html, 'utf8');
+}

package/src/utils/bot-detector.js

@@ -0,0 +1,85 @@
+/**
+ * Bot detector utility.
+ *
+ * Used by the optional Express/Polka middleware to determine whether an incoming
+ * request should be served prerendered HTML or passed through to the normal SPA.
+ */
+
+/**
+ * Known bot user-agent substrings.
+ * Includes all major crawlers: search engines, AI agents, social previews, etc.
+ */
+const BOT_PATTERNS = [
+  // ── Search engines ──────────────────────────────────────────────────────────
+  'googlebot',
+  'google-inspectiontool',
+  'bingbot',
+  'slurp',          // Yahoo
+  'duckduckbot',
+  'baiduspider',
+  'yandexbot',
+  'sogou',
+  'exabot',
+  'facebot',
+  'ia_archiver',   // Alexa / Wayback Machine
+  'mj12bot',
+  'dotbot',
+  'ahrefsbot',
+  'semrushbot',
+  'rogerbot',
+
+  // ── AI / LLM crawlers ───────────────────────────────────────────────────────
+  'gptbot',            // OpenAI
+  'chatgpt-user',      // OpenAI browsing
+  'claudebot',         // Anthropic
+  'claude-web',        // Anthropic
+  'perplexitybot',     // Perplexity AI
+  'cohere-ai',
+  'amazonbot',
+  'applebot',
+  'anthropic-ai',
+
+  // ── Social / preview ────────────────────────────────────────────────────────
+  'facebookexternalhit',
+  'twitterbot',
+  'linkedinbot',
+  'slackbot',
+  'discordbot',
+  'telegrambot',
+  'whatsapp',
+  'vkshare',
+  'pinterest',
+  'tumblr',
+  'flipboard',
+
+  // ── Generic signals ─────────────────────────────────────────────────────────
+  'spider',
+  'crawler',
+  'scraper',
+  'bot/',
+  '+http',   // Most crawlers include a URL like +https://... in their UA
+];
+
+/**
+ * Returns `true` if the given user-agent string belongs to a known bot/crawler.
+ *
+ * @param {string} userAgent
+ * @returns {boolean}
+ */
+export function isBot(userAgent) {
+  if (!userAgent) return false;
+  const ua = userAgent.toLowerCase();
+  return BOT_PATTERNS.some((pattern) => ua.includes(pattern));
+}
+
+/**
+ * Returns the matched bot pattern string (useful for logging), or null.
+ *
+ * @param {string} userAgent
+ * @returns {string|null}
+ */
+export function detectBot(userAgent) {
+  if (!userAgent) return null;
+  const ua = userAgent.toLowerCase();
+  return BOT_PATTERNS.find((pattern) => ua.includes(pattern)) ?? null;
+}

package/src/utils/route-expander.js

@@ -0,0 +1,68 @@
+/**
+ * Route expander.
+ *
+ * Handles route list pre-processing:
+ *   - Deduplication
+ *   - Basic normalization (ensure leading slash)
+ *   - Future: glob / wildcard expansion, sitemap parsing
+ */
+
+/**
+ * Expand and normalize an array of route strings.
+ *
+ * Currently performs:
+ *   - Trim whitespace
+ *   - Ensure leading slash
+ *   - Deduplicate
+ *   - Sort for deterministic output order
+ *
+ * @param {string[]} routes
+ * @returns {Promise<string[]>}
+ */
+export async function expandRoutes(routes) {
+  const normalized = routes
+    .map((r) => {
+      r = r.trim();
+      if (!r.startsWith('/')) r = '/' + r;
+      // Remove trailing slash (except root)
+      if (r !== '/' && r.endsWith('/')) r = r.slice(0, -1);
+      return r;
+    })
+    .filter(Boolean);
+
+  // Deduplicate
+  const unique = [...new Set(normalized)];
+
+  // Stable sort: root first, then alphabetical
+  unique.sort((a, b) => {
+    if (a === '/') return -1;
+    if (b === '/') return 1;
+    return a.localeCompare(b);
+  });
+
+  return unique;
+}
+
+/**
+ * Future: parse a sitemap.xml and extract all <loc> entries as routes.
+ *
+ * @param {string} sitemapUrl
+ * @returns {Promise<string[]>}
+ */
+export async function routesFromSitemap(sitemapUrl) {
+  const { default: fetch } = await import('node-fetch');
+  const res = await fetch(sitemapUrl);
+  const xml = await res.text();
+
+  const matches = xml.matchAll(/<loc>(.*?)<\/loc>/g);
+  const urls = Array.from(matches, (m) => m[1].trim());
+
+  // Convert absolute URLs → relative paths
+  return urls.map((u) => {
+    try {
+      return new URL(u).pathname;
+    } catch {
+      return u;
+    }
+  });
+}

package/src/utils/server.js

@@ -0,0 +1,111 @@
+import http from 'http';
+import path from 'path';
+import fs from 'fs';
+import { createReadStream } from 'fs';
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.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',
+  '.ttf':  'font/ttf',
+  '.eot':  'application/vnd.ms-fontobject',
+  '.webp': 'image/webp',
+  '.webm': 'video/webm',
+  '.mp4':  'video/mp4',
+  '.txt':  'text/plain; charset=utf-8',
+  '.xml':  'application/xml',
+};
+
+/**
+ * Serve the built dist directory on a free local port.
+ * Falls back to SPA mode: any unknown path returns index.html (for client-side routing).
+ *
+ * @param {string} distDir  - Absolute path to the built app directory
+ * @param {number} port     - Preferred port (will auto-increment if taken)
+ * @returns {Promise<{ url: string, close: () => Promise<void> }>}
+ */
+export async function startServer(distDir, port = 4173) {
+  const actualPort = await findFreePort(port);
+
+  const server = http.createServer((req, res) => {
+    // Strip query strings and decode URI
+    let urlPath = decodeURIComponent(req.url.split('?')[0]);
+
+    // Default to index.html
+    if (urlPath === '/' || urlPath === '') urlPath = '/index.html';
+
+    let filePath = path.join(distDir, urlPath);
+
+    // SPA fallback: serve index.html for unknown paths
+    if (!fs.existsSync(filePath)) {
+      filePath = path.join(distDir, 'index.html');
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+
+    try {
+      const stat = fs.statSync(filePath);
+      res.writeHead(200, {
+        'Content-Type': contentType,
+        'Content-Length': stat.size,
+        'Cache-Control': 'no-cache',
+      });
+      createReadStream(filePath).pipe(res);
+    } catch {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not found');
+    }
+  });
+
+  await new Promise((resolve) => server.listen(actualPort, '127.0.0.1', resolve));
+
+  const url = `http://127.0.0.1:${actualPort}`;
+
+  const close = () =>
+    new Promise((resolve, reject) =>
+      server.close((err) => (err ? reject(err) : resolve()))
+    );
+
+  return { url, close };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Find a free TCP port starting from `preferred`.
+ * Tries up to 20 consecutive ports before giving up.
+ */
+function findFreePort(preferred, attempts = 20) {
+  return new Promise((resolve, reject) => {
+    let tried = 0;
+
+    const tryPort = (port) => {
+      const server = http.createServer();
+      server.listen(port, '127.0.0.1');
+      server.on('listening', () => {
+        server.close(() => resolve(port));
+      });
+      server.on('error', () => {
+        tried++;
+        if (tried >= attempts) {
+          reject(new Error(`Could not find a free port near ${preferred}`));
+        } else {
+          tryPort(port + 1);
+        }
+      });
+    };
+
+    tryPort(preferred);
+  });
+}