@stati/core 1.27.1 → 1.28.0

package/dist/core/isg/builder.js

@@ -1,5 +1,5 @@
-import { computeContentHash, computeFileHash, computeInputsHash } from './hash.js';
-import { trackTemplateDependencies } from './deps.js';
+import { computeContentHash, computeFileHash, computeBinaryFileHash, computeInputsHash, } from './hash.js';
+import { trackTemplateDependencies, resolveLayoutDependency } from './deps.js';
 import { computeEffectiveTTL, computeNextRebuildAt, isPageFrozen } from './ttl.js';
 import { validatePageISGOverrides, extractNumericOverride } from './validation.js';
 import { getFrontMatterDate } from '../utils/index.js';
@@ -55,8 +55,35 @@ function isValidCacheEntry(entry) {
     if (entry.maxAgeCapDays !== undefined && typeof entry.maxAgeCapDays !== 'number') {
         return false;
     }
+    for (const list of [entry.assetDeps, entry.images]) {
+        if (list !== undefined && (!Array.isArray(list) || !list.every((v) => typeof v === 'string'))) {
+            return false;
+        }
+    }
     return true;
 }
+/**
+ * Hashes render-discovered dependencies by content. Missing files hash to a sentinel.
+ */
+async function hashAssetDeps(assetDeps) {
+    const hashes = [];
+    for (const assetPath of assetDeps ?? []) {
+        hashes.push(await computeBinaryFileHash(assetPath));
+    }
+    return hashes;
+}
+/**
+ * Returns the entry with its `assetDeps` and `images` replaced by this render's,
+ * dropping the fields when a render found none.
+ */
+function withRenderedAssets(entry, rendered) {
+    const { assetDeps: _assetDeps, images: _images, ...rest } = entry;
+    return {
+        ...rest,
+        ...(rendered && rendered.assetDeps.length > 0 && { assetDeps: [...rendered.assetDeps] }),
+        ...(rendered && rendered.images.length > 0 && { images: [...rendered.images] }),
+    };
+}
 /**
  * Determines if a page should be rebuilt based on ISG logic.
  * Checks content changes, dependency changes, TTL expiration, and freeze status.
@@ -65,19 +92,20 @@ function isValidCacheEntry(entry) {
  * @param page - The page model to check
  * @param entry - Existing cache entry, or undefined if not cached
  * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to resolve the same layout as rendering
  * @param now - Current date/time
  * @param renderInputsHash - Optional hash of asset URLs and injection settings
  * @returns True if the page should be rebuilt
  *
  * @example
  * ```typescript
- * const shouldRebuild = await shouldRebuildPage(page, cacheEntry, config, new Date());
+ * const shouldRebuild = await shouldRebuildPage(page, cacheEntry, config, pages, new Date());
  * if (shouldRebuild) {
  *   console.log('Page needs rebuilding');
  * }
  * ```
  */
-export async function shouldRebuildPage(page, entry, config, now, renderInputsHash) {
+export async function shouldRebuildPage(page, entry, config, allPages, now, renderInputsHash) {
     if (config.isg?.enabled === false) {
         return true;
     }
@@ -96,7 +124,7 @@ export async function shouldRebuildPage(page, entry, config, now, renderInputsHa
         // Track dependencies with error handling
         let deps;
         try {
-            deps = await trackTemplateDependencies(page, config);
+            deps = await trackTemplateDependencies(page, config, allPages);
         }
         catch (error) {
             if (error instanceof Error && error.name === 'CircularDependencyError') {
@@ -132,6 +160,8 @@ export async function shouldRebuildPage(page, entry, config, now, renderInputsHa
             console.warn(`${dependencyErrors} dependency errors for ${page.url}, forcing rebuild`);
             return true;
         }
+        // Files found during the last render, such as images, are hashed by content
+        depsHashes.push(...(await hashAssetDeps(entry.assetDeps)));
         const currentInputsHash = computeInputsHash(currentContentHash, depsHashes, renderInputsHash);
         // If inputs changed, always rebuild
         if (currentInputsHash !== entry.inputsHash) {
@@ -211,16 +241,18 @@ export async function shouldRebuildPage(page, entry, config, now, renderInputsHa
  *
  * @param page - The page model
  * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to resolve the same layout as rendering
  * @param renderedAt - When the page was rendered
  * @param renderInputsHash - Optional hash of asset URLs and injection settings
+ * @param rendered - Files the render discovered, such as images
  * @returns New cache entry
  *
  * @example
  * ```typescript
- * const entry = await createCacheEntry(page, config, new Date());
+ * const entry = await createCacheEntry(page, config, pages, new Date());
  * ```
  */
-export async function createCacheEntry(page, config, renderedAt, renderInputsHash) {
+export async function createCacheEntry(page, config, allPages, renderedAt, renderInputsHash, rendered) {
     const timings = {};
     let start = performance.now();
     // Validate page-level ISG overrides first
@@ -232,7 +264,7 @@ export async function createCacheEntry(page, config, renderedAt, renderInputsHas
     timings.contentHash = performance.now() - start;
     // Track all template dependencies
     start = performance.now();
-    const deps = await trackTemplateDependencies(page, config);
+    const deps = await trackTemplateDependencies(page, config, allPages);
     timings.trackDeps = performance.now() - start;
     // Compute hashes for all dependencies
     start = performance.now();
@@ -243,6 +275,7 @@ export async function createCacheEntry(page, config, renderedAt, renderInputsHas
             depsHashes.push(depHash);
         }
     }
+    depsHashes.push(...(await hashAssetDeps(rendered?.assetDeps)));
     timings.depsHashes = performance.now() - start;
     const inputsHash = computeInputsHash(contentHash, depsHashes, renderInputsHash);
     // Extract tags from front matter
@@ -285,7 +318,7 @@ export async function createCacheEntry(page, config, renderedAt, renderInputsHas
     if (maxAgeCapDays !== undefined) {
         cacheEntry.maxAgeCapDays = maxAgeCapDays;
     }
-    return cacheEntry;
+    return withRenderedAssets(cacheEntry, rendered);
 }
 /**
  * Checks if the template structure has changed by comparing the layout file's
@@ -339,26 +372,33 @@ async function hasTemplateStructureChanged(entry) {
  * @param entry - Existing cache entry
  * @param page - The page model
  * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to resolve the same layout as rendering
  * @param renderedAt - When the page was rendered
  * @param fastUpdate - If true, skip expensive dep tracking (dev mode optimization)
  * @param renderInputsHash - Optional hash of asset URLs and injection settings
+ * @param rendered - Files the render discovered, such as images
  * @returns Updated cache entry
  *
  * @example
  * ```typescript
- * const updatedEntry = await updateCacheEntry(existingEntry, page, config, new Date());
+ * const updatedEntry = await updateCacheEntry(existingEntry, page, config, pages, new Date());
  * ```
  */
-export async function updateCacheEntry(entry, page, config, renderedAt, fastUpdate = false, renderInputsHash) {
+export async function updateCacheEntry(entry, page, config, allPages, renderedAt, fastUpdate = false, renderInputsHash, rendered) {
     // In fast update mode (dev), reuse existing deps to avoid expensive tracking
     if (fastUpdate && entry.deps.length > 0) {
         // Detect if template structure has changed (new includes/extends added)
         // by checking if the layout file has been modified or if template content
         // contains different dependency patterns
         const structureChanged = await hasTemplateStructureChanged(entry);
-        if (structureChanged) {
-            // Template structure changed - fall through to full dependency tracking
-            // This ensures we pick up new includes/extends
+        // The page can also switch layouts without any template file changing, for example
+        // when a collection gains its first child page or a front matter layout is edited.
+        // deps[0] is always the layout, so compare it against the layout used now.
+        const layoutChanged = !structureChanged &&
+            (await resolveLayoutDependency(page, config, allPages)) !== entry.deps[0];
+        if (structureChanged || layoutChanged) {
+            // Template structure or layout changed - fall through to full dependency tracking
+            // This ensures we pick up new includes/extends and the newly selected layout
         }
         else {
             // Structure unchanged - safe to reuse existing deps
@@ -372,16 +412,18 @@ export async function updateCacheEntry(entry, page, config, renderedAt, fastUpda
                     depsHashes.push(depHash);
                 }
             }
+            // Asset deps come from this render, not from the previous entry
+            depsHashes.push(...(await hashAssetDeps(rendered?.assetDeps)));
             const inputsHash = computeInputsHash(contentHash, depsHashes, renderInputsHash);
-            return {
+            return withRenderedAssets({
                 ...entry,
                 inputsHash,
                 renderedAt: renderedAt.toISOString(),
-            };
+            }, rendered);
         }
     }
     // Full update - create new entry and preserve original publishedAt
-    const newEntry = await createCacheEntry(page, config, renderedAt, renderInputsHash);
+    const newEntry = await createCacheEntry(page, config, allPages, renderedAt, renderInputsHash, rendered);
     // Preserve original publishedAt if no new one is specified
     if (!newEntry.publishedAt && entry.publishedAt) {
         newEntry.publishedAt = entry.publishedAt;

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

@@ -22,13 +22,14 @@ export declare class CircularDependencyError extends Error {
  *
  * @param page - The page model to track dependencies for
  * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to detect collection index pages the same way rendering does
  * @returns Array of absolute paths to actually-used template files (POSIX format)
  * @throws {CircularDependencyError} When circular dependencies are detected in templates
  *
  * @example
  * ```typescript
  * try {
- *   const deps = await trackTemplateDependencies(page, config);
+ *   const deps = await trackTemplateDependencies(page, config, allPages);
  *   console.log(`Page depends on ${deps.length} template files`);
  * } catch (error) {
  *   if (error instanceof CircularDependencyError) {
@@ -37,7 +38,27 @@ export declare class CircularDependencyError extends Error {
  * }
  * ```
  */
-export declare function trackTemplateDependencies(page: PageModel, config: StatiConfig): Promise<string[]>;
+export declare function trackTemplateDependencies(page: PageModel, config: StatiConfig, allPages: PageModel[]): Promise<string[]>;
+/**
+ * Resolves the layout a page renders with, in the form stored as the first entry of its
+ * cache dependencies. Uses the same lookup as rendering, so callers can tell whether the
+ * page's layout has changed since its dependencies were recorded.
+ *
+ * @param page - The page model to resolve the layout for
+ * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to detect collection index pages the same way rendering does
+ * @returns Absolute path to the layout file (POSIX format), or null if no layout applies
+ */
+export declare function resolveLayoutDependency(page: PageModel, config: StatiConfig, allPages: PageModel[]): Promise<string | 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 declare function resolveOgTemplateDependency(page: PageModel, config: StatiConfig): Promise<string | null>;
 /**
  * Resolves a template name to its file path.
  * Used for explicit layout specifications in front matter.

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

@@ -1 +1 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../src/core/isg/deps.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAenE;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,eAAe,EAAE,MAAM,EAAE;gBAAzB,eAAe,EAAE,MAAM,EAAE,EACzC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}
+{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../src/core/isg/deps.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAgBnE;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAI7C;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,eAAe,EAAE,MAAM,EAAE;gBAAzB,eAAe,EAAE,MAAM,EAAE,EACzC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}

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.
@@ -42,13 +44,14 @@ export class CircularDependencyError extends Error {
  *
  * @param page - The page model to track dependencies for
  * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to detect collection index pages the same way rendering does
  * @returns Array of absolute paths to actually-used template files (POSIX format)
  * @throws {CircularDependencyError} When circular dependencies are detected in templates
  *
  * @example
  * ```typescript
  * try {
- *   const deps = await trackTemplateDependencies(page, config);
+ *   const deps = await trackTemplateDependencies(page, config, allPages);
  *   console.log(`Page depends on ${deps.length} template files`);
  * } catch (error) {
  *   if (error instanceof CircularDependencyError) {
@@ -57,7 +60,7 @@ export class CircularDependencyError extends Error {
  * }
  * ```
  */
-export async function trackTemplateDependencies(page, config) {
+export async function trackTemplateDependencies(page, config, allPages) {
     // Early return if required config values are missing
     if (!config.srcDir) {
         console.warn('Config srcDir is missing, cannot track template dependencies');
@@ -65,21 +68,25 @@ export async function trackTemplateDependencies(page, config) {
     }
     const deps = [];
     const srcDir = resolveSrcDir(config);
-    const relativePath = relative(srcDir, page.sourcePath);
     // Track dependencies with circular detection
     // The visited set will contain all templates that are actually used (not just accessible)
     const visited = new Set();
     const currentPath = new Set();
     // 1. Find the layout file that will be used for this page
-    const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isCollectionIndexPage(page));
-    if (layoutPath) {
-        // Normalize to POSIX format for consistent manifest output across platforms
-        const absoluteLayoutPath = posix.join(srcDir.replace(/\\/g, '/'), layoutPath);
+    const absoluteLayoutPath = await resolveLayoutDependency(page, config, allPages);
+    if (absoluteLayoutPath) {
         deps.push(absoluteLayoutPath);
         // Recursively traverse the template dependency tree
         // 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
@@ -93,6 +100,45 @@ export async function trackTemplateDependencies(page, config) {
     }
     return deps;
 }
+/**
+ * Resolves the layout a page renders with, in the form stored as the first entry of its
+ * cache dependencies. Uses the same lookup as rendering, so callers can tell whether the
+ * page's layout has changed since its dependencies were recorded.
+ *
+ * @param page - The page model to resolve the layout for
+ * @param config - Stati configuration
+ * @param allPages - All pages in the site, used to detect collection index pages the same way rendering does
+ * @returns Absolute path to the layout file (POSIX format), or null if no layout applies
+ */
+export async function resolveLayoutDependency(page, config, allPages) {
+    if (!config.srcDir) {
+        return null;
+    }
+    const srcDir = resolveSrcDir(config);
+    const layoutPath = await discoverLayout(relative(srcDir, page.sourcePath), config, page.frontMatter.layout, isCollectionIndexPage(page, 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"}