@stati/core 1.27.2 → 1.28.0

package/dist/images/config.js

@@ -0,0 +1,200 @@
+/**
+ * Validation and defaults for the `images` configuration block.
+ * @module images/config
+ */
+import { ConfigValidationError } from '../config/errors.js';
+import { DEFAULT_IMAGE_FORMATS, DEFAULT_IMAGE_QUALITY, DEFAULT_IMAGE_SIZES, DEFAULT_IMAGE_WIDTHS, DEFAULT_OG_HEIGHT, DEFAULT_OG_TEMPLATE, DEFAULT_OG_WIDTH, } from '../constants.js';
+const IMAGES_KEYS = ['eagerFirst', 'responsive', 'og', 'dev'];
+const RESPONSIVE_KEYS = ['widths', 'formats', 'quality', 'sizes'];
+const QUALITY_KEYS = ['avif', 'webp', 'jpeg', 'png'];
+const OG_KEYS = ['template', 'width', 'height', 'format', 'fonts', 'exclude'];
+const FONT_KEYS = ['name', 'path', 'weight', 'style'];
+const VARIANT_FORMATS = ['avif', 'webp'];
+const MAX_IMAGE_WIDTH = 16384;
+const MAX_OG_SIZE = 4096;
+function fail(message) {
+    throw new ConfigValidationError(message);
+}
+function describe(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function checkKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            fail(`Unknown option ${path}.${key}. Allowed options: ${allowed.join(', ')}.`);
+        }
+    }
+}
+function isIntegerInRange(value, min, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+}
+function validateResponsive(value) {
+    if (typeof value === 'boolean')
+        return;
+    if (!isPlainObject(value)) {
+        fail(`images.responsive must be true, false or an object (got ${describe(value)}).`);
+    }
+    checkKeys(value, RESPONSIVE_KEYS, 'images.responsive');
+    if (value.widths !== undefined) {
+        if (!Array.isArray(value.widths) ||
+            value.widths.length === 0 ||
+            !value.widths.every((w) => isIntegerInRange(w, 1, MAX_IMAGE_WIDTH))) {
+            fail(`images.responsive.widths must be a non-empty array of whole pixel widths between 1 and ${MAX_IMAGE_WIDTH} (got ${describe(value.widths)}).`);
+        }
+    }
+    if (value.formats !== undefined) {
+        if (!Array.isArray(value.formats) ||
+            !value.formats.every((f) => typeof f === 'string' && VARIANT_FORMATS.includes(f))) {
+            fail(`images.responsive.formats must be an array of 'avif' and 'webp' (got ${describe(value.formats)}).`);
+        }
+    }
+    if (value.quality !== undefined) {
+        if (!isPlainObject(value.quality)) {
+            fail(`images.responsive.quality must be an object (got ${describe(value.quality)}).`);
+        }
+        checkKeys(value.quality, QUALITY_KEYS, 'images.responsive.quality');
+        for (const [format, quality] of Object.entries(value.quality)) {
+            if (quality !== undefined && !isIntegerInRange(quality, 1, 100)) {
+                fail(`images.responsive.quality.${format} must be a whole number between 1 and 100 (got ${describe(quality)}).`);
+            }
+        }
+    }
+    if (value.sizes !== undefined && (typeof value.sizes !== 'string' || !value.sizes.trim())) {
+        fail(`images.responsive.sizes must be a non-empty string (got ${describe(value.sizes)}).`);
+    }
+}
+function validateFont(font, index) {
+    const path = `images.og.fonts[${index}]`;
+    if (!isPlainObject(font)) {
+        fail(`${path} must be an object with name and path (got ${describe(font)}).`);
+    }
+    checkKeys(font, FONT_KEYS, path);
+    if (typeof font.name !== 'string' || !font.name.trim()) {
+        fail(`${path}.name must be a non-empty string.`);
+    }
+    if (typeof font.path !== 'string' || !font.path.trim()) {
+        fail(`${path}.path must be a non-empty string.`);
+    }
+    if (font.weight !== undefined && !isIntegerInRange(font.weight, 100, 900)) {
+        fail(`${path}.weight must be a whole number between 100 and 900 (got ${describe(font.weight)}).`);
+    }
+    if (font.style !== undefined && font.style !== 'normal' && font.style !== 'italic') {
+        fail(`${path}.style must be 'normal' or 'italic' (got ${describe(font.style)}).`);
+    }
+}
+function validateOg(value) {
+    if (typeof value === 'boolean')
+        return;
+    if (!isPlainObject(value)) {
+        fail(`images.og must be true, false or an object (got ${describe(value)}).`);
+    }
+    checkKeys(value, OG_KEYS, 'images.og');
+    if (value.template !== undefined) {
+        if (typeof value.template !== 'string' ||
+            !value.template.endsWith('.eta') ||
+            /[/\\]/.test(value.template)) {
+            fail(`images.og.template must be a file name ending in .eta, such as 'og.eta' (got ${describe(value.template)}).`);
+        }
+    }
+    for (const dimension of ['width', 'height']) {
+        if (value[dimension] !== undefined && !isIntegerInRange(value[dimension], 1, MAX_OG_SIZE)) {
+            fail(`images.og.${dimension} must be a whole number of pixels between 1 and ${MAX_OG_SIZE} (got ${describe(value[dimension])}).`);
+        }
+    }
+    if (value.format !== undefined && value.format !== 'png' && value.format !== 'jpeg') {
+        fail(`images.og.format must be 'png' or 'jpeg' (got ${describe(value.format)}).`);
+    }
+    if (value.fonts !== undefined) {
+        if (!Array.isArray(value.fonts)) {
+            fail(`images.og.fonts must be an array (got ${describe(value.fonts)}).`);
+        }
+        value.fonts.forEach(validateFont);
+    }
+    if (value.exclude !== undefined) {
+        if (!Array.isArray(value.exclude) || !value.exclude.every((p) => typeof p === 'string')) {
+            fail(`images.og.exclude must be an array of URL glob patterns (got ${describe(value.exclude)}).`);
+        }
+    }
+}
+/**
+ * Validates the `images` configuration block.
+ *
+ * @param images - The `images` value from the config
+ * @throws {ConfigValidationError} When an option has the wrong type or value
+ */
+export function validateImagesConfig(images) {
+    if (images === undefined || images === false) {
+        return;
+    }
+    if (!isPlainObject(images)) {
+        fail(`images must be an object or false (got ${describe(images)}).`);
+    }
+    checkKeys(images, IMAGES_KEYS, 'images');
+    if (images.eagerFirst !== undefined && typeof images.eagerFirst !== 'boolean') {
+        fail(`images.eagerFirst must be true or false (got ${describe(images.eagerFirst)}).`);
+    }
+    if (images.dev !== undefined && images.dev !== 'fast' && images.dev !== 'full') {
+        fail(`images.dev must be 'fast' or 'full' (got ${describe(images.dev)}).`);
+    }
+    if (images.responsive !== undefined) {
+        validateResponsive(images.responsive);
+    }
+    if (images.og !== undefined) {
+        validateOg(images.og);
+    }
+}
+/**
+ * Applies defaults to the `images` configuration block.
+ * Expects a block that passed {@link validateImagesConfig}.
+ *
+ * @param images - The `images` value from the config
+ * @returns The resolved options, or `null` when images are turned off with `images: false`
+ */
+export function resolveImagesConfig(images) {
+    if (images === false) {
+        return null;
+    }
+    const config = images ?? {};
+    let responsive = null;
+    if (config.responsive) {
+        const options = config.responsive === true ? {} : config.responsive;
+        const quality = options.quality ?? {};
+        responsive = {
+            widths: [...new Set(options.widths ?? DEFAULT_IMAGE_WIDTHS)].sort((a, b) => a - b),
+            formats: [...new Set(options.formats ?? DEFAULT_IMAGE_FORMATS)],
+            quality: {
+                avif: quality.avif ?? DEFAULT_IMAGE_QUALITY.avif,
+                webp: quality.webp ?? DEFAULT_IMAGE_QUALITY.webp,
+                jpeg: quality.jpeg ?? DEFAULT_IMAGE_QUALITY.jpeg,
+                ...(quality.png !== undefined && { png: quality.png }),
+            },
+            sizes: options.sizes ?? DEFAULT_IMAGE_SIZES,
+        };
+    }
+    let og = null;
+    if (config.og) {
+        const options = config.og === true ? {} : config.og;
+        og = {
+            template: options.template ?? DEFAULT_OG_TEMPLATE,
+            width: options.width ?? DEFAULT_OG_WIDTH,
+            height: options.height ?? DEFAULT_OG_HEIGHT,
+            format: options.format ?? 'png',
+            fonts: options.fonts ?? [],
+            exclude: options.exclude ?? [],
+        };
+    }
+    return {
+        eagerFirst: config.eagerFirst ?? true,
+        responsive,
+        og,
+        dev: config.dev ?? 'fast',
+    };
+}

package/dist/images/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 type { ResolvedImagesConfig, ResolvedResponsiveConfig, ResolvedOgConfig } from './config.js';
+export { ImageRuntime, PageImages, validateOgBaseUrl } from './runtime.js';
+export type { StatiImageOptions, SettleResult, ImageRuntimeOptions } 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';
+export type { ImageProbeResult } from './utils/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

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