@stati/core 1.27.2 → 1.29.0

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

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