@stati/core 1.27.1 → 1.28.0

package/dist/images/index.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Image pipeline exports
+ * Intrinsic sizes, lazy loading and co-located images in core, plus the plumbing for
+ * responsive variants and Open Graph images rendered by `@stati/images`.
+ */
+export { resolveImagesConfig, validateImagesConfig } from './config.js';
+export { ImageRuntime, PageImages, validateOgBaseUrl } from './runtime.js';
+export { installImageRule, selectEagerImage } from './markdown-rule.js';
+export { findOgTemplatePath, clearOgTemplateCache } from './og.js';
+export { loadImageProvider, resolveImagesPackage, missingPackageMessage } from './provider.js';
+export { probeImage } from './utils/index.js';

package/dist/images/manifest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The images manifest, `.stati/images/manifest.json`: which files each image job produced,
+ * and cached hashes and probes of source images.
+ * @module images/manifest
+ */
+import type { SourceInfo } from './sources.js';
+/**
+ * Persisted state of the image pipeline.
+ */
+export interface ImagesManifest {
+    version: number;
+    /** Cached facts about source images, keyed by absolute path */
+    sources: Record<string, SourceInfo>;
+    /** Files each job wrote, relative to the output directory, keyed by job key */
+    outputs: Record<string, {
+        files: string[];
+    }>;
+}
+/**
+ * Creates an empty images manifest.
+ */
+export declare function createEmptyImagesManifest(): ImagesManifest;
+/**
+ * Path of the images manifest inside the cache directory.
+ */
+export declare function getImagesManifestPath(cacheDir: string): string;
+/**
+ * Loads the images manifest. A missing, unreadable or outdated manifest yields an empty one,
+ * which only means images are checked again.
+ */
+export declare function loadImagesManifest(cacheDir: string): Promise<ImagesManifest>;
+/**
+ * Saves the images manifest.
+ */
+export declare function saveImagesManifest(cacheDir: string, manifest: ImagesManifest): Promise<void>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/images/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/images/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK/C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,cAAc,CAE1D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAqClF;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/images/manifest.js

@@ -0,0 +1,69 @@
+/**
+ * The images manifest, `.stati/images/manifest.json`: which files each image job produced,
+ * and cached hashes and probes of source images.
+ * @module images/manifest
+ */
+import { join } from 'node:path';
+import { ensureDir, readFile, writeFile } from '../core/utils/index.js';
+import { IMAGES_CACHE_SUBDIR, MANIFEST_FILENAME } from '../constants.js';
+/** Bumped when the manifest layout changes; older manifests are discarded. */
+const IMAGES_MANIFEST_VERSION = 1;
+/**
+ * Creates an empty images manifest.
+ */
+export function createEmptyImagesManifest() {
+    return { version: IMAGES_MANIFEST_VERSION, sources: {}, outputs: {} };
+}
+/**
+ * Path of the images manifest inside the cache directory.
+ */
+export function getImagesManifestPath(cacheDir) {
+    return join(cacheDir, IMAGES_CACHE_SUBDIR, MANIFEST_FILENAME);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/**
+ * Loads the images manifest. A missing, unreadable or outdated manifest yields an empty one,
+ * which only means images are checked again.
+ */
+export async function loadImagesManifest(cacheDir) {
+    try {
+        const content = await readFile(getImagesManifestPath(cacheDir));
+        if (!content)
+            return createEmptyImagesManifest();
+        const parsed = JSON.parse(content);
+        if (parsed?.version !== IMAGES_MANIFEST_VERSION ||
+            typeof parsed.sources !== 'object' ||
+            typeof parsed.outputs !== 'object') {
+            return createEmptyImagesManifest();
+        }
+        const outputs = {};
+        for (const [key, record] of Object.entries(parsed.outputs ?? {})) {
+            if (record && isStringArray(record.files)) {
+                outputs[key] = { files: record.files };
+            }
+        }
+        const sources = {};
+        for (const [path, info] of Object.entries(parsed.sources ?? {})) {
+            if (info &&
+                typeof info.size === 'number' &&
+                typeof info.mtimeMs === 'number' &&
+                typeof info.hash === 'string') {
+                sources[path] = info;
+            }
+        }
+        return { version: IMAGES_MANIFEST_VERSION, sources, outputs };
+    }
+    catch {
+        return createEmptyImagesManifest();
+    }
+}
+/**
+ * Saves the images manifest.
+ */
+export async function saveImagesManifest(cacheDir, manifest) {
+    const path = getImagesManifestPath(cacheDir);
+    await ensureDir(join(cacheDir, IMAGES_CACHE_SUBDIR));
+    await writeFile(path, JSON.stringify(manifest, null, 2), 'utf-8');
+}

package/dist/images/markdown-rule.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The markdown-it `image` rule that adds dimensions, lazy loading and responsive variants.
+ * @module images/markdown-rule
+ */
+import type MarkdownIt from 'markdown-it';
+import type Token from 'markdown-it/lib/token.mjs';
+/** Key of the page's image state in the markdown-it `env`. */
+export declare const IMAGES_ENV_KEY = "statiImages";
+/**
+ * Installs the image rule. It holds no per-page state: each render passes its page's image
+ * state in `env`, and renders without it fall through to the previous rule. Installed before
+ * plugins and `markdown.configure`, so a custom image rule there replaces it.
+ *
+ * @param md - The markdown-it instance
+ */
+export declare function installImageRule(md: MarkdownIt): void;
+/**
+ * Picks the image `eagerFirst` loads eagerly: the document's first image, when it sits in
+ * one of the first top-level blocks. A first image further down is not the page's largest
+ * contentful paint, so it stays lazy.
+ *
+ * @param tokens - Parsed block tokens
+ * @returns The image token, or undefined
+ */
+export declare function selectEagerImage(tokens: Token[]): Token | undefined;
+//# sourceMappingURL=markdown-rule.d.ts.map

package/dist/images/markdown-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-rule.d.ts","sourceRoot":"","sources":["../../src/images/markdown-rule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,UAAU,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,MAAM,2BAA2B,CAAC;AAGnD,8DAA8D;AAC9D,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAO5C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAwBrD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,SAAS,CAanE"}

package/dist/images/markdown-rule.js

@@ -0,0 +1,60 @@
+/**
+ * The markdown-it `image` rule that adds dimensions, lazy loading and responsive variants.
+ * @module images/markdown-rule
+ */
+/** Key of the page's image state in the markdown-it `env`. */
+export const IMAGES_ENV_KEY = 'statiImages';
+/** An image counts as near the top of a page when it sits in one of the first blocks. */
+const EAGER_BLOCK_LIMIT = 3;
+/**
+ * Installs the image rule. It holds no per-page state: each render passes its page's image
+ * state in `env`, and renders without it fall through to the previous rule. Installed before
+ * plugins and `markdown.configure`, so a custom image rule there replaces it.
+ *
+ * @param md - The markdown-it instance
+ */
+export function installImageRule(md) {
+    const previous = md.renderer.rules.image ??
+        ((tokens, idx, options, _env, self) => self.renderToken(tokens, idx, options));
+    md.renderer.rules.image = (tokens, idx, options, env, self) => {
+        const images = env?.[IMAGES_ENV_KEY];
+        const token = tokens[idx];
+        if (!images || !token) {
+            return previous(tokens, idx, options, env, self);
+        }
+        const alt = self.renderInlineAsText(token.children ?? [], options, env);
+        const result = images.renderMarkdownImage(token, alt);
+        if ('html' in result) {
+            return result.html;
+        }
+        // Left as authored, apart from a stripped `?raw` suffix
+        if (result.src !== token.attrGet('src')) {
+            token.attrSet('src', result.src);
+        }
+        return previous(tokens, idx, options, env, self);
+    };
+}
+/**
+ * Picks the image `eagerFirst` loads eagerly: the document's first image, when it sits in
+ * one of the first top-level blocks. A first image further down is not the page's largest
+ * contentful paint, so it stays lazy.
+ *
+ * @param tokens - Parsed block tokens
+ * @returns The image token, or undefined
+ */
+export function selectEagerImage(tokens) {
+    let blocks = 0;
+    for (const token of tokens) {
+        if (token.level === 0 && token.nesting !== -1) {
+            blocks++;
+            if (blocks > EAGER_BLOCK_LIMIT)
+                return undefined;
+        }
+        if (token.type === 'inline') {
+            const image = token.children?.find((child) => child.type === 'image');
+            if (image)
+                return image;
+        }
+    }
+    return undefined;
+}

package/dist/images/markup.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HTML for processed images.
+ * @module images/markup
+ */
+import type { VariantPlan } from './plan.js';
+/**
+ * Attributes for an `<img>` element.
+ */
+export interface ImgMarkupOptions {
+    alt: string;
+    title?: string | undefined;
+    /** Other authored attributes, such as `class` or `id`, in order */
+    attributes?: ReadonlyArray<readonly [string, string]> | undefined;
+    width?: number | string | undefined;
+    height?: number | string | undefined;
+    /** Load eagerly with high fetch priority instead of lazily */
+    eager?: boolean | undefined;
+    srcset?: string | undefined;
+    sizes?: string | undefined;
+}
+/**
+ * Renders an `<img>` with dimensions, loading hints and authored attributes.
+ *
+ * @param src - Image URL
+ * @param options - Attributes
+ * @returns The `<img>` element
+ */
+export declare function renderImg(src: string, options: ImgMarkupOptions): string;
+/**
+ * Renders a responsive image: a `<picture>` with one `<source>` per modern format, or a
+ * plain `<img srcset>` when there are none.
+ *
+ * @param plan - The planned variants
+ * @param options - Attributes for the `<img>` fallback
+ * @param sizes - The `sizes` attribute
+ * @returns The `<picture>` or `<img>` element
+ */
+export declare function renderResponsiveImage(plan: VariantPlan, options: Omit<ImgMarkupOptions, 'srcset' | 'sizes'>, sizes: string): string;
+//# sourceMappingURL=markup.d.ts.map

package/dist/images/markup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.d.ts","sourceRoot":"","sources":["../../src/images/markup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAgB7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,mEAAmE;IACnE,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAClE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAMD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAexE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,OAAO,CAAC,EACnD,KAAK,EAAE,MAAM,GACZ,MAAM,CAgBR"}

package/dist/images/markup.js

@@ -0,0 +1,72 @@
+/**
+ * HTML for processed images.
+ * @module images/markup
+ */
+import { escapeHtml } from '../seo/utils/index.js';
+/** Attributes Stati sets itself; authored values for these are ignored or handled separately. */
+const MANAGED_ATTRIBUTES = new Set([
+    'src',
+    'srcset',
+    'sizes',
+    'alt',
+    'title',
+    'width',
+    'height',
+    'loading',
+    'decoding',
+    'fetchpriority',
+]);
+function attribute(name, value) {
+    return ` ${name}="${escapeHtml(String(value))}"`;
+}
+/**
+ * Renders an `<img>` with dimensions, loading hints and authored attributes.
+ *
+ * @param src - Image URL
+ * @param options - Attributes
+ * @returns The `<img>` element
+ */
+export function renderImg(src, options) {
+    let html = `<img${attribute('src', src)}`;
+    if (options.srcset)
+        html += attribute('srcset', options.srcset);
+    if (options.sizes)
+        html += attribute('sizes', options.sizes);
+    html += attribute('alt', options.alt);
+    if (options.title)
+        html += attribute('title', options.title);
+    for (const [name, value] of options.attributes ?? []) {
+        if (!MANAGED_ATTRIBUTES.has(name.toLowerCase())) {
+            html += attribute(name, value);
+        }
+    }
+    if (options.width !== undefined)
+        html += attribute('width', options.width);
+    if (options.height !== undefined)
+        html += attribute('height', options.height);
+    html += options.eager ? ' loading="eager" fetchpriority="high"' : ' loading="lazy"';
+    return `${html} decoding="async">`;
+}
+/**
+ * Renders a responsive image: a `<picture>` with one `<source>` per modern format, or a
+ * plain `<img srcset>` when there are none.
+ *
+ * @param plan - The planned variants
+ * @param options - Attributes for the `<img>` fallback
+ * @param sizes - The `sizes` attribute
+ * @returns The `<picture>` or `<img>` element
+ */
+export function renderResponsiveImage(plan, options, sizes) {
+    const img = renderImg(plan.fallback.src, {
+        ...options,
+        srcset: plan.fallback.srcset,
+        sizes,
+    });
+    if (plan.sources.length === 0) {
+        return img;
+    }
+    const sources = plan.sources
+        .map((source) => `<source${attribute('type', source.type)}${attribute('srcset', source.srcset)}${attribute('sizes', sizes)}>`)
+        .join('');
+    return `<picture>${sources}${img}</picture>`;
+}

package/dist/images/og.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Helpers for Open Graph image generation: template lookup, exclusions and inlining.
+ * @module images/og
+ */
+import type { PageModel } from '../types/index.js';
+/**
+ * Clears the Open Graph template lookup cache.
+ */
+export declare function clearOgTemplateCache(): void;
+/**
+ * Finds the Open Graph template for a page: the nearest file named `templateName` in the
+ * page's directory or one of its parents, up to the source directory.
+ *
+ * @param pageSourcePath - Absolute path of the page's Markdown file
+ * @param srcDir - Absolute source directory
+ * @param templateName - Template file name, such as `og.eta`
+ * @returns Absolute path of the template, or null when there is none
+ */
+export declare function findOgTemplatePath(pageSourcePath: string, srcDir: string, templateName: string): Promise<string | null>;
+/**
+ * Whether a page gets no generated Open Graph image: it sets its own image in front matter
+ * (`seo.openGraph.image`, or `false` to have none) or matches an `exclude` pattern.
+ */
+export declare function isOgImageExcluded(page: PageModel, exclude: readonly string[]): boolean;
+/**
+ * File name stem for a page's Open Graph image, from its URL.
+ * The root page is `index`; `/blog/hello/` becomes `blog-hello`.
+ */
+export declare function ogImageSlug(url: string): string;
+/**
+ * Replaces local `<img src>` values in Open Graph HTML with data URIs, because the renderer
+ * does not fetch files. Root-relative paths resolve from the static directory, relative ones
+ * from `baseDir`. Remote URLs and data URIs are left alone.
+ *
+ * @param generatedSource - Finds the source of an image Stati generates (`/_img/...`), such as
+ *   a responsive variant from `stati.image()`. Cards inline the source, because generated
+ *   files may not exist yet.
+ * @returns The HTML and the absolute paths of the files that were inlined
+ */
+export declare function inlineLocalImages(html: string, dirs: {
+    staticDir: string;
+    baseDir: string;
+    srcDir: string;
+}, generatedSource?: (path: string) => string | undefined): Promise<{
+    html: string;
+    files: string[];
+}>;
+/**
+ * The template path to show in messages, relative to the project.
+ */
+export declare function displayTemplatePath(templatePath: string): string;
+//# sourceMappingURL=og.d.ts.map

package/dist/images/og.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og.d.ts","sourceRoot":"","sources":["../../src/images/og.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAKnD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAOtF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU/C;AAsCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACrD,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwC5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/images/og.js

@@ -0,0 +1,165 @@
+/**
+ * Helpers for Open Graph image generation: template lookup, exclusions and inlining.
+ * @module images/og
+ */
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { isPathWithinDirectory, pathExists, readFileBuffer } from '../core/utils/index.js';
+import { matchesGlob } from '../core/utils/glob-patterns.utils.js';
+/** Cache of template lookups per directory, cleared at the start of each build. */
+const templateCache = new Map();
+/**
+ * Clears the Open Graph template lookup cache.
+ */
+export function clearOgTemplateCache() {
+    templateCache.clear();
+}
+/**
+ * Finds the Open Graph template for a page: the nearest file named `templateName` in the
+ * page's directory or one of its parents, up to the source directory.
+ *
+ * @param pageSourcePath - Absolute path of the page's Markdown file
+ * @param srcDir - Absolute source directory
+ * @param templateName - Template file name, such as `og.eta`
+ * @returns Absolute path of the template, or null when there is none
+ */
+export async function findOgTemplatePath(pageSourcePath, srcDir, templateName) {
+    const root = resolve(srcDir);
+    let dir = dirname(resolve(pageSourcePath));
+    const visited = [];
+    while (isPathWithinDirectory(root, dir)) {
+        const cacheKey = `${dir}|${templateName}`;
+        if (templateCache.has(cacheKey)) {
+            const cached = templateCache.get(cacheKey);
+            for (const key of visited)
+                templateCache.set(key, cached);
+            return cached;
+        }
+        visited.push(cacheKey);
+        const candidate = join(dir, templateName);
+        if (await pathExists(candidate)) {
+            for (const key of visited)
+                templateCache.set(key, candidate);
+            return candidate;
+        }
+        if (dir === root)
+            break;
+        dir = dirname(dir);
+    }
+    for (const key of visited)
+        templateCache.set(key, null);
+    return null;
+}
+/**
+ * Whether a page gets no generated Open Graph image: it sets its own image in front matter
+ * (`seo.openGraph.image`, or `false` to have none) or matches an `exclude` pattern.
+ */
+export function isOgImageExcluded(page, exclude) {
+    const seo = page.frontMatter.seo;
+    const image = seo?.openGraph?.image;
+    if (image !== undefined && image !== null && image !== '') {
+        return true;
+    }
+    return exclude.some((pattern) => matchesGlob(page.url, pattern));
+}
+/**
+ * File name stem for a page's Open Graph image, from its URL.
+ * The root page is `index`; `/blog/hello/` becomes `blog-hello`.
+ */
+export function ogImageSlug(url) {
+    const slug = url
+        .split('/')
+        .filter(Boolean)
+        .join('-')
+        .replace(/[^a-zA-Z0-9-_]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+    return slug || 'index';
+}
+const MIME_BY_EXTENSION = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+};
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+/**
+ * Decodes the character references in an attribute value: the ones Eta's escaping writes,
+ * and numeric ones.
+ */
+function decodeHtmlEntities(text) {
+    return text.replace(/&(#[xX][0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (match, entity) => {
+        if (!entity.startsWith('#'))
+            return NAMED_ENTITIES[entity];
+        const code = entity[1] === 'x' || entity[1] === 'X'
+            ? parseInt(entity.slice(2), 16)
+            : parseInt(entity.slice(1), 10);
+        return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
+    });
+}
+/**
+ * Replaces local `<img src>` values in Open Graph HTML with data URIs, because the renderer
+ * does not fetch files. Root-relative paths resolve from the static directory, relative ones
+ * from `baseDir`. Remote URLs and data URIs are left alone.
+ *
+ * @param generatedSource - Finds the source of an image Stati generates (`/_img/...`), such as
+ *   a responsive variant from `stati.image()`. Cards inline the source, because generated
+ *   files may not exist yet.
+ * @returns The HTML and the absolute paths of the files that were inlined
+ */
+export async function inlineLocalImages(html, dirs, generatedSource) {
+    const files = [];
+    // `[^<>]` keeps each match inside one tag, so unclosed tags can't make the search quadratic
+    const pattern = /(<img\b[^<>]*?\bsrc\s*=\s*)("([^"]*)"|'([^']*)')/gi;
+    const replacements = [];
+    for (const match of html.matchAll(pattern)) {
+        // The value is HTML-escaped: `a&amp;b.png` names the file `a&b.png`
+        const src = decodeHtmlEntities(match[3] ?? match[4] ?? '').trim();
+        if (!src || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(src))
+            continue;
+        let path;
+        try {
+            path = decodeURIComponent(src.replace(/[?#].*$/, ''));
+        }
+        catch {
+            continue;
+        }
+        let filePath = generatedSource?.(path);
+        if (!filePath) {
+            filePath = path.startsWith('/') ? join(dirs.staticDir, path) : resolve(dirs.baseDir, path);
+            const root = path.startsWith('/') ? dirs.staticDir : dirs.srcDir;
+            if (!isPathWithinDirectory(root, filePath))
+                continue;
+        }
+        const mime = MIME_BY_EXTENSION[extname(filePath).toLowerCase()];
+        if (!mime)
+            continue;
+        files.push(filePath.replace(/\\/g, '/'));
+        const bytes = await readFileBuffer(filePath);
+        if (!bytes)
+            continue;
+        const dataUri = `data:${mime};base64,${bytes.toString('base64')}`;
+        replacements.push({ match: match[0], replacement: `${match[1]}"${dataUri}"` });
+    }
+    let result = html;
+    for (const { match, replacement } of replacements) {
+        // A function, so `$&` and the like in the tag's other attributes stay literal
+        result = result.replace(match, () => replacement);
+    }
+    return { html: result, files };
+}
+/**
+ * The template path to show in messages, relative to the project.
+ */
+export function displayTemplatePath(templatePath) {
+    return relative(process.cwd(), templatePath).replace(/\\/g, '/') || templatePath;
+}

package/dist/images/plan.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Decides which files to generate for an image and what to call them.
+ * Names come from inputs, not from encoded bytes, so page HTML can be written before
+ * encoding finishes.
+ * @module images/plan
+ */
+import type { ImageOutputFormat, ImageSourceFormat } from '../types/index.js';
+import type { ResolvedResponsiveConfig } from './config.js';
+/**
+ * Picks the widths to generate for an image.
+ * Configured widths up to the image's own width are kept, and the image's own width is
+ * added when it is below the largest configured width. Images are never enlarged.
+ *
+ * @param intrinsicWidth - The image's display width
+ * @param configured - Candidate widths, ascending
+ * @returns Widths to generate, ascending
+ */
+export declare function planWidths(intrinsicWidth: number, configured: readonly number[]): number[];
+/**
+ * The format of the `<img>` fallback for a source format: the source's own format, except
+ * GIF, which becomes PNG.
+ */
+export declare function fallbackFormatFor(format: ImageSourceFormat): ImageOutputFormat;
+/**
+ * File extension for a format.
+ */
+export declare function extensionFor(format: ImageSourceFormat | ImageOutputFormat): string;
+/**
+ * MIME type for a generated format.
+ */
+export declare function mimeTypeFor(format: ImageOutputFormat): string;
+/**
+ * A URL-safe base name for generated files, from the source file name.
+ */
+export declare function imageBaseName(filePath: string): string;
+/** One file to generate, with its path relative to the output directory and its URL. */
+export interface PlannedOutput {
+    /** Path relative to the output directory, with forward slashes */
+    relPath: string;
+    /** Root-relative URL */
+    url: string;
+    width: number;
+    format: ImageOutputFormat;
+    quality?: number;
+}
+/**
+ * A copy of a co-located source image under its content-hashed name.
+ */
+export interface CopyPlan {
+    key: string;
+    /** Path relative to the output directory, with forward slashes */
+    relPath: string;
+    /** Root-relative URL */
+    url: string;
+}
+/**
+ * Plans the copy of a co-located image: `/_img/{name}-{hash}.{ext}`.
+ *
+ * @param filePath - Absolute source path
+ * @param sourceHash - SHA-256 of the source bytes
+ * @param format - Source format
+ */
+export declare function planCopy(filePath: string, sourceHash: string, format: ImageSourceFormat): CopyPlan;
+/**
+ * Generated files for one responsive image, grouped for markup.
+ */
+export interface VariantPlan {
+    /** Cache key covering the output name, source bytes, options and encoder */
+    key: string;
+    /** Every file to generate */
+    outputs: PlannedOutput[];
+    /** `<source>` elements, one per modern format, in order of preference */
+    sources: Array<{
+        type: string;
+        srcset: string;
+    }>;
+    /** The `<img>` fallback in the source's own format */
+    fallback: {
+        src: string;
+        srcset: string;
+    };
+}
+/**
+ * Inputs for {@link planVariants}.
+ */
+export interface VariantPlanInput {
+    filePath: string;
+    sourceHash: string;
+    format: ImageSourceFormat;
+    /** Display width */
+    width: number;
+    responsive: ResolvedResponsiveConfig;
+    /** Encoder identity, so encoder upgrades produce new URLs */
+    providerVersion: string;
+}
+/**
+ * Plans the responsive variants of one image: `/_img/{name}-{hash}-{width}.{ext}` for every
+ * width in each modern format, plus the fallback format.
+ */
+export declare function planVariants(input: VariantPlanInput): VariantPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/images/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/images/plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAa5D;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAU1F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CAE9E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,MAAM,CAElF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,GACxB,QAAQ,CAMV;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,yEAAyE;IACzE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sDAAsD;IACtD,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,wBAAwB,CAAC;IACrC,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;CACzB;AAaD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAiDjE"}