@stati/core 1.27.2 → 1.28.0

package/dist/core/isg/deps.js

@@ -1,7 +1,8 @@
 import { join, dirname, relative, posix } from 'node:path';
 import { pathExists, readFile, isCollectionIndexPage, discoverLayout, resolveSrcDir, } from '../utils/index.js';
 import glob from 'fast-glob';
-import { TEMPLATE_EXTENSION } from '../../constants.js';
+import { TEMPLATE_EXTENSION, DEFAULT_OG_TEMPLATE } from '../../constants.js';
+import { clearOgTemplateCache, findOgTemplatePath, isOgImageExcluded } from '../../images/og.js';
 /**
  * Per-build cache for template path resolution (glob results).
  * Cleared at the start of each build via clearTemplatePathCache().
@@ -19,6 +20,7 @@ const templateContentCache = new Map();
 export function clearTemplatePathCache() {
     templatePathCache.clear();
     templateContentCache.clear();
+    clearOgTemplateCache();
 }
 /**
  * Error thrown when a circular dependency is detected in templates.
@@ -78,6 +80,13 @@ export async function trackTemplateDependencies(page, config, allPages) {
         // This populates 'visited' with all actually-used templates (not just accessible ones)
         await collectTemplateDependencies(absoluteLayoutPath, srcDir, visited, currentPath);
     }
+    // The Open Graph template renders with the page, so it and its partials are dependencies too.
+    // It comes after the layout, which must stay first.
+    const ogTemplatePath = await resolveOgTemplateDependency(page, config);
+    if (ogTemplatePath) {
+        deps.push(ogTemplatePath);
+        await collectTemplateDependencies(ogTemplatePath, srcDir, visited, currentPath);
+    }
     // 2. Add all actually-used templates from the visited set
     // Filter to only include underscore directories (partials/components)
     // and normalize paths to POSIX format
@@ -110,6 +119,26 @@ export async function resolveLayoutDependency(page, config, allPages) {
     // Normalize to POSIX format for consistent manifest output across platforms
     return layoutPath ? posix.join(srcDir.replace(/\\/g, '/'), layoutPath) : null;
 }
+/**
+ * Resolves the Open Graph template a page renders with, when Open Graph images are on and the
+ * page does not opt out. Pages that use the built-in template have no file dependency.
+ *
+ * @param page - The page model
+ * @param config - Stati configuration
+ * @returns Absolute path to the template (POSIX format), or null
+ */
+export async function resolveOgTemplateDependency(page, config) {
+    const og = config.images ? config.images.og : undefined;
+    if (!og || !config.srcDir) {
+        return null;
+    }
+    const options = og === true ? {} : og;
+    if (isOgImageExcluded(page, options.exclude ?? [])) {
+        return null;
+    }
+    const templatePath = await findOgTemplatePath(page.sourcePath, resolveSrcDir(config), options.template ?? DEFAULT_OG_TEMPLATE);
+    return templatePath ? templatePath.replace(/\\/g, '/') : null;
+}
 /**
  * Resolves a template name to its file path.
  * Used for explicit layout specifications in front matter.

package/dist/core/isg/hash.d.ts

@@ -33,6 +33,16 @@ export declare function computeContentHash(content: string, frontMatter: Record<
  * ```
  */
 export declare function computeFileHash(filePath: string): Promise<string | null>;
+/**
+ * Computes a hash of a binary file, such as an image a page displays.
+ * Unlike {@link computeFileHash}, it hashes raw bytes, and a missing file hashes to a
+ * fixed sentinel: a page that references a missing image stays cached until the file
+ * appears, and then rebuilds.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns `sha256-…` for an existing file, `missing:<path>` otherwise
+ */
+export declare function computeBinaryFileHash(filePath: string): Promise<string>;
 /**
  * Computes a combined hash from content hash and dependency hashes.
  * This represents the complete input state for a page.

package/dist/core/isg/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/isg/hash.ts"],"names":[],"mappings":"AA+BA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAiBhG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8B9E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CASR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CAqCnE"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/isg/hash.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAiBhG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8B9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CASR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CAqCnE"}

package/dist/core/isg/hash.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readFile, pathExists } from '../utils/index.js';
+import { inspectSource } from '../../images/sources.js';
 /**
  * Creates a SHA-256 hash instance, updates it with data, and returns the hex digest.
  * Internal utility to eliminate duplicate hash creation patterns.
@@ -104,6 +105,19 @@ export async function computeFileHash(filePath) {
         return null;
     }
 }
+/**
+ * Computes a hash of a binary file, such as an image a page displays.
+ * Unlike {@link computeFileHash}, it hashes raw bytes, and a missing file hashes to a
+ * fixed sentinel: a page that references a missing image stays cached until the file
+ * appears, and then rebuilds.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns `sha256-…` for an existing file, `missing:<path>` otherwise
+ */
+export async function computeBinaryFileHash(filePath) {
+    const info = await inspectSource(filePath);
+    return info ? `sha256-${info.hash}` : `missing:${filePath.replace(/\\/g, '/')}`;
+}
 /**
  * Computes a combined hash from content hash and dependency hashes.
  * This represents the complete input state for a page.

package/dist/core/isg/index.d.ts

@@ -8,10 +8,11 @@
  */
 export { loadCacheManifest, saveCacheManifest, createEmptyManifest } from './manifest.js';
 export { shouldRebuildPage, createCacheEntry, updateCacheEntry } from './builder.js';
+export type { RenderedAssets } from './builder.js';
 export { BuildLockManager, withBuildLock } from './build-lock.js';
 export { DevServerLockManager } from './dev-server-lock.js';
 export { CircularDependencyError, trackTemplateDependencies, resolveTemplatePath, clearTemplatePathCache, } from './deps.js';
-export { computeContentHash, computeFileHash, computeInputsHash, computeNavigationHash, clearFileHashCache, } from './hash.js';
+export { computeContentHash, computeFileHash, computeBinaryFileHash, computeInputsHash, computeNavigationHash, clearFileHashCache, } from './hash.js';
 export { getSafeCurrentTime, parseSafeDate, computeEffectiveTTL, computeNextRebuildAt, isPageFrozen, applyAgingRules, } from './ttl.js';
 export { ISGConfigurationError, validateISGConfig, validatePageISGOverrides, extractNumericOverride, } from './validation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/isg/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/isg/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrF,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/isg/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/core/isg/index.js

@@ -16,7 +16,7 @@ export { DevServerLockManager } from './dev-server-lock.js';
 // Dependency tracking
 export { CircularDependencyError, trackTemplateDependencies, resolveTemplatePath, clearTemplatePathCache, } from './deps.js';
 // Hash computation
-export { computeContentHash, computeFileHash, computeInputsHash, computeNavigationHash, clearFileHashCache, } from './hash.js';
+export { computeContentHash, computeFileHash, computeBinaryFileHash, computeInputsHash, computeNavigationHash, clearFileHashCache, } from './hash.js';
 // TTL and aging
 export { getSafeCurrentTime, parseSafeDate, computeEffectiveTTL, computeNextRebuildAt, isPageFrozen, applyAgingRules, } from './ttl.js';
 // Validation

package/dist/core/isg/manifest.js

@@ -229,6 +229,14 @@ function validateCacheEntry(entry, path) {
         console.warn(`Invalid cache entry for ${path}: "maxAgeCapDays" must be a number if present`);
         return false;
     }
+    for (const field of ['assetDeps', 'images']) {
+        const value = entryObj[field];
+        if (value !== undefined &&
+            (!Array.isArray(value) || !value.every((item) => typeof item === 'string'))) {
+            console.warn(`Invalid cache entry for ${path}: "${field}" must be an array of strings`);
+            return false;
+        }
+    }
     // Validate that deps and tags arrays contain strings
     if (!entryObj.deps.every((dep) => typeof dep === 'string')) {
         console.warn(`Invalid cache entry for ${path}: all "deps" must be strings`);

package/dist/core/markdown.d.ts

@@ -1,5 +1,6 @@
 import MarkdownIt from 'markdown-it';
 import type { StatiConfig, TocEntry } from '../types/index.js';
+import type { PageImages } from '../images/runtime.js';
 /**
  * Result of rendering markdown content.
  */
@@ -29,13 +30,21 @@ export declare function createMarkdownProcessor(config: StatiConfig): Promise<Ma
  * @returns Array of TOC entries extracted from headings (levels 2-6)
  */
 export declare function extractToc(content: string, md: MarkdownIt): TocEntry[];
+/**
+ * Options for {@link renderMarkdown}.
+ */
+export interface RenderMarkdownOptions {
+    /** Image state of the page being rendered; without it images are left as authored */
+    images?: PageImages | undefined;
+}
 /**
  * Renders markdown content to HTML with optional TOC extraction.
  *
  * @param content - The markdown content to render
  * @param md - The configured MarkdownIt instance
  * @param tocEnabled - Whether to extract TOC and inject heading anchors (default: true)
+ * @param options - Page-specific rendering state
  * @returns Object containing rendered HTML and TOC entries
  */
-export declare function renderMarkdown(content: string, md: MarkdownIt, tocEnabled?: boolean): MarkdownResult;
+export declare function renderMarkdown(content: string, md: MarkdownIt, tocEnabled?: boolean, options?: RenderMarkdownOptions): MarkdownResult;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/core/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/core/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAKrC,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,EAAE,QAAQ,EAAE,CAAC;CACjB;AAQD;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAmBD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAkDtF;AA6ED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,QAAQ,EAAE,CAGtE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,UAAU,EACd,UAAU,GAAE,OAAc,GACzB,cAAc,CAWhB"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/core/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAKrC,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,EAAE,QAAQ,EAAE,CAAC;CACjB;AAQD;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAmBD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAsDtF;AA6ED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,QAAQ,EAAE,CAGtE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,UAAU,EACd,UAAU,GAAE,OAAc,EAC1B,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAkBhB"}

package/dist/core/markdown.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import { slugify } from './utils/index.js';
 import { isDevelopment } from '../env.js';
+import { installImageRule, selectEagerImage, IMAGES_ENV_KEY } from '../images/markdown-rule.js';
 /**
  * Cached markdown processor for dev mode to avoid re-creating on each rebuild.
  * This significantly improves rebuild performance by avoiding repeated plugin loading.
@@ -48,6 +49,9 @@ export async function createMarkdownProcessor(config) {
         linkify: true,
         typographer: true,
     });
+    // Image dimensions, lazy loading and responsive variants. Installed first so plugins and
+    // markdown.configure can still replace the image rule.
+    installImageRule(md);
     // Apply plugins from array format
     if (config.markdown?.plugins) {
         for (const plugin of config.markdown.plugins) {
@@ -168,14 +172,20 @@ export function extractToc(content, md) {
  * @param content - The markdown content to render
  * @param md - The configured MarkdownIt instance
  * @param tocEnabled - Whether to extract TOC and inject heading anchors (default: true)
+ * @param options - Page-specific rendering state
  * @returns Object containing rendered HTML and TOC entries
  */
-export function renderMarkdown(content, md, tocEnabled = true) {
+export function renderMarkdown(content, md, tocEnabled = true, options = {}) {
+    // The same env object goes to parsing and rendering so renderer rules see the page's state
+    const env = options.images ? { [IMAGES_ENV_KEY]: options.images } : {};
     // Parse content into tokens
-    const tokens = md.parse(content, {});
+    const tokens = md.parse(content, env);
     // Extract TOC and inject anchor IDs
     const toc = extractAndInjectAnchors(tokens, tocEnabled);
+    if (options.images) {
+        options.images.eagerToken = selectEagerImage(tokens);
+    }
     // Render tokens to HTML
-    const html = md.renderer.render(tokens, md.options, {});
+    const html = md.renderer.render(tokens, md.options, env);
     return { html, toc };
 }

package/dist/core/templates.d.ts

@@ -1,5 +1,7 @@
 import { Eta } from 'eta';
 import type { StatiConfig, PageModel, NavNode, TocEntry, Logger } from '../types/index.js';
+import type { PageImages } from '../images/runtime.js';
+import type { GeneratedOgImage } from '../types/index.js';
 /**
  * Result of rendering a page template.
  */
@@ -8,6 +10,15 @@ export interface RenderResult {
     html: string;
     /** Number of templates loaded (layout + partials) */
     templatesLoaded: number;
+    /** Open Graph image generated for the page, if any */
+    ogImage?: GeneratedOgImage | undefined;
+}
+/**
+ * Page-specific state for {@link renderPage}.
+ */
+export interface RenderPageExtras {
+    /** Image state of the page; without it `stati.image()` emits a plain `<img>` */
+    images?: PageImages | undefined;
 }
 /**
  * Clear the cached template engine. Call this when templates change in dev mode
@@ -15,5 +26,5 @@ export interface RenderResult {
  */
 export declare function clearTemplateEngineCache(): void;
 export declare function createTemplateEngine(config: StatiConfig): Eta;
-export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets, toc?: TocEntry[], logger?: Logger): Promise<RenderResult>;
+export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[], assets?: import('../types/index.js').StatiAssets, toc?: TocEntry[], logger?: Logger, extras?: RenderPageExtras): Promise<RenderResult>;
 //# sourceMappingURL=templates.d.ts.map

package/dist/core/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,OAAO,EAEP,QAAQ,EACR,MAAM,EACP,MAAM,mBAAmB,CAAC;AAmB3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;CACzB;AAgND;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CA2B7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,EAChD,GAAG,CAAC,EAAE,QAAQ,EAAE,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CA0MvB"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,OAAO,EAEP,QAAQ,EACR,MAAM,EACP,MAAM,mBAAmB,CAAC;AAkB3B,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAgOD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CA2B7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,EACtB,MAAM,CAAC,EAAE,OAAO,mBAAmB,EAAE,WAAW,EAChD,GAAG,CAAC,EAAE,QAAQ,EAAE,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,YAAY,CAAC,CA0PvB"}

package/dist/core/templates.js

@@ -5,7 +5,22 @@ import { createFallbackLogger } from './utils/index.js';
 import { TEMPLATE_EXTENSION } from '../constants.js';
 import { getStatiVersion, isCollectionIndexPage, discoverLayout, getCollectionPathForPage, resolveSrcDir, createTemplateError, createValidatingPartialsProxy, createValidatingContextProxy, propValue, wrapPartialsAsCallable, createNavigationHelpers, } from './utils/index.js';
 import { isDevelopment, isProduction } from '../env.js';
-import { generateSEO } from '../seo/index.js';
+import { generateSEO, resolveGeneratedImagePlaceholders } from '../seo/index.js';
+/**
+ * `stati.image()` when images are turned off: a plain `<img>`, attributes escaped.
+ */
+function renderPlainImage(src, options = {}) {
+    if (typeof src !== 'string' || !src.trim()) {
+        return '';
+    }
+    const attributes = [
+        `src="${escapeHtml(src)}"`,
+        `alt="${escapeHtml(options.alt ?? '')}"`,
+        ...(options.title ? [`title="${escapeHtml(options.title)}"`] : []),
+        ...(options.class ? [`class="${escapeHtml(options.class)}"`] : []),
+    ];
+    return `<img ${attributes.join(' ')}>`;
+}
 /**
  * Groups pages by their tags for aggregation purposes.
  *
@@ -215,8 +230,15 @@ export function createTemplateEngine(config) {
     }
     return eta;
 }
-export async function renderPage(page, body, config, eta, navigation, allPages, assets, toc, logger) {
+export async function renderPage(page, body, config, eta, navigation, allPages, assets, toc, logger, extras) {
     const log = logger || createFallbackLogger();
+    const pageImages = extras?.images;
+    // The generated Open Graph image is known once the og template has rendered, after the
+    // partials. Until then stati.generateSEO() emits placeholders for its tags.
+    const ogState = {
+        image: undefined,
+        pending: pageImages?.wantsOg() ?? false,
+    };
     // Discover partials for this page's directory hierarchy
     const srcDir = resolveSrcDir(config);
     const relativePath = relative(srcDir, page.sourcePath);
@@ -274,12 +296,24 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             version: getStatiVersion(),
         },
         // Stati utilities object with helper functions
-        generateSEO: (tags) => generateSEO({ page, config, site: config.site }, tags),
+        generateSEO: (tags) => generateSEO({
+            page,
+            config,
+            site: config.site,
+            generatedImage: ogState.image,
+            deferGeneratedImage: ogState.pending,
+        }, tags),
         propValue,
+        // Image with dimensions, lazy loading and, with images.responsive, srcset variants
+        image: (src, options) => pageImages ? pageImages.renderHelperImage(src, options) : renderPlainImage(src, options),
         assets, // TypeScript bundle assets (available when typescript.enabled is true)
         // Set by callable partials invoked with props; always present so that
         // stati.props?.x works under the dev-mode context validation
         props: undefined,
+        // Set while the Open Graph template renders: { width, height }
+        og: undefined,
+        // The page's generated Open Graph image, once rendered: { url, path, width, height, alt }
+        ogImage: undefined,
     };
     // Render partials and store their content
     // Use multiple passes to allow partials to reference other partials
@@ -345,6 +379,23 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             break;
         }
     }
+    // Render the Open Graph template with the layout's context, minus the page body, so the
+    // generated image is known before the layout renders its SEO tags
+    if (pageImages && ogState.pending) {
+        const ogBaseContext = {
+            ...baseContext,
+            content: '',
+            page: { ...baseContext.page, content: '' },
+            og: pageImages.ogSize(),
+        };
+        const ogContext = createValidatingContextProxy({
+            ...ogBaseContext,
+            partials: createValidatingPartialsProxy(wrapPartialsAsCallable(eta, renderedPartials, partialPaths, ogBaseContext)),
+        });
+        ogState.image = (await pageImages.renderOg(ogContext, eta)) ?? undefined;
+        ogState.pending = false;
+        baseContext.ogImage = ogState.image;
+    }
     // Wrap final rendered partials as callable before passing to layout context
     const callablePartials = wrapPartialsAsCallable(eta, renderedPartials, partialPaths, baseContext);
     const context = createValidatingContextProxy({
@@ -354,10 +405,14 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     try {
         if (!layoutPath) {
             log.warning('No layout template found, using fallback');
-            return { html: createFallbackHtml(page, body), templatesLoaded };
+            return { html: createFallbackHtml(page, body), templatesLoaded, ogImage: ogState.image };
         }
         const html = await eta.renderAsync(layoutPath, context);
-        return { html, templatesLoaded };
+        return {
+            html: resolveGeneratedImagePlaceholders(html, ogState.image),
+            templatesLoaded,
+            ogImage: ogState.image,
+        };
     }
     catch (error) {
         log.error(`Error rendering layout ${layoutPath || 'unknown'}: ${error instanceof Error ? error.message : String(error)}`);
@@ -366,7 +421,7 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), layoutPath || undefined);
             throw templateError;
         }
-        return { html: createFallbackHtml(page, body), templatesLoaded };
+        return { html: createFallbackHtml(page, body), templatesLoaded, ogImage: ogState.image };
     }
 }
 function createFallbackHtml(page, body) {

package/dist/core/utils/fs.utils.d.ts

@@ -1,5 +1,5 @@
 import fse from 'fs-extra';
-import type { WriteFileOptions } from 'node:fs';
+import type { WriteFileOptions, Stats } from 'node:fs';
 /**
  * Safely reads a file with consistent error handling.
  */
@@ -34,4 +34,24 @@ export declare function readdir<T extends boolean = false>(dirPath: string, opti
  * Copies a file with consistent error handling.
  */
 export declare function copyFile(src: string, dest: string): Promise<void>;
+/**
+ * Reads a file as raw bytes. Returns null if the file does not exist.
+ */
+export declare function readFileBuffer(filePath: string): Promise<Buffer | null>;
+/**
+ * Reads a file as raw bytes synchronously. Returns null if the file does not exist.
+ * For code that must stay synchronous, such as template helpers.
+ */
+export declare function readFileBufferSync(filePath: string): Buffer | null;
+/**
+ * Gets file stats synchronously. Returns null if the path does not exist.
+ */
+export declare function statSyncOrNull(filePath: string): Stats | null;
+/**
+ * Lists every file under a directory, recursively.
+ *
+ * @param dirPath - Directory to list
+ * @returns Paths relative to `dirPath` with forward slashes; empty if the directory does not exist
+ */
+export declare function listFilesRecursiveSync(dirPath: string): string[];
 //# sourceMappingURL=fs.utils.d.ts.map

package/dist/core/utils/fs.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/fs.utils.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAkDhD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,OAAO,GAAG,MAAgB,GACnC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExD;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,CAAC,SAAS,OAAO,GAAG,KAAK,EACrD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,CAAC,CAAA;CAAE,GAC9B,OAAO,CAAC,CAAC,SAAS,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAcnD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE"}
+{"version":3,"file":"fs.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/fs.utils.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAmDvD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,OAAO,GAAG,MAAgB,GACnC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExD;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,CAAC,SAAS,OAAO,GAAG,KAAK,EACrD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,CAAC,CAAA;CAAE,GAC9B,OAAO,CAAC,CAAC,SAAS,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAcnD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE7E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUlE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAU7D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAchE"}

package/dist/core/utils/fs.utils.js

@@ -1,4 +1,6 @@
 import fse from 'fs-extra';
+import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
 const { readFile: fseReadFile, writeFile: fseWriteFile, pathExists: fsePathExists, ensureDir: fseEnsureDir, remove: fseRemove, stat: fseStat, readdir: fseReaddir, copyFile: fseCopyFile, } = fse;
 /**
  * Wraps fs-extra operations with consistent error handling.
@@ -86,3 +88,62 @@ export async function readdir(dirPath, options) {
 export async function copyFile(src, dest) {
     return wrapFsOperation('copy', fseCopyFile(src, dest), `${src} to ${dest}`);
 }
+/**
+ * Reads a file as raw bytes. Returns null if the file does not exist.
+ */
+export async function readFileBuffer(filePath) {
+    return wrapFsOperationNullable('read file', fseReadFile(filePath), filePath);
+}
+/**
+ * Reads a file as raw bytes synchronously. Returns null if the file does not exist.
+ * For code that must stay synchronous, such as template helpers.
+ */
+export function readFileBufferSync(filePath) {
+    try {
+        return readFileSync(filePath);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT' || nodeError.code === 'ENOTDIR') {
+            return null;
+        }
+        throw new Error(`Failed to read file ${filePath}: ${nodeError.message}`, { cause: error });
+    }
+}
+/**
+ * Gets file stats synchronously. Returns null if the path does not exist.
+ */
+export function statSyncOrNull(filePath) {
+    try {
+        return statSync(filePath);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT' || nodeError.code === 'ENOTDIR') {
+            return null;
+        }
+        throw new Error(`Failed to get stats for ${filePath}: ${nodeError.message}`, { cause: error });
+    }
+}
+/**
+ * Lists every file under a directory, recursively.
+ *
+ * @param dirPath - Directory to list
+ * @returns Paths relative to `dirPath` with forward slashes; empty if the directory does not exist
+ */
+export function listFilesRecursiveSync(dirPath) {
+    let entries;
+    try {
+        entries = readdirSync(dirPath, { withFileTypes: true, recursive: true });
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT' || nodeError.code === 'ENOTDIR') {
+            return [];
+        }
+        throw new Error(`Failed to read directory ${dirPath}: ${nodeError.message}`, { cause: error });
+    }
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(dirPath, join(entry.parentPath, entry.name)).replace(/\\/g, '/'));
+}

package/dist/core/utils/index.d.ts

@@ -2,7 +2,7 @@
  * Core utilities index
  * @module core/utils
  */
-export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, } from './fs.utils.js';
+export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, readFileBuffer, readFileBufferSync, statSyncOrNull, listFilesRecursiveSync, } from './fs.utils.js';
 export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, normalizePathForComparison, isPathWithinDirectory, } from './paths.utils.js';
 export { discoverLayout, isCollectionIndexPage, getCollectionPathForPage, } from './template-discovery.utils.js';
 export { propValue } from './template.utils.js';

package/dist/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG/E,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/index.js

@@ -3,7 +3,7 @@
  * @module core/utils
  */
 // File system utilities
-export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, } from './fs.utils.js';
+export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, readFileBuffer, readFileBufferSync, statSyncOrNull, listFilesRecursiveSync, } from './fs.utils.js';
 // Path resolution utilities
 export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, normalizePathForComparison, isPathWithinDirectory, } from './paths.utils.js';
 // Template discovery utilities

package/dist/images/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Validation and defaults for the `images` configuration block.
+ * @module images/config
+ */
+import type { ImageVariantFormat, OgImageFontConfig, StatiConfig } from '../types/index.js';
+/** Responsive image options with defaults applied. */
+export interface ResolvedResponsiveConfig {
+    /** Candidate widths, ascending and unique */
+    widths: number[];
+    formats: ImageVariantFormat[];
+    quality: {
+        avif: number;
+        webp: number;
+        jpeg: number;
+        png?: number;
+    };
+    sizes: string;
+}
+/** Open Graph image options with defaults applied. */
+export interface ResolvedOgConfig {
+    template: string;
+    width: number;
+    height: number;
+    format: 'png' | 'jpeg';
+    fonts: OgImageFontConfig[];
+    exclude: string[];
+}
+/** The `images` block with defaults applied. */
+export interface ResolvedImagesConfig {
+    eagerFirst: boolean;
+    /** `null` when responsive images are off */
+    responsive: ResolvedResponsiveConfig | null;
+    /** `null` when Open Graph images are off */
+    og: ResolvedOgConfig | null;
+    dev: 'fast' | 'full';
+}
+/**
+ * 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 declare function validateImagesConfig(images: unknown): void;
+/**
+ * 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 declare function resolveImagesConfig(images: StatiConfig['images']): ResolvedImagesConfig | null;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/images/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAY5F,sDAAsD;AACtD,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC5C,4CAA4C;IAC5C,EAAE,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB;AA6JD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAqB1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,oBAAoB,GAAG,IAAI,CA0C9F"}