prerender-crawler 0.1.0 → 0.2.0

package/dist/crawl.js

@@ -1,17 +1,20 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { extractLinks, normalizeLink, normalizePath } from "./links.js";
+import { dirname, resolve } from "node:path";
+import { extractLinks, normalizeLink, normalizeRoute, splitRoute } from "./links.js";
 import { outputFilename } from "./output.js";
 const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-async function resolveSeeds(pages) {
+async function resolveSeeds(pages, origin, links) {
     const source = typeof pages === "function" ? await pages() : (pages ?? ["/"]);
-    // Seed sources overlap routinely (an explicit list plus a route-manifest
-    // scan both naming `/`): one render per path, the first spelling wins.
+    // Seeds are spelled by people and route manifests — `about/`, `/a#top`,
+    // `/posts?page=2` — and get the same normalization a crawled link does,
+    // so a seed and a link to the same page meet in one queue entry. Seed
+    // sources overlap routinely (an explicit list plus a route-manifest scan
+    // both naming `/`): one render per path, the first spelling wins.
     const byPath = new Map();
     for (const entry of source) {
-        const page = typeof entry === "string"
-            ? { path: normalizePath(entry) }
-            : { ...entry, path: normalizePath(entry.path) };
+        const spelled = typeof entry === "string" ? entry : entry.path;
+        const path = normalizeRoute(new URL(spelled, origin), links);
+        const page = typeof entry === "string" ? { path } : { ...entry, path };
         if (!byPath.has(page.path))
             byPath.set(page.path, page);
     }
@@ -24,20 +27,37 @@ async function resolveSeeds(pages) {
  * identical loop.
  */
 export async function runPrerender(options) {
-    const { transport, outDir, mode = "static", crawlLinks = true, hintHeader = "x-prerender", filter, concurrency = 8, interval = 0, retries = 2, retryDelay = 500, failOnError = true, maxRedirects = 5, 
+    const { transport, outDir, mode = "static", crawlLinks = true, hintHeader = "x-prerender", filter, keepQuery = false, concurrency = 8, interval = 0, retries = 2, retryDelay = 500, failOnError = true, 
     // hybrid's crawl bakes data; writing its HTML would shadow live SSR
-    emitPages = mode === "static", autoSubfolderIndex = true, origin = "http://localhost", onRendered, integrations = [] } = options;
+    emitPages = mode === "static", autoSubfolderIndex = true, origin = "http://localhost", onRendered, integrations = [], 
+    // an integration turning redirects into host rules makes stubs
+    // redundant — and on hosts where a file shadows a rule, harmful
+    redirectStubs = !integrations.some(integration => integration.handlesRedirects) } = options;
     const originUrl = new URL(origin);
+    const links = { keepQuery };
     const rendered = [];
+    const redirects = [];
     const skipped = [];
     const emitted = [];
     const context = {
         mode,
         origin,
         outDir,
+        pages: rendered,
+        redirects,
+        skipped,
+        files: emitted,
         emitFile: file => void emitted.push(file)
     };
-    const seeds = await resolveSeeds(options.pages);
+    // A query spelling without a filename of its own has nowhere correct to
+    // go: `posts/index.html` is `/posts`, and a static host serves it for
+    // every query. It renders (data, links) and leaves no file.
+    const shouldEmit = (entry) => {
+        if (!entry.filename && entry.path.includes("?"))
+            return false;
+        return entry.emit ?? (typeof emitPages === "function" ? emitPages(entry.path) : emitPages);
+    };
+    const seeds = await resolveSeeds(options.pages, originUrl, links);
     const seen = new Set(seeds.map(page => page.path));
     const queue = [...seeds];
     // Provenance: which pages named each discovered path. Recorded for every
@@ -57,46 +77,73 @@ export async function runPrerender(options) {
         seen.add(path);
         queue.push({ path });
     };
-    // The throttle: every request start claims the next slot on a shared
-    // timeline, so starts are at least `interval` apart no matter how many
-    // workers are running.
+    // The throttle. Two mechanisms, because the guarantee is about ACTUAL
+    // starts: claiming the next slot on a shared timeline keeps concurrent
+    // workers apart in advance, and holding until `interval` has passed since
+    // the last real start covers the case a claim cannot — a start that ran
+    // late (busy event loop) must not be crowded by the next one's on-time
+    // slot. The hold's check-then-record runs without interleaving, so two
+    // workers waking together cannot both pass it.
     let nextSlot = 0;
+    let lastStart = -Infinity;
     async function pace() {
         if (interval <= 0)
             return;
-        const now = Date.now();
+        const now = performance.now();
         const slot = Math.max(now, nextSlot);
         nextSlot = slot + interval;
         if (slot > now)
             await wait(slot - now);
+        let started = performance.now();
+        while (started - lastStart < interval) {
+            await wait(lastStart + interval - started);
+            started = performance.now();
+        }
+        lastStart = started;
+        if (nextSlot < started + interval)
+            nextSlot = started + interval;
     }
-    async function fetchFollowingRedirects(path) {
-        let url = new URL(path, originUrl);
-        for (let hop = 0;; hop++) {
-            await pace();
-            const response = await transport.fetch(new Request(url, { headers: { accept: "text/html,*/*", [hintHeader]: "1" } }));
-            const location = response.headers.get("location");
-            if (response.status < 300 || response.status >= 400 || !location)
-                return response;
-            if (hop >= maxRedirects) {
-                throw new Error(`Redirect chain from ${path} exceeded ${maxRedirects} hops`);
-            }
-            const target = new URL(location, url);
-            if (target.origin !== originUrl.origin) {
-                // an external redirect terminates the chain; the page becomes a stub
-                return response;
-            }
-            url = target;
+    // Redirects are not followed in place: a 3xx makes the path a redirect
+    // record (and a stub, see finalizeRedirects), and its same-origin target
+    // enters the queue as a page in its own right — so the destination is
+    // rendered once, at its own URL, and a chain is one record per hop the
+    // way a host's redirect rules would spell it. Cycles are harmless: the
+    // seen-set admits each path once.
+    // `started` is taken after pacing: a page's duration is its own, not the
+    // throttle's.
+    async function fetchUrl(url) {
+        await pace();
+        const started = performance.now();
+        const response = await transport.fetch(new Request(url, { headers: { accept: "text/html,*/*", [hintHeader]: "1" } }));
+        return { response, started };
+    }
+    // A redirect to a spelling of the SAME page (`/posts` -> `/posts/`, the
+    // trailing-slash canonicalization static servers do) is not a redirect
+    // between pages: it is followed here, once, and the page renders as
+    // itself. Anything else is the caller's to record.
+    async function fetchPage(path) {
+        const url = new URL(path, originUrl);
+        const fetched = await fetchUrl(url);
+        const { response } = fetched;
+        const location = response.headers.get("location");
+        if (!location || response.status < 300 || response.status >= 400)
+            return fetched;
+        const target = new URL(location, url);
+        if (target.origin !== originUrl.origin || normalizeRoute(target, links) !== path) {
+            return fetched;
         }
+        return { ...(await fetchUrl(target)), started: fetched.started };
     }
+    const pendingRedirects = [];
     async function renderPage(entry) {
         let response;
+        let started = 0;
         let error;
         for (let attempt = 0; attempt <= retries; attempt++) {
             if (attempt > 0)
                 await wait(retryDelay);
             try {
-                response = await fetchFollowingRedirects(entry.path);
+                ({ response, started } = await fetchPage(entry.path));
                 error = undefined;
                 if (response.status < 500)
                     break; // retry only what might heal
@@ -122,40 +169,43 @@ export async function runPrerender(options) {
             skipped.push({ path: entry.path, error: failure, referrers: [] });
             return;
         }
-        const filename = entry.filename ?? outputFilename(entry.path, autoSubfolderIndex);
-        let html;
-        const contentType = response.headers.get("content-type") ?? "";
-        const isHTML = contentType.includes("text/html");
+        const filename = entry.filename ?? outputFilename(splitRoute(entry.path).pathname, autoSubfolderIndex);
+        const hints = response.headers.get(hintHeader);
+        if (hints) {
+            for (const hint of hints.split(",")) {
+                const path = normalizeLink(hint.trim(), originUrl, originUrl.origin, links);
+                if (path !== undefined)
+                    discovered(path, entry.path);
+            }
+        }
         const location = response.headers.get("location");
         if (location && response.status >= 300 && response.status < 400) {
-            // external redirect (internal ones were followed): a meta-refresh stub
-            // keeps the path working on hosts without redirect support
-            html = redirectStub(location);
-        }
-        else {
-            html = await response.text();
+            const pageUrl = new URL(entry.path, originUrl);
+            const target = new URL(location, pageUrl);
+            const internal = target.origin === originUrl.origin;
+            const to = internal ? normalizeRoute(target, links) : target.href;
+            const redirect = { from: entry.path, to, status: response.status };
+            redirects.push(redirect);
+            if (internal)
+                discovered(to, entry.path);
+            // the stub needs the chain's end, known only once the crawl settles
+            const duration = performance.now() - started;
+            pendingRedirects.push({ entry, filename, response, duration, redirect });
+            return;
         }
+        const html = await response.text();
+        const duration = performance.now() - started;
         // Emission is policy, rendering is not: an unemitted page has still
         // fully executed (integration capture happened server-side) and its
         // links still feed the crawl — it just leaves no HTML file behind to
         // shadow a live server's SSR of the route.
-        const emitted = entry.emit ?? (typeof emitPages === "function" ? emitPages(entry.path) : emitPages);
+        const emitted = shouldEmit(entry);
         if (emitted)
             await writeOutput(outDir, filename, html);
-        if (isHTML) {
+        if (crawlLinks && (response.headers.get("content-type") ?? "").includes("text/html")) {
             const pageUrl = new URL(entry.path, originUrl);
-            if (crawlLinks) {
-                for (const path of extractLinks(html, pageUrl))
-                    discovered(path, entry.path);
-            }
-        }
-        const hints = response.headers.get(hintHeader);
-        if (hints) {
-            for (const hint of hints.split(",")) {
-                const path = normalizeLink(hint.trim(), originUrl, originUrl.origin);
-                if (path !== undefined)
-                    discovered(path, entry.path);
-            }
+            for (const path of extractLinks(html, pageUrl, links))
+                discovered(path, entry.path);
         }
         const page = {
             path: entry.path,
@@ -163,12 +213,51 @@ export async function runPrerender(options) {
             filename,
             emitted,
             response,
+            duration,
             html
         };
         rendered.push(page);
         if (onRendered)
             await onRendered(page);
     }
+    // Redirected paths become pages holding a meta-refresh stub — the old URL
+    // keeps working on hosts with no redirect support — pointing straight at
+    // the chain's final destination so a visitor hops once, not per record.
+    async function finalizeRedirects() {
+        const hops = new Map(redirects.map(record => [record.from, record.to]));
+        // the chain's end — or, in a cycle (which has none), one hop on
+        const destination = (from) => {
+            const next = hops.get(from);
+            const visited = new Set([from]);
+            let at = next;
+            while (hops.has(at)) {
+                if (visited.has(at))
+                    return next;
+                visited.add(at);
+                at = hops.get(at);
+            }
+            return at;
+        };
+        for (const { entry, filename, response, duration, redirect } of pendingRedirects) {
+            const html = redirectStub(destination(entry.path));
+            const emitted = redirectStubs && shouldEmit(entry);
+            if (emitted)
+                await writeOutput(outDir, filename, html);
+            const page = {
+                path: entry.path,
+                referrers: referrersOf(entry.path),
+                filename,
+                emitted,
+                response,
+                duration,
+                html,
+                redirect
+            };
+            rendered.push(page);
+            if (onRendered)
+                await onRendered(page);
+        }
+    }
     try {
         for (const integration of integrations)
             await integration.setup?.(context);
@@ -199,6 +288,7 @@ export async function runPrerender(options) {
         });
         for (const miss of skipped)
             miss.referrers = referrersOf(miss.path);
+        await finalizeRedirects();
         for (const integration of integrations)
             await integration.teardown?.(context);
         for (const file of emitted) {
@@ -208,15 +298,15 @@ export async function runPrerender(options) {
     finally {
         await transport.close?.();
     }
-    return { pages: rendered, files: emitted, skipped };
+    return { pages: rendered, redirects, files: emitted, skipped };
 }
 const describe = (error) => (error instanceof Error ? error.message : String(error));
 function redirectStub(location) {
-    const target = String(location).replace(/"/g, "&quot;");
+    const target = location.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
     return `<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=${target}"><link rel="canonical" href="${target}"></head></html>`;
 }
 async function writeOutput(outDir, filename, contents) {
-    const target = join(outDir, filename);
+    const target = resolve(outDir, filename);
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, contents);
 }

package/dist/index.d.ts

@@ -1,5 +1,16 @@
 export { runPrerender } from "./crawl.ts";
 export type { RunOptions } from "./crawl.ts";
-export { extractLinks, normalizeLink, normalizePath } from "./links.ts";
+export { extractLinks, normalizeLink, normalizePath, normalizeRoute, splitRoute } from "./links.ts";
+export type { LinkOptions } from "./links.ts";
 export { outputFilename } from "./output.ts";
-export type { EmittedFile, PageEntry, PagesSource, PrerenderContext, PrerenderIntegration, PrerenderMode, PrerenderOptions, PrerenderResult, RenderedPage, SkippedPage, Transport } from "./types.ts";
+export { formatRedirectsFile, redirects } from "./redirects.ts";
+export type { RedirectsIntegrationOptions } from "./redirects.ts";
+export { report } from "./report.ts";
+export { HINT_HEADER, announcePages } from "./announce.ts";
+export type { AnnounceOptions } from "./announce.ts";
+export type { PrerenderReport, ReportIntegrationOptions, ReportPage, ReportSkip } from "./report.ts";
+export { formatSitemap, indexable, sitemap } from "./sitemap.ts";
+export type { SitemapChangeFrequency, SitemapEntry, SitemapIntegrationOptions } from "./sitemap.ts";
+export { httpTransport, loadHandler, moduleTransport } from "./transports.ts";
+export type { HttpTransportOptions, RequestHandler } from "./transports.ts";
+export type { EmittedFile, PageEntry, PagesSource, PrerenderContext, PrerenderIntegration, PrerenderMode, PrerenderOptions, PrerenderResult, RedirectRecord, RenderedPage, SkippedPage, Transport } from "./types.ts";

package/dist/index.js

@@ -1,3 +1,8 @@
 export { runPrerender } from "./crawl.js";
-export { extractLinks, normalizeLink, normalizePath } from "./links.js";
+export { extractLinks, normalizeLink, normalizePath, normalizeRoute, splitRoute } from "./links.js";
 export { outputFilename } from "./output.js";
+export { formatRedirectsFile, redirects } from "./redirects.js";
+export { report } from "./report.js";
+export { HINT_HEADER, announcePages } from "./announce.js";
+export { formatSitemap, indexable, sitemap } from "./sitemap.js";
+export { httpTransport, loadHandler, moduleTransport } from "./transports.js";

package/dist/links.d.ts

@@ -2,23 +2,39 @@
  * Link discovery: which hrefs in a rendered page name more pages of this
  * site. The rules here are correctness fixes other prerenderers earned one
  * bug report at a time — resolve relative hrefs against the PAGE's URL
- * (not the origin), honor <base href>, strip queries and fragments before
- * dedupe, and never leave the origin.
+ * (not the origin), honor <base href>, strip queries (unless asked to keep
+ * them) and fragments before dedupe, and never leave the origin.
  */
+export interface LinkOptions {
+    /** Keep the query string as part of the page's identity. @default false */
+    keepQuery?: boolean;
+}
 /**
  * Extracts the crawlable same-origin route paths from a page's HTML.
- * Returned paths are normalized (`/about`, no query, no fragment, no
- * trailing slash except the root) and deduped.
+ * Returned paths are normalized (`/about`, no fragment, no trailing slash
+ * except the root, query only with `keepQuery`) and deduped.
  */
-export declare function extractLinks(html: string, pageUrl: URL): string[];
+export declare function extractLinks(html: string, pageUrl: URL, options?: LinkOptions): string[];
 /**
  * Resolves one href to a normalized same-origin path, or undefined when it
  * is not a page of this site (foreign origin, unparseable).
  */
-export declare function normalizeLink(href: string, base: URL, origin: string): string | undefined;
+export declare function normalizeLink(href: string, base: URL, origin: string, options?: LinkOptions): string | undefined;
 /**
- * One spelling per page: query and fragment never reach here (URL parsing
- * split them off), the trailing slash is dropped (except the root), and
- * percent-encoding is left exactly as the URL parser produced it.
+ * One spelling per page: the fragment never reaches here (URL parsing split
+ * it off), the trailing slash is dropped (except the root), percent-encoding
+ * is left exactly as the URL parser produced it, and the query is kept only
+ * on request — with its parameters sorted, so `?a=1&b=2` and `?b=2&a=1`
+ * are the one page they are.
+ */
+export declare function normalizeRoute(url: URL, options?: LinkOptions): string;
+/**
+ * The pathname half of normalization: the trailing slash is dropped (except
+ * the root) and nothing else is touched.
  */
 export declare function normalizePath(pathname: string): string;
+/** Splits a normalized route into its pathname and its (possibly empty) query. */
+export declare function splitRoute(route: string): {
+    pathname: string;
+    search: string;
+};

package/dist/links.js

@@ -2,8 +2,8 @@
  * Link discovery: which hrefs in a rendered page name more pages of this
  * site. The rules here are correctness fixes other prerenderers earned one
  * bug report at a time — resolve relative hrefs against the PAGE's URL
- * (not the origin), honor <base href>, strip queries and fragments before
- * dedupe, and never leave the origin.
+ * (not the origin), honor <base href>, strip queries (unless asked to keep
+ * them) and fragments before dedupe, and never leave the origin.
  */
 const LINK_PATTERN = /<a\s[^>]*?href\s*=\s*(?:"([^"]*)"|'([^']*)')/gis;
 const BASE_PATTERN = /<base\s[^>]*?href\s*=\s*(?:"([^"]*)"|'([^']*)')/is;
@@ -11,10 +11,10 @@ const BASE_PATTERN = /<base\s[^>]*?href\s*=\s*(?:"([^"]*)"|'([^']*)')/is;
 const NON_PAGE_SCHEME = /^(?:mailto|tel|javascript|data|blob|about):/i;
 /**
  * Extracts the crawlable same-origin route paths from a page's HTML.
- * Returned paths are normalized (`/about`, no query, no fragment, no
- * trailing slash except the root) and deduped.
+ * Returned paths are normalized (`/about`, no fragment, no trailing slash
+ * except the root, query only with `keepQuery`) and deduped.
  */
-export function extractLinks(html, pageUrl) {
+export function extractLinks(html, pageUrl, options = {}) {
     // <base href> shifts what relative hrefs resolve against, exactly as the
     // browser would resolve them.
     const baseMatch = BASE_PATTERN.exec(html);
@@ -33,7 +33,7 @@ export function extractLinks(html, pageUrl) {
         const href = (match[1] ?? match[2] ?? "").trim();
         if (!href || NON_PAGE_SCHEME.test(href))
             continue;
-        const path = normalizeLink(href, base, pageUrl.origin);
+        const path = normalizeLink(href, base, pageUrl.origin, options);
         if (path !== undefined)
             found.add(path);
     }
@@ -43,7 +43,7 @@ export function extractLinks(html, pageUrl) {
  * Resolves one href to a normalized same-origin path, or undefined when it
  * is not a page of this site (foreign origin, unparseable).
  */
-export function normalizeLink(href, base, origin) {
+export function normalizeLink(href, base, origin, options = {}) {
     let url;
     try {
         url = new URL(href, base);
@@ -53,15 +53,37 @@ export function normalizeLink(href, base, origin) {
     }
     if (url.origin !== origin)
         return undefined;
-    return normalizePath(url.pathname);
+    return normalizeRoute(url, options);
 }
 /**
- * One spelling per page: query and fragment never reach here (URL parsing
- * split them off), the trailing slash is dropped (except the root), and
- * percent-encoding is left exactly as the URL parser produced it.
+ * One spelling per page: the fragment never reaches here (URL parsing split
+ * it off), the trailing slash is dropped (except the root), percent-encoding
+ * is left exactly as the URL parser produced it, and the query is kept only
+ * on request — with its parameters sorted, so `?a=1&b=2` and `?b=2&a=1`
+ * are the one page they are.
+ */
+export function normalizeRoute(url, options = {}) {
+    const path = normalizePath(url.pathname);
+    if (!options.keepQuery || !url.search)
+        return path;
+    const params = new URLSearchParams(url.search);
+    params.sort();
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+/**
+ * The pathname half of normalization: the trailing slash is dropped (except
+ * the root) and nothing else is touched.
  */
 export function normalizePath(pathname) {
     if (pathname === "" || pathname === "/")
         return "/";
     return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
 }
+/** Splits a normalized route into its pathname and its (possibly empty) query. */
+export function splitRoute(route) {
+    const at = route.indexOf("?");
+    return at === -1
+        ? { pathname: route, search: "" }
+        : { pathname: route.slice(0, at), search: route.slice(at) };
+}

package/dist/redirects.d.ts

@@ -0,0 +1,33 @@
+import type { PrerenderIntegration, RedirectRecord } from "./types.ts";
+export interface RedirectsIntegrationOptions {
+    /** Output file, relative to the output directory. @default "_redirects" */
+    filename?: string;
+    /**
+     * Produces the file's contents from the run's redirects — for hosts with
+     * their own format. Defaults to the `_redirects` line format.
+     */
+    format?(redirects: readonly RedirectRecord[]): string;
+    /**
+     * Netlify only: append `!` to force each rule past an existing file at
+     * its path. Unneeded when the engine writes no stubs (the default with
+     * this integration active), and Cloudflare Pages rejects the syntax.
+     * @default false
+     */
+    force?: boolean;
+}
+/**
+ * Emits the crawl's redirects as host rules — by default a `_redirects` file
+ * (Netlify, Cloudflare Pages). Declares `handlesRedirects`, so the engine
+ * writes no meta-refresh stubs at redirected paths.
+ *
+ * ```ts
+ * import { redirects } from "prerender-crawler";
+ * prerender({ integrations: [redirects()] })
+ * ```
+ */
+export declare function redirects(options?: RedirectsIntegrationOptions): PrerenderIntegration;
+/**
+ * The `_redirects` line format: `/from /to status`, one rule per line,
+ * sorted by source for a stable file across builds.
+ */
+export declare function formatRedirectsFile(redirects: readonly RedirectRecord[], force?: boolean): string;

package/dist/redirects.js

@@ -0,0 +1,33 @@
+/**
+ * Emits the crawl's redirects as host rules — by default a `_redirects` file
+ * (Netlify, Cloudflare Pages). Declares `handlesRedirects`, so the engine
+ * writes no meta-refresh stubs at redirected paths.
+ *
+ * ```ts
+ * import { redirects } from "prerender-crawler";
+ * prerender({ integrations: [redirects()] })
+ * ```
+ */
+export function redirects(options = {}) {
+    const { filename = "_redirects", force = false } = options;
+    const format = options.format ?? (records => formatRedirectsFile(records, force));
+    return {
+        name: "redirects",
+        handlesRedirects: true,
+        teardown(context) {
+            if (context.redirects.length === 0)
+                return;
+            context.emitFile({ filename, contents: format(context.redirects) });
+        }
+    };
+}
+/**
+ * The `_redirects` line format: `/from /to status`, one rule per line,
+ * sorted by source for a stable file across builds.
+ */
+export function formatRedirectsFile(redirects, force = false) {
+    const lines = [...redirects]
+        .sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0))
+        .map(({ from, to, status }) => `${from} ${to} ${status}${force ? "!" : ""}`);
+    return lines.join("\n") + "\n";
+}

package/dist/report.d.ts

@@ -0,0 +1,55 @@
+import type { PrerenderIntegration, RedirectRecord } from "./types.ts";
+/**
+ * The report integration: what the crawl did, as JSON — every page with
+ * its status, timing, output file and the pages that linked to it; every
+ * redirect; every skipped page and why; every file other integrations
+ * emitted. The answers to "why was this page crawled", "which page is
+ * slow" and "what did the build actually produce" are all in here, and
+ * they are otherwise gone the moment the process exits.
+ */
+export interface ReportIntegrationOptions {
+    /**
+     * Where to write, resolved against the output directory. The default
+     * lands inside it and so deploys with the site; point it outside
+     * (`"../prerender-report.json"`) to keep it a build artifact.
+     * @default "prerender-report.json"
+     */
+    filename?: string;
+}
+export interface PrerenderReport {
+    generatedAt: string;
+    mode: string;
+    origin: string;
+    totals: {
+        pages: number;
+        written: number;
+        redirects: number;
+        skipped: number;
+        files: number;
+        /** Sum of page durations, milliseconds — render cost, not wall time. */
+        duration: number;
+    };
+    pages: ReportPage[];
+    redirects: RedirectRecord[];
+    skipped: ReportSkip[];
+    /** Files emitted by integrations that ran before this one, this run's pages excluded. */
+    files: string[];
+}
+export interface ReportPage {
+    path: string;
+    status: number;
+    contentType: string | null;
+    /** Milliseconds, the successful attempt. */
+    duration: number;
+    filename: string;
+    /** Whether the HTML was written (`false` in hybrid mode, for query spellings, ...). */
+    written: boolean;
+    referrers: string[];
+    redirect?: RedirectRecord;
+}
+export interface ReportSkip {
+    path: string;
+    error: string;
+    referrers: string[];
+}
+export declare function report(options?: ReportIntegrationOptions): PrerenderIntegration;

package/dist/report.js

@@ -0,0 +1,46 @@
+export function report(options = {}) {
+    const { filename = "prerender-report.json" } = options;
+    return {
+        name: "report",
+        teardown(context) {
+            const pages = context.pages
+                .map(page => ({
+                path: page.path,
+                status: page.response.status,
+                contentType: page.response.headers.get("content-type"),
+                duration: Math.round(page.duration * 100) / 100,
+                filename: page.filename,
+                written: page.emitted,
+                referrers: [...page.referrers].sort(),
+                ...(page.redirect ? { redirect: page.redirect } : {})
+            }))
+                .sort(byPath);
+            const skipped = context.skipped
+                .map(miss => ({
+                path: miss.path,
+                error: miss.error instanceof Error ? miss.error.message : String(miss.error),
+                referrers: [...miss.referrers].sort()
+            }))
+                .sort(byPath);
+            const summary = {
+                generatedAt: new Date().toISOString(),
+                mode: context.mode,
+                origin: context.origin,
+                totals: {
+                    pages: pages.length,
+                    written: pages.filter(page => page.written).length,
+                    redirects: context.redirects.length,
+                    skipped: skipped.length,
+                    files: context.files.length,
+                    duration: Math.round(pages.reduce((sum, page) => sum + page.duration, 0))
+                },
+                pages,
+                redirects: [...context.redirects],
+                skipped,
+                files: context.files.map(file => file.filename)
+            };
+            context.emitFile({ filename, contents: JSON.stringify(summary, null, 2) + "\n" });
+        }
+    };
+}
+const byPath = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;