@stati/core 1.27.2 → 1.28.0

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"}

package/dist/images/plan.js

@@ -0,0 +1,128 @@
+/**
+ * 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 { createHash } from 'node:crypto';
+import { basename, extname, posix } from 'node:path';
+import { slugify } from '../core/utils/index.js';
+import { IMAGES_OUTPUT_DIR } from '../constants.js';
+/** Length of the hash in generated file names. */
+const NAME_HASH_LENGTH = 8;
+/** MIME types for `<source type>`. */
+const MIME_TYPES = {
+    avif: 'image/avif',
+    webp: 'image/webp',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+};
+/**
+ * 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 function planWidths(intrinsicWidth, configured) {
+    const widths = configured.filter((width) => width <= intrinsicWidth);
+    const largest = configured.length > 0 ? Math.max(...configured) : intrinsicWidth;
+    if (intrinsicWidth < largest && !widths.includes(intrinsicWidth)) {
+        widths.push(intrinsicWidth);
+    }
+    if (widths.length === 0) {
+        widths.push(intrinsicWidth);
+    }
+    return [...new Set(widths)].sort((a, b) => a - b);
+}
+/**
+ * The format of the `<img>` fallback for a source format: the source's own format, except
+ * GIF, which becomes PNG.
+ */
+export function fallbackFormatFor(format) {
+    return format === 'gif' ? 'png' : format;
+}
+/**
+ * File extension for a format.
+ */
+export function extensionFor(format) {
+    return format === 'jpeg' ? 'jpg' : format;
+}
+/**
+ * MIME type for a generated format.
+ */
+export function mimeTypeFor(format) {
+    return MIME_TYPES[format];
+}
+/**
+ * A URL-safe base name for generated files, from the source file name.
+ */
+export function imageBaseName(filePath) {
+    return slugify(basename(filePath, extname(filePath))) || 'image';
+}
+/**
+ * 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 function planCopy(filePath, sourceHash, format) {
+    const relPath = posix.join(IMAGES_OUTPUT_DIR, `${imageBaseName(filePath)}-${sourceHash.slice(0, NAME_HASH_LENGTH)}.${extensionFor(format)}`);
+    return { key: `copy:${relPath}`, relPath, url: `/${relPath}` };
+}
+function qualityFor(format, responsive) {
+    return responsive.quality[format];
+}
+function srcsetOf(outputs) {
+    return outputs.map((output) => `${output.url} ${output.width}w`).join(', ');
+}
+/**
+ * Plans the responsive variants of one image: `/_img/{name}-{hash}-{width}.{ext}` for every
+ * width in each modern format, plus the fallback format.
+ */
+export function planVariants(input) {
+    const widths = planWidths(input.width, input.responsive.widths);
+    const fallbackFormat = fallbackFormatFor(input.format);
+    const formats = input.responsive.formats.filter((format) => format !== fallbackFormat);
+    const hash = createHash('sha256')
+        .update(JSON.stringify({
+        source: input.sourceHash,
+        widths,
+        formats,
+        fallbackFormat,
+        quality: [...formats, fallbackFormat].map((f) => qualityFor(f, input.responsive) ?? null),
+        provider: input.providerVersion,
+    }))
+        .digest('hex');
+    const baseName = imageBaseName(input.filePath);
+    const name = `${baseName}-${hash.slice(0, NAME_HASH_LENGTH)}`;
+    const outputsFor = (format) => widths.map((width) => {
+        const relPath = posix.join(IMAGES_OUTPUT_DIR, `${name}-${width}.${extensionFor(format)}`);
+        const quality = qualityFor(format, input.responsive);
+        return {
+            relPath,
+            url: `/${relPath}`,
+            width,
+            format,
+            ...(quality !== undefined && { quality }),
+        };
+    });
+    const sourceOutputs = formats.map((format) => ({ format, outputs: outputsFor(format) }));
+    const fallbackOutputs = outputsFor(fallbackFormat);
+    return {
+        // The name is part of the key: identical files under different names get their own outputs
+        key: `variants:${baseName}:${hash}`,
+        outputs: [...sourceOutputs.flatMap((group) => group.outputs), ...fallbackOutputs],
+        sources: sourceOutputs.map((group) => ({
+            type: mimeTypeFor(group.format),
+            srcset: srcsetOf(group.outputs),
+        })),
+        fallback: {
+            src: fallbackOutputs[fallbackOutputs.length - 1].url,
+            srcset: srcsetOf(fallbackOutputs),
+        },
+    };
+}

package/dist/images/provider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Finds and loads the optional `@stati/images` package.
+ * @module images/provider
+ */
+import type { ImageProvider } from '../types/index.js';
+/** Provider contract version this core supports. */
+export declare const SUPPORTED_PROVIDER_API_VERSION = 1;
+/** Image features that need the package. */
+export type ImageFeature = 'responsive' | 'og';
+/**
+ * Resolves the package from the project, as markdown-it plugins are, so it is found under
+ * strict layouts such as pnpm's where core cannot see the project's dependencies.
+ * Resolution walks up from the project, which also covers workspaces.
+ *
+ * @returns The resolved entry file, or null when the package is not installed
+ */
+export declare function resolveImagesPackage(cwd?: string): string | null;
+/**
+ * The error shown when a feature is on but the package is missing.
+ */
+export declare function missingPackageMessage(features: ImageFeature[]): string;
+/**
+ * Checks that the package is installed and, when `load` is set, creates its provider.
+ *
+ * @param options.features - The features that are on; they decide the error message
+ * @param options.load - Whether to import the package; false only checks it is installed
+ * @returns The provider, or null when `load` is false
+ * @throws {Error} When the package is missing, fails to load, or is incompatible
+ */
+export declare function loadImageProvider(options: {
+    features: ImageFeature[];
+    load: boolean;
+    cwd?: string;
+}): Promise<ImageProvider | null>;
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/images/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,oDAAoD;AACpD,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAO/E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAItE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAuChC"}

package/dist/images/provider.js

@@ -0,0 +1,70 @@
+/**
+ * Finds and loads the optional `@stati/images` package.
+ * @module images/provider
+ */
+import { createRequire } from 'node:module';
+import { resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { IMAGES_PACKAGE_NAME } from '../constants.js';
+import { getStatiVersion } from '../core/utils/index.js';
+/** Provider contract version this core supports. */
+export const SUPPORTED_PROVIDER_API_VERSION = 1;
+/**
+ * Resolves the package from the project, as markdown-it plugins are, so it is found under
+ * strict layouts such as pnpm's where core cannot see the project's dependencies.
+ * Resolution walks up from the project, which also covers workspaces.
+ *
+ * @returns The resolved entry file, or null when the package is not installed
+ */
+export function resolveImagesPackage(cwd = process.cwd()) {
+    try {
+        const require = createRequire(pathToFileURL(resolvePath(cwd, 'package.json')));
+        return require.resolve(IMAGES_PACKAGE_NAME);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The error shown when a feature is on but the package is missing.
+ */
+export function missingPackageMessage(features) {
+    const names = features.map((feature) => `images.${feature}`).join(' and ');
+    const verb = features.length > 1 ? 'require' : 'requires';
+    return `${names} ${verb} ${IMAGES_PACKAGE_NAME}. Run: npm i -D ${IMAGES_PACKAGE_NAME}`;
+}
+/**
+ * Checks that the package is installed and, when `load` is set, creates its provider.
+ *
+ * @param options.features - The features that are on; they decide the error message
+ * @param options.load - Whether to import the package; false only checks it is installed
+ * @returns The provider, or null when `load` is false
+ * @throws {Error} When the package is missing, fails to load, or is incompatible
+ */
+export async function loadImageProvider(options) {
+    const entry = resolveImagesPackage(options.cwd);
+    if (!entry) {
+        throw new Error(missingPackageMessage(options.features));
+    }
+    if (!options.load) {
+        return null;
+    }
+    let provider;
+    try {
+        const module = (await import(pathToFileURL(entry).href));
+        if (typeof module.createImageProvider !== 'function') {
+            throw new Error(`${IMAGES_PACKAGE_NAME} does not export createImageProvider()`);
+        }
+        provider = await module.createImageProvider();
+    }
+    catch (error) {
+        throw new Error(`Failed to load ${IMAGES_PACKAGE_NAME}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (provider?.apiVersion !== SUPPORTED_PROVIDER_API_VERSION) {
+        throw new Error(`${IMAGES_PACKAGE_NAME} ${provider?.version ?? ''} is not compatible with @stati/core ${getStatiVersion()}. Update both packages.`.replace(/\s+/g, ' '));
+    }
+    if (options.features.includes('og') && typeof provider.renderOgImage !== 'function') {
+        throw new Error(`images.og needs a newer ${IMAGES_PACKAGE_NAME} (${provider.version}). Update the package.`);
+    }
+    return provider;
+}

package/dist/images/resolve.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Maps an image `src` as written in Markdown or a template to a file on disk.
+ * @module images/resolve
+ */
+/**
+ * Where an image's `src` points.
+ * - `skip`: leave the image alone (remote, SVG, unsupported, opted out or outside the site);
+ *   `src` is the value to emit, with any `?raw` suffix removed.
+ * - `static`: a file under the static directory, served at its own URL.
+ * - `colocated`: a file under the source directory, next to the page that uses it.
+ */
+export type ResolvedImageSource = {
+    kind: 'skip';
+    src: string;
+} | {
+    kind: 'static';
+    src: string;
+    filePath: string;
+} | {
+    kind: 'colocated';
+    src: string;
+    filePath: string;
+};
+/**
+ * Paths needed to resolve an image for one page.
+ */
+export interface ImageResolveContext {
+    /** Absolute path of the Markdown file being rendered */
+    pageSourcePath: string;
+    /** Absolute source directory */
+    srcDir: string;
+    /** Absolute static assets directory */
+    staticDir: string;
+}
+/**
+ * Resolves an image `src`.
+ * Root-relative paths (`/images/hero.jpg`) resolve from the static directory; relative
+ * paths (`./hero.jpg`) resolve next to the page's Markdown file.
+ *
+ * @param rawSrc - The `src` as authored
+ * @param context - The page and site directories
+ * @returns Where the image lives, or `skip` when it should be left as authored
+ */
+export declare function resolveImageSource(rawSrc: string, context: ImageResolveContext): ResolvedImageSource;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/images/resolve.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,mBAAmB,GAC3B,mBAAmB,CAmCrB"}

package/dist/images/resolve.js

@@ -0,0 +1,51 @@
+/**
+ * Maps an image `src` as written in Markdown or a template to a file on disk.
+ * @module images/resolve
+ */
+import { dirname, extname, join, resolve } from 'node:path';
+import { isPathWithinDirectory } from '../core/utils/index.js';
+/** Extensions Stati reads dimensions from. SVG and anything else are left as authored. */
+const SUPPORTED_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif']);
+/** Suffix that opts a single image out of processing. */
+const RAW_SUFFIX = '?raw';
+/**
+ * Resolves an image `src`.
+ * Root-relative paths (`/images/hero.jpg`) resolve from the static directory; relative
+ * paths (`./hero.jpg`) resolve next to the page's Markdown file.
+ *
+ * @param rawSrc - The `src` as authored
+ * @param context - The page and site directories
+ * @returns Where the image lives, or `skip` when it should be left as authored
+ */
+export function resolveImageSource(rawSrc, context) {
+    const src = rawSrc.trim();
+    if (!src)
+        return { kind: 'skip', src: rawSrc };
+    if (src.endsWith(RAW_SUFFIX)) {
+        return { kind: 'skip', src: src.slice(0, -RAW_SUFFIX.length) };
+    }
+    // Remote URLs, protocol-relative URLs and data URIs
+    if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(src)) {
+        return { kind: 'skip', src };
+    }
+    let path;
+    try {
+        path = decodeURIComponent(src.replace(/[?#].*$/, ''));
+    }
+    catch {
+        return { kind: 'skip', src };
+    }
+    if (!SUPPORTED_EXTENSIONS.has(extname(path).toLowerCase())) {
+        return { kind: 'skip', src };
+    }
+    if (path.startsWith('/')) {
+        const filePath = join(context.staticDir, path);
+        return isPathWithinDirectory(context.staticDir, filePath)
+            ? { kind: 'static', src, filePath }
+            : { kind: 'skip', src };
+    }
+    const filePath = resolve(dirname(context.pageSourcePath), path);
+    return isPathWithinDirectory(context.srcDir, filePath)
+        ? { kind: 'colocated', src, filePath }
+        : { kind: 'skip', src };
+}