snappy-prerender 2.6.0-rc.3 → 2.6.0

package/src/core/artifacts.js

@@ -0,0 +1,110 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileIfChanged } from './output.js';
+import { buildPreloadManifest } from './preload-manifest.js';
+import { toPublicPath } from './routes.js';
+import { buildSitemap, withSitemapDirective } from './sitemap.js';
+
+/**
+ * Writes the preload manifest: per route, the scripts and stylesheets the final HTML
+ * references, as Link header values a host can serve for Early Hints or HTTP headers.
+ */
+export async function writePreloadManifest({ manifestEntries, outputDir, config, log, report }) {
+  const manifest = buildPreloadManifest(manifestEntries, {
+    ignoreForPreload: config.ignoreForPreload,
+    base: config.base,
+    flatOutput: config.flatOutput,
+    trailingSlash: config.metadata?.trailingSlash,
+    notFoundRoute: config.notFoundRoute,
+  });
+  const file = 'preload-manifest.json';
+  const contents = `${JSON.stringify(manifest, null, 2)}\n`;
+  if (config.dryRun) {
+    report.files.push({ route: null, file, status: 'dry-run', bytes: Buffer.byteLength(contents) });
+    log.info(`Dry run: would write preload manifest covering ${manifest.length} route(s)`);
+    return { file, routes: manifest.length, status: 'dry-run' };
+  }
+  const written = await writeFileIfChanged({ dir: outputDir, file, contents });
+  report.files.push({ route: null, ...written });
+  log.info(
+    `${written.status === 'unchanged' ? 'Unchanged' : 'Wrote'} preload manifest covering ${manifest.length} route(s)`,
+  );
+  return { file, routes: manifest.length, status: written.status };
+}
+
+/**
+ * Writes sitemap.xml from the routes the run produced, and points an existing robots.txt at
+ * it. Every loc must be absolute, which is why the option needs metadata.siteUrl.
+ */
+export async function writeSitemap({ outputDir, config, log, report }) {
+  if (config.saveAs !== 'html') {
+    log.warn(
+      `sitemap is skipped when saveAs writes ${config.saveAs} files, as there are no pages to list`,
+    );
+    return;
+  }
+  const sitemap = buildSitemap({ files: report.files, config });
+  if (!sitemap) {
+    log.warn('sitemap is skipped: no pages were written');
+    return;
+  }
+
+  const siteUrl = config.metadata.siteUrl.replace(/\/$/, '');
+  const sitemapUrl = `${siteUrl}${toPublicPath('/sitemap.xml', config.base)}`;
+  const robots = await fs.readFile(path.join(outputDir, 'robots.txt'), 'utf8').catch(() => null);
+  const patched = robots === null ? null : withSitemapDirective(robots, sitemapUrl);
+  const names = sitemap.files.map((entry) => entry.name);
+
+  if (config.dryRun) {
+    for (const entry of sitemap.files) {
+      report.files.push({
+        route: null,
+        file: entry.name,
+        status: 'dry-run',
+        bytes: Buffer.byteLength(entry.contents),
+      });
+    }
+    report.sitemap = {
+      file: 'sitemap.xml',
+      routes: sitemap.routes,
+      robotsUpdated: patched !== null,
+      files: names,
+    };
+    log.info(`Dry run: would write ${names.join(', ')} listing ${sitemap.routes} route(s)`);
+    return;
+  }
+
+  const statuses = [];
+  for (const entry of sitemap.files) {
+    const written = await writeFileIfChanged({
+      dir: outputDir,
+      file: entry.name,
+      contents: entry.contents,
+    });
+    statuses.push(written.status);
+    report.files.push({ route: null, ...written });
+  }
+  report.sitemap = {
+    file: 'sitemap.xml',
+    routes: sitemap.routes,
+    robotsUpdated: patched !== null,
+    files: names,
+  };
+  log.info(
+    `${statuses.every((status) => status === 'unchanged') ? 'Unchanged' : 'Wrote'} ${names.join(', ')} listing ${sitemap.routes} route(s)`,
+  );
+
+  if (robots === null) {
+    log.info(`Add "Sitemap: ${sitemapUrl}" to a robots.txt so crawlers find it`);
+    return;
+  }
+  if (patched !== null) {
+    const written = await writeFileIfChanged({
+      dir: outputDir,
+      file: 'robots.txt',
+      contents: patched,
+    });
+    report.files.push({ route: null, ...written });
+    log.info('Added the sitemap location to robots.txt');
+  }
+}

package/src/core/blocking.js

@@ -1,3 +1,36 @@
+/**
+ * Reports whether a host is on the allowlist. Entries may be a hostname, a hostname
+ * with a port, a leading-dot or wildcard suffix, or a full URL; matching is
+ * case-insensitive.
+ */
+export function isHostAllowed(hostname, port, allowedHosts) {
+  const host = hostname.toLowerCase();
+  const withPort = port ? `${host}:${port}` : host;
+  for (const raw of allowedHosts) {
+    const entry = String(raw).trim().toLowerCase();
+    if (entry.length === 0) continue;
+    if (entry.includes('://')) {
+      try {
+        const parsed = new URL(entry);
+        if (parsed.hostname.toLowerCase() === host && (!parsed.port || parsed.port === port)) {
+          return true;
+        }
+      } catch {
+        // A malformed entry is simply not a match.
+      }
+      continue;
+    }
+    if (entry === withPort || entry === host) return true;
+    if (entry.startsWith('*.') && host.endsWith(entry.slice(1)) && host !== entry.slice(2)) {
+      return true;
+    }
+    if (entry.startsWith('.') && host.endsWith(entry) && host !== entry.slice(1)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Aborts requests to third-party origins so analytics, ads and external widgets
  * cannot mutate the DOM mid-capture or make output non-deterministic. Used by both
@@ -15,11 +48,30 @@ export async function blockThirdPartyRequests(page, origin, allowedHosts) {
       return allow(route);
     }
     if (parsed.origin === origin) return allow(route);
-    if (allowed.has(parsed.hostname.toLowerCase())) return allow(route);
+    if (isHostAllowed(parsed.hostname, parsed.port, allowed)) return allow(route);
     // A route can already be handled or cancelled, and that rejection is not this hook's to
     // report, so it is swallowed rather than surfacing as an unhandled rejection.
     return route.abort().catch(() => {});
   });
+
+  // page.route does not see WebSockets; route them separately when the Playwright
+  // version provides the hook.
+  if (typeof page.routeWebSocket === 'function') {
+    await page.routeWebSocket('**/*', (socket) => {
+      let parsed;
+      try {
+        parsed = new URL(socket.url());
+      } catch {
+        socket.close();
+        return;
+      }
+      if (parsed.origin === origin || isHostAllowed(parsed.hostname, parsed.port, allowed)) {
+        socket.connectToServer();
+      } else {
+        socket.close();
+      }
+    });
+  }
 }
 
 // Continues a request, ignoring the rejection that follows an already-handled route.

package/src/core/browser.js

@@ -1,14 +1,26 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import * as browsers from '@puppeteer/browsers';
 import { chromium } from 'playwright-core';
 import { isExecutablePath } from './config.js';
 
 /**
- * Resolves a usable Chromium-compatible browser, preferring the browser already on
- * the machine, then any Playwright cache, then a one-time Chrome for Testing
- * download. Returns the launched browser plus a human-readable source for logs.
+ * Lists the resolution steps for a browser option. Explicit choices only ever try the
+ * browser they name, so a machine without Chrome cannot silently prerender in Edge;
+ * `auto` is the only choice that falls through the machine, the Playwright cache, a
+ * cached Chrome for Testing, and finally a download.
+ */
+export function browserSteps(browser) {
+  if (browser === 'auto') return ['chrome', 'msedge', 'playwright', 'cache', 'download'];
+  if (browser === 'chromium') return ['playwright'];
+  if (browser === 'chrome' || browser === 'msedge') return [browser];
+  return [];
+}
+
+/**
+ * Resolves a usable Chromium-compatible browser. Explicit channel choices fail rather
+ * than falling back, while `auto` prefers the machine's browser, then any cached
+ * download, then a one-time Chrome for Testing install.
  */
 export async function launchBrowser(config, log) {
   if (isExecutablePath(config.browser)) {
@@ -19,40 +31,54 @@ export async function launchBrowser(config, log) {
   }
 
   const attempts = [];
-  const channels =
-    config.browser === 'auto'
-      ? ['chrome', 'msedge']
-      : config.browser === 'chromium'
-        ? []
-        : [config.browser];
-
-  for (const channel of channels) {
+  for (const step of browserSteps(config.browser)) {
     try {
-      const browser = await launch(config, { channel });
-      return { browser, source: `system ${channel}` };
+      const launched = await runStep(step, config, log);
+      if (launched) return launched;
     } catch (error) {
-      attempts.push(`${channel}: ${firstLine(error.message)}`);
+      attempts.push(`${step}: ${firstLine(error.message)}`);
     }
   }
 
-  try {
-    const browser = await launch(config, {});
-    return { browser, source: 'playwright cache' };
-  } catch (error) {
-    attempts.push(`playwright cache: ${firstLine(error.message)}`);
-  }
-
   if (!config.browserDownload) {
     throw new Error(
       `No usable browser found and browserDownload is disabled. Tried:\n  ${attempts.join('\n  ')}`,
     );
   }
+  if (config.browser === 'chromium') {
+    throw new Error(
+      `No Playwright-managed Chromium is installed. Run "npx playwright install chromium", or set browser to auto or chrome. Tried:\n  ${attempts.join('\n  ')}`,
+    );
+  }
+  throw new Error(`No usable browser found. Tried:\n  ${attempts.join('\n  ')}`);
+}
 
-  const executablePath = await downloadChrome(config, log);
-  return {
-    browser: await launch(config, { executablePath }),
-    source: `downloaded ${executablePath}`,
-  };
+// Runs one browser resolution step and returns the launched browser, or null when the
+// step has nothing to offer on this machine.
+async function runStep(step, config, log) {
+  if (step === 'chrome' || step === 'msedge') {
+    return { browser: await launch(config, { channel: step }), source: `system ${step}` };
+  }
+  if (step === 'playwright') {
+    return { browser: await launch(config, {}), source: 'playwright cache' };
+  }
+  if (step === 'cache') {
+    const cached = await findCachedChrome(config);
+    if (!cached) return null;
+    return {
+      browser: await launch(config, { executablePath: cached.executablePath }),
+      source: `cached Chrome for Testing ${cached.buildId}`,
+    };
+  }
+  if (step === 'download') {
+    if (!config.browserDownload) return null;
+    const executablePath = await downloadChrome(config, log);
+    return {
+      browser: await launch(config, { executablePath }),
+      source: `downloaded ${executablePath}`,
+    };
+  }
+  return null;
 }
 
 // Launches Chromium with the configured headless mode, extra args and target.
@@ -70,20 +96,64 @@ function firstLine(message) {
 }
 
 /**
- * Downloads Chrome for Testing into the tool's own cache directory. Used only when
- * neither a system browser nor a Playwright-managed browser is available. The
- * archive comes from Google's version-pinned HTTPS bucket via @puppeteer/browsers,
- * which verifies it against browserDownloadHash when one is configured and deletes
- * it on a mismatch. Without a configured hash the download is trusted on the
- * strength of HTTPS alone, which is logged as a warning.
+ * Chooses a cached Chrome for Testing install. Kept pure so the offline/version-pinned
+ * selection can be tested without touching the machine's browser cache.
+ */
+export function selectCachedChrome(
+  installed,
+  { browser = 'chrome', platform, buildId = null, executableExists = () => true },
+) {
+  return (
+    installed.find(
+      (entry) =>
+        entry.browser === browser &&
+        entry.platform === platform &&
+        (!buildId || entry.buildId === buildId) &&
+        executableExists(entry.executablePath),
+    ) ?? null
+  );
+}
+
+// Formats download progress for the debug log; a missing content length reports 0%.
+export function downloadPercent(downloaded, total) {
+  return total > 0 ? Math.round((downloaded / total) * 100) : 0;
+}
+
+/**
+ * Finds a Chrome for Testing build already present in the tool's cache, so a rebuild
+ * never needs the version feed or a download when a browser is available offline.
+ * Honours browserDownloadVersion when one is configured.
+ */
+async function findCachedChrome(config) {
+  const browsers = await import('@puppeteer/browsers');
+  const platform = browsers.detectBrowserPlatform();
+  if (!platform) return null;
+  const installed = browsers.getInstalledBrowsers({ cacheDir: browserCacheDir() });
+  return selectCachedChrome(installed, {
+    browser: browsers.Browser.CHROME,
+    platform,
+    buildId: config.browserDownloadVersion,
+    executableExists: fs.existsSync,
+  });
+}
+
+/**
+ * Downloads Chrome for Testing into the tool's own cache directory. The archive comes
+ * from Google's version-pinned HTTPS bucket via @puppeteer/browsers, which verifies it
+ * against browserDownloadHash when one is configured and deletes it on a mismatch.
+ * Without a configured hash the download is trusted on the strength of HTTPS alone,
+ * which is logged as a warning.
  */
 async function downloadChrome(config, log) {
+  const browsers = await import('@puppeteer/browsers');
+  const platform = browsers.detectBrowserPlatform();
+  if (!platform) {
+    throw new Error(`Cannot download a browser for ${os.platform()} (${os.arch()})`);
+  }
   const cacheDir = browserCacheDir();
-  const buildId = await browsers.resolveBuildId(
-    browsers.Browser.CHROME,
-    browsers.detectBrowserPlatform(),
-    'stable',
-  );
+  const buildId =
+    config.browserDownloadVersion ??
+    (await browsers.resolveBuildId(browsers.Browser.CHROME, platform, 'stable'));
   if (config.browserDownloadHash) {
     log.info(
       `Downloading Chrome for Testing ${buildId}, verifying SHA-256 against browserDownloadHash`,
@@ -99,7 +169,7 @@ async function downloadChrome(config, log) {
     cacheDir,
     expectedHash: config.browserDownloadHash ?? undefined,
     downloadProgressCallback: (downloaded, total) =>
-      log.debug(`  downloaded ${total > 0 ? Math.round((downloaded / total) * 100) : 0}%`),
+      log.debug(`  downloaded ${downloadPercent(downloaded, total)}%`),
   });
   if (!fs.existsSync(installed.executablePath)) {
     throw new Error(`Chrome download reported success but ${installed.executablePath} is missing`);

package/src/core/build-origin.js

@@ -0,0 +1,19 @@
+import { parse } from 'parse5';
+import { collectBuildOrigins, isMetadataUrlNode, metadataUrlValue } from './metadata-origin.js';
+
+/**
+ * Collects build-server origins from the metadata URLs in a serialized document.
+ * Only canonical and URL-bearing social tags are inspected, so a loopback API URL in
+ * application state does not trip the optional build-origin gate.
+ */
+export function findBuildOriginUrls(html) {
+  const origins = new Set();
+  const walk = (node) => {
+    if (isMetadataUrlNode(node)) {
+      for (const origin of collectBuildOrigins(metadataUrlValue(node))) origins.add(origin);
+    }
+    for (const child of node.childNodes ?? []) walk(child);
+  };
+  walk(parse(html));
+  return [...origins].slice(0, 3);
+}

package/src/core/config.js

@@ -24,6 +24,7 @@ const NULLABLE_KEYS = [
   'userAgent',
   'destination',
   'browserDownloadHash',
+  'browserDownloadVersion',
   'url',
   'serveCmd',
 ];
@@ -39,6 +40,7 @@ const ARRAY_KEYS = [
 export const DEFAULTS = Object.freeze({
   sourceDir: 'dist',
   destination: null,
+  cleanDestination: false,
   base: '/',
   include: ['/'],
   exclude: [],
@@ -59,6 +61,7 @@ export const DEFAULTS = Object.freeze({
   browser: 'auto',
   browserDownload: true,
   browserDownloadHash: null,
+  browserDownloadVersion: null,
   browserArgs: [],
   headless: true,
   ignoreHTTPSErrors: false,
@@ -94,6 +97,15 @@ export const DEFAULTS = Object.freeze({
   failOnHydrationError: false,
   failOnRerender: false,
   failOnPageError: false,
+  failOnEmptyPage: true,
+  failOnUndetected: false,
+  failOnVerificationError: false,
+  failOnConsoleError: false,
+  failOnFailedRequest: false,
+  failOnDuplicateContent: false,
+  stripBuildOriginMetadata: true,
+  failOnBuildOriginMetadata: false,
+  pruneStaleRoutes: false,
   metadata: null,
   failOnError: true,
   dryRun: false,
@@ -107,6 +119,19 @@ export const DEFAULTS = Object.freeze({
 // below decide what is allowed.
 const MULTI_TYPE_KEYS = new Set(['inlineCss', 'minifyHtml', 'minifyCss']);
 
+// Freeze the nested list defaults as well, so a consumer cannot mutate the defaults
+// used by every later run in the same process.
+for (const key of [
+  'include',
+  'exclude',
+  'allowedHosts',
+  'browserArgs',
+  'ignoreForPreload',
+  'removeAttributes',
+]) {
+  Object.freeze(DEFAULTS[key]);
+}
+
 // Every boolean option is validated, derived from the defaults so a new flag cannot be
 // forgotten in a hand-maintained list.
 const BOOLEAN_KEYS = Object.entries(DEFAULTS)
@@ -126,7 +151,9 @@ export function resolveConfig(userOptions = {}) {
   config.concurrency =
     userOptions.concurrency ??
     Math.max(1, Math.min(os.availableParallelism(), MAX_DEFAULT_CONCURRENCY));
-  config.includeProvided = userOptions.include !== undefined;
+  config.includeProvided =
+    userOptions.include !== undefined &&
+    !(config.include.length === 1 && config.include[0] === '/');
   // The CSP dial decides the defaults for the pieces that can move. Explicit options still
   // win, so a project can take 'strict' and put one part back.
   if (userOptions.externalScripts === undefined) config.externalScripts = config.csp === 'strict';
@@ -135,9 +162,87 @@ export function resolveConfig(userOptions = {}) {
   }
   config.warnings = [];
   validateConfig(config);
+  addConfigWarnings(config, userOptions);
   return config;
 }
 
+/**
+ * Reports options that do nothing in the current combination, so a build does not
+ * quietly skip a gate the caller believes is active.
+ */
+function addConfigWarnings(config, userOptions) {
+  const warn = (message) => config.warnings.push(message);
+  for (const key of Object.keys(userOptions)) {
+    if (!Object.hasOwn(DEFAULTS, key)) {
+      warn(`unknown option "${key}" is ignored; check the spelling`);
+    }
+  }
+  if (!config.verify) {
+    for (const key of [
+      'verifyChangedOnly',
+      'failOnHydrationError',
+      'failOnRerender',
+      'failOnUndetected',
+      'failOnVerificationError',
+    ]) {
+      if (config[key]) warn(`${key} has no effect because verify is false`);
+    }
+  }
+  if (config.verify && (config.serveCmd || config.saveAs !== 'html')) {
+    for (const key of [
+      'failOnHydrationError',
+      'failOnRerender',
+      'failOnUndetected',
+      'failOnVerificationError',
+    ]) {
+      if (config[key]) {
+        warn(
+          `${key} has no effect because hydration verification is skipped with ${config.serveCmd ? 'serveCmd' : `saveAs: '${config.saveAs}'`}`,
+        );
+      }
+    }
+  }
+  if (
+    userOptions.criticalCssPreload !== undefined &&
+    config.criticalCssPreload !== false &&
+    config.inlineCss !== 'critical'
+  ) {
+    warn('criticalCssPreload has no effect unless inlineCss is "critical"');
+  }
+  if (config.minifyCss && !config.minifyHtml && !config.inlineCss) {
+    warn('minifyCss has no effect unless minifyHtml or inlineCss is enabled');
+  }
+  if (config.allowedHosts.length > 0 && !config.blockThirdParty) {
+    warn('allowedHosts has no effect unless blockThirdParty is true');
+  }
+  if (config.csp === 'strict' && config.inlineCss) {
+    warn(
+      "csp controls script-src; inlineCss emits inline styles, which need style-src 'unsafe-inline' or hashes",
+    );
+  }
+  if (
+    config.csp === 'strict' &&
+    userOptions.criticalCssPreload !== undefined &&
+    config.criticalCssPreload !== false
+  ) {
+    warn(
+      "criticalCssPreload emits an inline onload handler that a script-src 'self' policy blocks",
+    );
+  }
+  if (config.removeStyleTags && config.inlineCss === 'critical') {
+    warn('removeStyleTags removes CSS-in-JS styles before critical CSS is extracted');
+  }
+  if (config.sitemap && config.saveAs !== 'html') {
+    warn(`sitemap has no effect when saveAs is '${config.saveAs}'`);
+  }
+  const metadataBase = config.metadata?.base;
+  if (metadataBase && metadataBase !== config.base) {
+    warn(
+      `metadata.base (${metadataBase}) differs from base (${config.base}); canonical, social URLs and routing will disagree`,
+    );
+  }
+}
+
 /**
  * Ensures the base path always carries a leading and trailing slash so route and
  * URL helpers can strip or append it without branching on user input shape.
@@ -201,7 +306,7 @@ export function validateConfig(config) {
   stringList(config.ignoreForPreload, 'ignoreForPreload');
   patternList(config.removeAttributes, 'removeAttributes');
   for (const key of ['readyFlag', 'readySelector', 'waitFor', 'notFoundRoute']) nullableString(key);
-  for (const key of ['userAgent', 'destination']) nullableString(key);
+  for (const key of ['userAgent', 'destination', 'browserDownloadVersion']) nullableString(key);
   for (const key of BOOLEAN_KEYS) booleanOption(key);
 
   if (config.browserDownloadHash !== null && !/^[a-f0-9]{64}$/i.test(config.browserDownloadHash)) {
@@ -257,6 +362,14 @@ export function validateConfig(config) {
   if (config.url !== null && !/^https?:\/\//.test(config.url)) {
     throw new TypeError('url must be an absolute http(s) URL');
   }
+  if (config.serveCmd !== null && config.url) {
+    const parsed = new URL(config.url);
+    if (parsed.pathname !== '/' && parsed.pathname !== '') {
+      throw new TypeError(
+        'url must be an origin without a path when serveCmd is used; set base for a sub-path deployment',
+      );
+    }
+  }
   if (!INLINE_CSS_STRATEGIES.includes(config.inlineCss)) {
     throw new TypeError("inlineCss must be false, true, 'inline' or 'critical'");
   }
@@ -281,6 +394,11 @@ export function validateConfig(config) {
   if (!SAVE_AS_CHOICES.includes(config.saveAs)) {
     throw new TypeError(`saveAs must be one of: ${SAVE_AS_CHOICES.join(', ')}`);
   }
+  if (config.removeStyleTags && (config.inlineCss === true || config.inlineCss === 'inline')) {
+    throw new TypeError(
+      "removeStyleTags cannot be combined with inlineCss 'inline' or true: it would strip the CSS the inline step just added",
+    );
+  }
   validateMetadata(config);
   if (config.sitemap && !config.metadata?.siteUrl) {
     throw new TypeError('sitemap needs metadata.siteUrl so the sitemap can list absolute URLs');
@@ -319,6 +437,14 @@ function validateMetadata(config) {
   if (metadata.siteUrl && !/^https?:\/\//.test(metadata.siteUrl)) {
     throw new TypeError('metadata.siteUrl must be an absolute http(s) URL');
   }
+  if (metadata.siteUrl) {
+    const parsed = new URL(metadata.siteUrl);
+    if (parsed.pathname !== '/' && parsed.pathname !== '') {
+      throw new TypeError(
+        'metadata.siteUrl must be an origin without a path; set base for a sub-path deployment',
+      );
+    }
+  }
   if (metadata.base && !metadata.base.startsWith('/')) {
     throw new TypeError('metadata.base must start with a slash, for example /app/');
   }

package/src/core/css-url.js

@@ -0,0 +1,34 @@
+const URL_TOKEN = /url\(\s*(['"]?)([^'")]+)\1\s*\)/gi;
+const NON_LOCAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * Rebases the relative url() values in a stylesheet against the stylesheet's own URL.
+ * Moving a sheet from /assets/app.css into a <style> element would otherwise resolve
+ * its fonts and images against the page URL, which differs on nested routes. Local
+ * URLs become root-relative so they work from any page depth.
+ */
+export function rewriteCssUrls(css, stylesheetUrl, pageOrigin) {
+  return css.replace(URL_TOKEN, (match, quote, value) => {
+    const target = value.trim();
+    if (target.length === 0 || NON_LOCAL.test(target)) return match;
+    let resolved;
+    try {
+      resolved = new URL(target, stylesheetUrl);
+    } catch {
+      return match;
+    }
+    const next =
+      resolved.origin === pageOrigin
+        ? `${resolved.pathname}${resolved.search}${resolved.hash}`
+        : resolved.href;
+    return `url(${quote}${next}${quote})`;
+  });
+}
+
+/**
+ * Reports whether a stylesheet uses @import. Inlining cannot preserve the rule's
+ * position in the cascade, so the caller leaves that sheet as a link instead.
+ */
+export function hasImportRule(css) {
+  return /@import\b/i.test(css);
+}

package/src/core/destination.js

@@ -7,9 +7,34 @@ import path from 'node:path';
  * HTML and the source directory stays untouched. An existing destination is reported
  * before it is overwritten, and entries that cannot be copied are counted.
  */
-export async function prepareDestination({ sourceDir, destination, log }) {
-  if (!destination || path.resolve(destination) === path.resolve(sourceDir)) {
-    return sourceDir;
+export async function prepareDestination({
+  sourceDir,
+  destination,
+  log,
+  cleanDestination = false,
+}) {
+  if (!destination) return path.resolve(sourceDir);
+  const source = path.resolve(sourceDir);
+  const target = path.resolve(destination);
+  if (target === source) return source;
+  if (target.startsWith(`${source}${path.sep}`)) {
+    throw new Error(
+      `destination cannot be inside sourceDir: ${target} is inside ${source}. Use a sibling directory.`,
+    );
+  }
+  if (cleanDestination) {
+    const sourceInsideTarget = path.relative(target, source);
+    if (
+      sourceInsideTarget.length > 0 &&
+      !sourceInsideTarget.startsWith('..') &&
+      !path.isAbsolute(sourceInsideTarget)
+    ) {
+      throw new Error(
+        `cleanDestination would delete sourceDir: ${source} is inside ${target}. Choose a destination outside the build output.`,
+      );
+    }
+    await fs.rm(target, { recursive: true, force: true });
+    log?.debug(`cleaned destination ${destination}`);
   }
   const existing = await fs.readdir(destination).catch(() => []);
   if (existing.length > 0) {