@stati/core 1.27.2 → 1.29.0

package/dist/images/runtime.js

@@ -0,0 +1,659 @@
+/**
+ * Per-build image pipeline: renders image markup while pages render, runs the jobs the
+ * written pages need, recovers from failed jobs and prunes outputs no page uses.
+ * @module images/runtime
+ */
+import { createHash } from 'node:crypto';
+import { dirname, join, posix, relative, resolve } from 'node:path';
+import { URL } from 'node:url';
+import { copyFile, createTemplateError, ensureDir, isPathWithinDirectory, listFilesRecursiveSync, pathExists, readFile, readFileBuffer, remove, writeFile, } from '../core/utils/index.js';
+import { resolveAbsoluteUrl } from '../seo/utils/index.js';
+import { generatedOgImageTags } from '../seo/generator.js';
+import { DEFAULT_SRC_DIR, DEFAULT_STATIC_DIR, IMAGES_OUTPUT_DIR, OG_IMAGES_SUBDIR, } from '../constants.js';
+import { resolveImagesConfig, validateImagesConfig, } from './config.js';
+import { loadImageProvider } from './provider.js';
+import { loadImagesManifest, saveImagesManifest } from './manifest.js';
+import { getSourceCacheEntries, inspectSourceSync, seedSourceCache, } from './sources.js';
+import { resolveImageSource } from './resolve.js';
+import { planCopy, planVariants } from './plan.js';
+import { renderImg, renderResponsiveImage } from './markup.js';
+import { displayTemplatePath, findOgTemplatePath, inlineLocalImages, isOgImageExcluded, ogImageSlug, } from './og.js';
+/**
+ * Bumped when the generated markup changes, so pages rendered by an older pipeline rebuild.
+ */
+const IMAGE_PIPELINE_VERSION = 1;
+/** Host names that cannot appear in an absolute og:image URL. */
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '[::1]']);
+function toPosix(path) {
+    return path.replace(/\\/g, '/');
+}
+function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Checks that og:image URLs will be absolute and public.
+ * @throws {Error} When `site.baseUrl` is not an absolute http(s) URL on a public host
+ */
+export function validateOgBaseUrl(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url ||
+        (url.protocol !== 'http:' && url.protocol !== 'https:') ||
+        LOCAL_HOSTS.has(url.hostname)) {
+        throw new Error(`images.og needs site.baseUrl set to your site's public address, such as https://example.com, so og:image is an absolute URL (got ${JSON.stringify(baseUrl)}).`);
+    }
+}
+async function loadOgState(provider, userFonts) {
+    const defaults = provider.loadOgDefaults ? await provider.loadOgDefaults() : undefined;
+    const fonts = [];
+    for (const font of userFonts) {
+        const data = await readFileBuffer(resolve(process.cwd(), font.path));
+        if (!data) {
+            throw new Error(`images.og.fonts: font file not found: ${font.path}`);
+        }
+        if (data.subarray(0, 4).toString('latin1') === 'wOF2') {
+            throw new Error(`images.og.fonts: ${font.path} is WOFF2, which the image renderer can't read. Use a TTF, OTF or WOFF file.`);
+        }
+        fonts.push({
+            name: font.name,
+            data,
+            ...(font.weight !== undefined && { weight: font.weight }),
+            ...(font.style !== undefined && { style: font.style }),
+        });
+    }
+    fonts.push(...(defaults?.fonts ?? []));
+    if (fonts.length === 0) {
+        throw new Error('images.og needs at least one font. Add one to images.og.fonts.');
+    }
+    const fontsHash = sha256(fonts
+        .map((font) => `${font.name}|${font.weight ?? ''}|${font.style ?? ''}|${sha256(font.data)}`)
+        .join('\n'));
+    return { fonts, fontsHash, defaultTemplate: defaults?.template };
+}
+/**
+ * Image state for one page while it renders.
+ */
+export class PageImages {
+    runtime;
+    page;
+    /** Source files whose content affects the page */
+    assetDeps = new Set();
+    /** Processed images and cards, filtered against the written HTML when the page commits */
+    uses = [];
+    /** The Markdown image that `eagerFirst` loads eagerly, chosen by `renderMarkdown()` */
+    eagerToken;
+    context;
+    constructor(runtime, page) {
+        this.runtime = runtime;
+        this.page = page;
+        this.context = {
+            pageSourcePath: page.sourcePath,
+            srcDir: runtime.srcDir,
+            staticDir: runtime.staticDir,
+        };
+    }
+    /**
+     * Renders a Markdown image token.
+     *
+     * @returns The markup, or the `src` to give markdown-it's default renderer when the image
+     *   is left as authored
+     */
+    renderMarkdownImage(token, alt) {
+        const attributes = (token.attrs ?? []).filter(([name]) => !['src', 'alt', 'title', 'width', 'height'].includes(name.toLowerCase()));
+        return this.renderImage(token.attrGet('src') ?? '', {
+            alt,
+            title: token.attrGet('title') ?? undefined,
+            attributes,
+            width: token.attrGet('width') ?? undefined,
+            height: token.attrGet('height') ?? undefined,
+            eager: this.runtime.settings.eagerFirst && token === this.eagerToken,
+        });
+    }
+    /**
+     * Implements `stati.image(src, options)` for templates. Synchronous, because templates
+     * print its result directly.
+     */
+    renderHelperImage(src, options = {}) {
+        if (typeof src !== 'string' || !src.trim()) {
+            return '';
+        }
+        if (options.alt === undefined) {
+            this.runtime.warnOnce(`alt:${this.page.url}:${src}`, `stati.image('${src}') on ${this.page.url} has no alt text. Pass { alt: '' } for decorative images.`);
+        }
+        const markupOptions = {
+            alt: options.alt ?? '',
+            title: options.title,
+            attributes: options.class ? [['class', options.class]] : undefined,
+            eager: options.priority === true,
+            sizes: options.sizes,
+        };
+        const result = this.renderImage(src, markupOptions);
+        return 'html' in result ? result.html : renderImg(result.src, markupOptions);
+    }
+    renderImage(rawSrc, options) {
+        const resolved = resolveImageSource(rawSrc, this.context);
+        if (resolved.kind === 'skip') {
+            return { src: resolved.src };
+        }
+        const filePath = resolved.filePath;
+        this.assetDeps.add(toPosix(filePath));
+        const info = this.runtime.inspect(filePath);
+        const shownPath = toPosix(relative(process.cwd(), filePath));
+        if (!info) {
+            this.runtime.warnOnce(`missing:${filePath}`, `Image not found: ${shownPath} (used by ${this.page.url}). It is left as written.`);
+            return { src: resolved.src };
+        }
+        if (!info.probe) {
+            this.runtime.warnOnce(`unreadable:${filePath}`, `Could not read the dimensions of ${shownPath}. It is left as written.`);
+            return { src: resolved.src };
+        }
+        const probe = info.probe;
+        const base = {
+            ...options,
+            width: options.width ?? probe.width,
+            height: options.height ?? probe.height,
+        };
+        let tier1Src = resolved.src;
+        let copy;
+        if (resolved.kind === 'colocated') {
+            copy = planCopy(filePath, info.hash, probe.format);
+            tier1Src = copy.url;
+        }
+        const tier1Markup = renderImg(tier1Src, base);
+        const responsive = this.runtime.responsive;
+        const provider = this.runtime.provider;
+        if (responsive && provider && !probe.animated) {
+            const plan = planVariants({
+                filePath,
+                sourceHash: info.hash,
+                format: probe.format,
+                width: probe.width,
+                responsive,
+                providerVersion: provider.version,
+            });
+            const markup = renderResponsiveImage(plan, base, options.sizes ?? responsive.sizes);
+            this.runtime.registerJob(this.runtime.variantJob(plan, filePath));
+            this.uses.push({
+                jobKey: plan.key,
+                outputs: plan.outputs.map((output) => output.relPath),
+                marker: plan.fallback.src,
+                markup,
+                fallbackMarkup: tier1Markup,
+                ...(copy && { fallbackCopy: this.runtime.copyJob(copy, filePath) }),
+            });
+            return { html: markup };
+        }
+        if (copy) {
+            const job = this.runtime.copyJob(copy, filePath);
+            this.runtime.registerJob(job);
+            this.uses.push({ jobKey: job.key, outputs: [copy.relPath], marker: copy.url });
+        }
+        return { html: tier1Markup };
+    }
+    /**
+     * Whether this page gets a generated Open Graph image.
+     */
+    wantsOg() {
+        const { og, ogState, provider } = this.runtime;
+        return Boolean(og && ogState && provider?.renderOgImage && !isOgImageExcluded(this.page, og.exclude));
+    }
+    /**
+     * Size of the page's Open Graph image, exposed to the template as `stati.og`.
+     */
+    ogSize() {
+        const og = this.runtime.og;
+        return og ? { width: og.width, height: og.height } : undefined;
+    }
+    /**
+     * Renders this page's Open Graph template and registers the card.
+     *
+     * @param context - Template context: the layout's, with an empty body and `stati.og`
+     * @param eta - The template engine
+     * @returns The generated image, or null when the page gets none
+     */
+    async renderOg(context, eta) {
+        const { og, ogState, provider } = this.runtime;
+        if (!og || !ogState || !provider?.renderOgImage)
+            return null;
+        if (isOgImageExcluded(this.page, og.exclude))
+            return null;
+        const srcDir = this.runtime.srcDir;
+        const templatePath = await findOgTemplatePath(this.page.sourcePath, srcDir, og.template);
+        if (!templatePath && !ogState.defaultTemplate)
+            return null;
+        const templateLabel = templatePath
+            ? displayTemplatePath(templatePath)
+            : 'built-in Open Graph template';
+        let html;
+        try {
+            html = templatePath
+                ? await eta.renderAsync(toPosix(relative(srcDir, templatePath)), context)
+                : await eta.renderStringAsync(ogState.defaultTemplate, context);
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (this.runtime.development) {
+                throw createTemplateError(failure, templatePath ?? undefined);
+            }
+            this.runtime.logger.error(`Failed to render ${templateLabel} for ${this.page.url}: ${failure.message}`);
+            return null;
+        }
+        const inlined = await inlineLocalImages(html, {
+            staticDir: this.runtime.staticDir,
+            baseDir: templatePath ? dirname(templatePath) : srcDir,
+            srcDir,
+        }, (path) => this.runtime.generatedSourceFor(path));
+        for (const file of inlined.files)
+            this.assetDeps.add(file);
+        const key = sha256(JSON.stringify({
+            html: inlined.html,
+            width: og.width,
+            height: og.height,
+            format: og.format,
+            fonts: ogState.fontsHash,
+            provider: provider.version,
+        }));
+        const extension = og.format === 'jpeg' ? 'jpg' : 'png';
+        const slug = ogImageSlug(this.page.url);
+        const relPath = posix.join(IMAGES_OUTPUT_DIR, OG_IMAGES_SUBDIR, `${slug}-${key.slice(0, 8)}.${extension}`);
+        const path = `/${relPath}`;
+        const title = this.page.frontMatter.title;
+        const image = {
+            url: resolveAbsoluteUrl(path, this.runtime.baseUrl),
+            path,
+            width: og.width,
+            height: og.height,
+            ...(typeof title === 'string' && title && { alt: title }),
+        };
+        // The slug is part of the key: pages that draw the same card each get their own file
+        const jobKey = `og:${slug}:${key}`;
+        const filePath = join(this.runtime.outDir, relPath);
+        const render = provider.renderOgImage.bind(provider);
+        this.runtime.registerJob({
+            key: jobKey,
+            outputs: [relPath],
+            label: `${templateLabel} (${this.page.url})`,
+            run: () => render({
+                html: inlined.html,
+                width: og.width,
+                height: og.height,
+                format: og.format,
+                fonts: ogState.fonts,
+                filePath,
+                templatePath: templateLabel,
+            }),
+        });
+        this.uses.push({ jobKey, outputs: [relPath], marker: path, ogImage: image });
+        return image;
+    }
+}
+/**
+ * The image pipeline for one build.
+ */
+export class ImageRuntime {
+    settings;
+    provider;
+    ogState;
+    manifest;
+    existing;
+    srcDir;
+    staticDir;
+    outDir;
+    cacheDir;
+    baseUrl;
+    logger;
+    development;
+    /** Responsive options in effect for this build; null when off or skipped in dev */
+    responsive;
+    /** Open Graph options in effect for this build; null when off or skipped in dev */
+    og;
+    /** Counters for the build summary and metrics */
+    stats = { generated: 0, cached: 0, failed: 0 };
+    specs = new Map();
+    /** Source file of each generated image registered this build, by URL path */
+    generatedSources = new Map();
+    jobs = new Map();
+    failures = new Map();
+    records = [];
+    touched = new Set();
+    warned = new Set();
+    /** Whether the images manifest changed and needs saving */
+    dirty = false;
+    constructor(settings, provider, ogState, manifest, existing, srcDir, staticDir, outDir, cacheDir, baseUrl, logger, development, generate) {
+        this.settings = settings;
+        this.provider = provider;
+        this.ogState = ogState;
+        this.manifest = manifest;
+        this.existing = existing;
+        this.srcDir = srcDir;
+        this.staticDir = staticDir;
+        this.outDir = outDir;
+        this.cacheDir = cacheDir;
+        this.baseUrl = baseUrl;
+        this.logger = logger;
+        this.development = development;
+        this.responsive = generate ? settings.responsive : null;
+        this.og = generate && ogState ? settings.og : null;
+    }
+    /**
+     * Creates the pipeline for a build.
+     *
+     * @returns The runtime, or null when images are turned off with `images: false`
+     * @throws {ConfigValidationError} When the `images` block is invalid
+     * @throws {Error} When a feature needs `@stati/images` and it is missing or incompatible,
+     *   or when an Open Graph font or `site.baseUrl` is unusable
+     */
+    static async create(config, options) {
+        validateImagesConfig(config.images);
+        const settings = resolveImagesConfig(config.images);
+        if (!settings)
+            return null;
+        const generate = !options.development || settings.dev === 'full';
+        const features = [];
+        if (settings.responsive)
+            features.push('responsive');
+        if (settings.og)
+            features.push('og');
+        // The package must be installed whenever a feature is on, even when dev skips it
+        const provider = features.length > 0 ? await loadImageProvider({ features, load: generate }) : null;
+        let ogState = null;
+        if (generate && settings.og && provider) {
+            if (!options.development) {
+                validateOgBaseUrl(config.site.baseUrl);
+            }
+            ogState = await loadOgState(provider, settings.og.fonts);
+        }
+        const manifest = await loadImagesManifest(options.cacheDir);
+        seedSourceCache(manifest.sources);
+        const existing = new Set(listFilesRecursiveSync(join(options.outDir, IMAGES_OUTPUT_DIR)).map((file) => `${IMAGES_OUTPUT_DIR}/${file}`));
+        const srcDir = join(process.cwd(), config.srcDir || DEFAULT_SRC_DIR);
+        const staticDir = join(process.cwd(), config.staticDir || DEFAULT_STATIC_DIR);
+        if (await pathExists(join(staticDir, IMAGES_OUTPUT_DIR))) {
+            options.logger.warning(`${toPosix(relative(process.cwd(), join(staticDir, IMAGES_OUTPUT_DIR)))} shares its URL with generated images (/${IMAGES_OUTPUT_DIR}/). Move those files to another folder.`);
+        }
+        return new ImageRuntime(settings, provider, ogState, manifest, existing, srcDir, staticDir, options.outDir, options.cacheDir, config.site.baseUrl, options.logger, options.development, generate);
+    }
+    /**
+     * Settings that change generated HTML, added to every page's render-inputs hash.
+     */
+    fingerprint() {
+        const hasFeatures = this.settings.responsive !== null || this.settings.og !== null;
+        return {
+            version: IMAGE_PIPELINE_VERSION,
+            eagerFirst: this.settings.eagerFirst,
+            ...(hasFeatures && { generate: this.responsive !== null || this.og !== null }),
+            ...(this.responsive && { responsive: this.responsive }),
+            ...(this.og &&
+                this.ogState && {
+                og: {
+                    template: this.og.template,
+                    width: this.og.width,
+                    height: this.og.height,
+                    format: this.og.format,
+                    exclude: this.og.exclude,
+                    fonts: this.ogState.fontsHash,
+                },
+            }),
+            ...(this.provider && { provider: this.provider.version }),
+        };
+    }
+    /**
+     * Creates the image state for a page about to render.
+     */
+    createPageContext(page) {
+        return new PageImages(this, page);
+    }
+    /**
+     * Whether every generated file a cached page references still exists.
+     */
+    outputsExist(images) {
+        return (images ?? []).every((image) => this.existing.has(image));
+    }
+    /**
+     * Records a written page and starts the jobs for the images its HTML actually contains.
+     *
+     * @param pageImages - The page's image state
+     * @param html - The final HTML of the page
+     * @param info - Output path and cache key of the page
+     * @returns The files to record on the page's cache entry
+     */
+    commitPage(pageImages, html, info) {
+        // Partials are pre-rendered for every page, so keep only images the page really shows
+        const used = pageImages.uses.filter((use) => html.includes(use.marker));
+        for (const use of used) {
+            this.startJob(use.jobKey);
+        }
+        if (used.length > 0) {
+            this.records.push({ ...info, uses: used });
+        }
+        return {
+            assetDeps: [...pageImages.assetDeps].sort(),
+            images: [...new Set(used.flatMap((use) => use.outputs))].sort(),
+        };
+    }
+    /**
+     * Waits for every job, then rewrites pages whose images failed so they show plain images,
+     * and marks those pages stale so the next build retries.
+     *
+     * @param cacheManifest - The ISG manifest, updated in place
+     */
+    async settle(cacheManifest) {
+        await Promise.all(this.jobs.values());
+        const failures = [];
+        if (this.failures.size === 0) {
+            return { patchedPages: 0, failures };
+        }
+        for (const [key, error] of this.failures) {
+            const spec = this.specs.get(key);
+            failures.push({
+                label: spec?.label ?? key,
+                message: error.message,
+                og: key.startsWith('og:'),
+            });
+        }
+        let patchedPages = 0;
+        for (const record of this.records) {
+            const failed = record.uses.filter((use) => this.failures.has(use.jobKey));
+            if (failed.length === 0)
+                continue;
+            const html = await readFile(record.outputPath);
+            if (html === null)
+                continue;
+            let patched = html;
+            const removed = new Set();
+            const added = new Set();
+            for (const use of failed) {
+                use.outputs.forEach((output) => removed.add(output));
+                if (use.fallbackCopy) {
+                    this.registerJob(use.fallbackCopy);
+                    this.startJob(use.fallbackCopy.key);
+                    await this.jobs.get(use.fallbackCopy.key);
+                    if (!this.failures.has(use.fallbackCopy.key)) {
+                        use.fallbackCopy.outputs.forEach((output) => added.add(output));
+                    }
+                }
+                if (use.markup !== undefined && use.fallbackMarkup !== undefined) {
+                    patched = patched.split(use.markup).join(use.fallbackMarkup);
+                }
+                if (use.ogImage) {
+                    const tags = generatedOgImageTags(use.ogImage);
+                    for (const tag of [...tags.openGraph, ...tags.twitter]) {
+                        patched = patched.split(tag).join('');
+                    }
+                }
+            }
+            if (patched !== html) {
+                await writeFile(record.outputPath, patched, 'utf-8');
+            }
+            const entry = cacheManifest.entries[record.cacheKey];
+            if (entry) {
+                const { images: previous, ...rest } = entry;
+                const images = [
+                    ...new Set([...(previous ?? []).filter((image) => !removed.has(image)), ...added]),
+                ].sort();
+                cacheManifest.entries[record.cacheKey] = {
+                    ...rest,
+                    inputsHash: 'STALE',
+                    ...(images.length > 0 && { images }),
+                };
+            }
+            patchedPages++;
+        }
+        for (const failure of failures) {
+            this.logger.warning(`Image generation failed for ${failure.label}: ${failure.message}. ${failure.og ? 'The page has no generated og:image' : 'Pages show the original image'} until the next build.`);
+        }
+        return { patchedPages, failures };
+    }
+    /**
+     * Saves the images manifest.
+     */
+    async save() {
+        if (!this.dirty && this.touched.size === 0)
+            return;
+        this.manifest.sources = getSourceCacheEntries(new Set([...Object.keys(this.manifest.sources), ...this.touched]));
+        await saveImagesManifest(this.cacheDir, this.manifest);
+        this.dirty = false;
+    }
+    /**
+     * Deletes generated files no page of this build references. Only files recorded in the
+     * images manifest are ever deleted.
+     *
+     * @param liveImages - Generated files referenced by this build's pages
+     * @param liveSources - Source files referenced by this build's pages
+     * @returns Number of files deleted
+     */
+    async prune(liveImages, liveSources) {
+        const imagesDir = join(this.outDir, IMAGES_OUTPUT_DIR);
+        let removedFiles = 0;
+        let changed = false;
+        for (const [key, record] of Object.entries(this.manifest.outputs)) {
+            if (record.files.some((file) => liveImages.has(file)))
+                continue;
+            for (const file of record.files) {
+                const filePath = join(this.outDir, file);
+                if (isPathWithinDirectory(imagesDir, filePath) && (await pathExists(filePath))) {
+                    await remove(filePath);
+                    removedFiles++;
+                }
+            }
+            delete this.manifest.outputs[key];
+            changed = true;
+        }
+        for (const path of Object.keys(this.manifest.sources)) {
+            if (!liveSources.has(path)) {
+                delete this.manifest.sources[path];
+                changed = true;
+            }
+        }
+        if (changed) {
+            await saveImagesManifest(this.cacheDir, this.manifest);
+        }
+        return removedFiles;
+    }
+    /**
+     * Inspects a source image and remembers it for the manifest.
+     */
+    inspect(filePath) {
+        this.touched.add(toPosix(filePath));
+        return inspectSourceSync(filePath);
+    }
+    /**
+     * Logs a warning once per build.
+     */
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        this.logger.warning(message);
+    }
+    /**
+     * Registers a job. It only runs once a written page references its outputs.
+     */
+    registerJob(spec) {
+        if (!this.specs.has(spec.key)) {
+            this.specs.set(spec.key, spec);
+        }
+        if (spec.sourcePath) {
+            for (const output of spec.outputs)
+                this.generatedSources.set(`/${output}`, spec.sourcePath);
+        }
+    }
+    /**
+     * The source file of an image this build generates, by its URL path, such as
+     * `/_img/hero-1a2b3c4d-960.webp`.
+     */
+    generatedSourceFor(path) {
+        return this.generatedSources.get(path);
+    }
+    /**
+     * Job that copies a co-located image to its hashed URL.
+     */
+    copyJob(plan, sourcePath) {
+        const target = join(this.outDir, plan.relPath);
+        return {
+            key: plan.key,
+            outputs: [plan.relPath],
+            label: toPosix(relative(process.cwd(), sourcePath)),
+            sourcePath,
+            run: () => copyFile(sourcePath, target),
+        };
+    }
+    /**
+     * Job that encodes the responsive variants of an image.
+     */
+    variantJob(plan, sourcePath) {
+        const provider = this.provider;
+        return {
+            key: plan.key,
+            outputs: plan.outputs.map((output) => output.relPath),
+            label: toPosix(relative(process.cwd(), sourcePath)),
+            sourcePath,
+            run: () => provider.createVariants({
+                sourcePath,
+                outputs: plan.outputs.map((output) => ({
+                    filePath: join(this.outDir, output.relPath),
+                    width: output.width,
+                    format: output.format,
+                    ...(output.quality !== undefined && { quality: output.quality }),
+                })),
+            }),
+        };
+    }
+    startJob(key) {
+        if (this.jobs.has(key))
+            return;
+        const spec = this.specs.get(key);
+        if (!spec)
+            return;
+        if (this.manifest.outputs[key] && spec.outputs.every((output) => this.existing.has(output))) {
+            this.stats.cached++;
+            this.jobs.set(key, Promise.resolve());
+            return;
+        }
+        const promise = (async () => {
+            for (const dir of new Set(spec.outputs.map((output) => dirname(join(this.outDir, output))))) {
+                await ensureDir(dir);
+            }
+            await spec.run();
+            this.manifest.outputs[key] = { files: [...spec.outputs] };
+            this.dirty = true;
+            for (const output of spec.outputs)
+                this.existing.add(output);
+            this.stats.generated++;
+        })().catch(async (error) => {
+            this.failures.set(key, error instanceof Error ? error : new Error(String(error)));
+            this.stats.failed++;
+            // Outputs this run wrote before failing are recorded nowhere, so pruning would never
+            // remove them. Files that existed when the build started stay: cached pages may show them.
+            await Promise.all(spec.outputs
+                .filter((output) => !this.existing.has(output))
+                .map((output) => remove(join(this.outDir, output)).catch(() => undefined)));
+        });
+        this.jobs.set(key, promise);
+    }
+}