@stati/core 1.27.2 → 1.29.0

package/dist/core/isg/builder.js

@@ -1,4 +1,4 @@
-import { computeContentHash, computeFileHash, computeInputsHash } from './hash.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';
@@ -55,8 +55,74 @@ 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;
+        }
+    }
+    for (const flag of [entry.readsCollection, entry.readsNav]) {
+        if (flag !== undefined && typeof flag !== 'boolean') {
+            return false;
+        }
+    }
     return true;
 }
+/**
+ * Whether a cache entry records what its page read while rendering. Entries written before
+ * Stati recorded it don't, and their page must be rebuilt once: whether it depends on its
+ * collection or the navigation tree is unknown, and assuming it doesn't could keep stale
+ * listings or prev/next links.
+ *
+ * @param entry - The cache entry
+ * @returns True when `readsCollection` and `readsNav` are both recorded
+ */
+export function hasRecordedReads(entry) {
+    return typeof entry.readsCollection === 'boolean' && typeof entry.readsNav === 'boolean';
+}
+/**
+ * Tags a page's cache entry carries for `stati invalidate "tag:…"`: its front matter tags,
+ * plus the key and label of a generated page, so `tag:css` also refreshes `/tags/css`.
+ */
+function getCacheTags(page) {
+    const tags = Array.isArray(page.frontMatter.tags)
+        ? page.frontMatter.tags.filter((tag) => typeof tag === 'string')
+        : [];
+    if (page.generated) {
+        for (const tag of [page.generated.key, page.generated.label]) {
+            if (tag && !tags.includes(tag)) {
+                tags.push(tag);
+            }
+        }
+    }
+    return tags;
+}
+/**
+ * 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, and with what the render read.
+ */
+function withRenderedAssets(entry, rendered) {
+    const { assetDeps: _assetDeps, images: _images, readsCollection: _readsCollection, readsNav: _readsNav, ...rest } = entry;
+    return {
+        ...rest,
+        ...(rendered && rendered.assetDeps.length > 0 && { assetDeps: [...rendered.assetDeps] }),
+        ...(rendered && rendered.images.length > 0 && { images: [...rendered.images] }),
+        // Always written, false included: a missing flag means "unknown" and forces a rebuild
+        ...(rendered?.reads && {
+            readsCollection: rendered.reads.collection,
+            readsNav: rendered.reads.nav,
+        }),
+    };
+}
 /**
  * Determines if a page should be rebuilt based on ISG logic.
  * Checks content changes, dependency changes, TTL expiration, and freeze status.
@@ -133,6 +199,8 @@ export async function shouldRebuildPage(page, entry, config, allPages, now, rend
             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) {
@@ -215,6 +283,7 @@ export async function shouldRebuildPage(page, entry, config, allPages, now, rend
  * @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
@@ -222,7 +291,7 @@ export async function shouldRebuildPage(page, entry, config, allPages, now, rend
  * const entry = await createCacheEntry(page, config, pages, new Date());
  * ```
  */
-export async function createCacheEntry(page, config, allPages, renderedAt, renderInputsHash) {
+export async function createCacheEntry(page, config, allPages, renderedAt, renderInputsHash, rendered) {
     const timings = {};
     let start = performance.now();
     // Validate page-level ISG overrides first
@@ -245,13 +314,11 @@ export async function createCacheEntry(page, config, allPages, renderedAt, rende
             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
-    let tags = [];
-    if (Array.isArray(page.frontMatter.tags)) {
-        tags = page.frontMatter.tags.filter((tag) => typeof tag === 'string');
-    }
+    const tags = getCacheTags(page);
     // Get published date
     const publishedAt = getPublishedDateISO(page);
     // Compute effective TTL
@@ -287,7 +354,7 @@ export async function createCacheEntry(page, config, allPages, renderedAt, rende
     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
@@ -345,6 +412,7 @@ async function hasTemplateStructureChanged(entry) {
  * @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
@@ -352,7 +420,7 @@ async function hasTemplateStructureChanged(entry) {
  * const updatedEntry = await updateCacheEntry(existingEntry, page, config, pages, new Date());
  * ```
  */
-export async function updateCacheEntry(entry, page, config, allPages, 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)
@@ -380,16 +448,20 @@ export async function updateCacheEntry(entry, page, config, allPages, renderedAt
                     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,
+                // Front matter tags, and a generated page's label, can change without a layout change
+                tags: getCacheTags(page),
                 renderedAt: renderedAt.toISOString(),
-            };
+            }, rendered);
         }
     }
     // Full update - create new entry and preserve original publishedAt
-    const newEntry = await createCacheEntry(page, config, allPages, 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

@@ -50,6 +50,15 @@ export declare function trackTemplateDependencies(page: PageModel, config: Stati
  * @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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAuCnB;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;;;;;;;;;;;;;;;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.
@@ -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.
@@ -51,8 +61,10 @@ export declare function computeFileHash(filePath: string): Promise<string | null
  */
 export declare function computeInputsHash(contentHash: string, depsHashes: string[], renderInputsHash?: string): string;
 /**
- * Computes a hash of the navigation tree structure.
- * Used to detect when navigation has changed (title, url, order, children structure).
+ * Computes a hash of the navigation tree.
+ * Covers every field of a navigation node (title, url, path, order, publishedAt,
+ * isCollection and children), so pages that read the navigation rebuild when any of
+ * what they can show changes.
  *
  * @param navigation - The navigation tree to hash
  * @returns SHA-256 hash as a hex string

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,CAmBhG;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;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CA+CnE"}

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.
@@ -51,6 +52,9 @@ export function computeContentHash(content, frontMatter) {
     const sortKeys = (obj) => {
         if (obj === null || typeof obj !== 'object')
             return obj;
+        // A date has no keys to sort; kept as it is, it serializes as its ISO string, not {}
+        if (obj instanceof Date)
+            return obj;
         if (Array.isArray(obj))
             return obj.map(sortKeys);
         const sorted = {};
@@ -104,6 +108,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.
@@ -130,8 +147,10 @@ export function computeInputsHash(contentHash, depsHashes, renderInputsHash) {
     ]);
 }
 /**
- * Computes a hash of the navigation tree structure.
- * Used to detect when navigation has changed (title, url, order, children structure).
+ * Computes a hash of the navigation tree.
+ * Covers every field of a navigation node (title, url, path, order, publishedAt,
+ * isCollection and children), so pages that read the navigation rebuild when any of
+ * what they can show changes.
  *
  * @param navigation - The navigation tree to hash
  * @returns SHA-256 hash as a hex string
@@ -148,9 +167,18 @@ export function computeNavigationHash(navigation) {
             title: String(node.title ?? ''),
             url: String(node.url ?? ''),
         };
+        if (typeof node.path === 'string') {
+            normalized.path = node.path;
+        }
         if (node.order !== undefined && typeof node.order === 'number') {
             normalized.order = node.order;
         }
+        if (node.publishedAt instanceof Date && !Number.isNaN(node.publishedAt.getTime())) {
+            normalized.publishedAt = node.publishedAt.toISOString();
+        }
+        if (typeof node.isCollection === 'boolean') {
+            normalized.isCollection = node.isCollection;
+        }
         if (node.children && Array.isArray(node.children) && node.children.length > 0) {
             normalized.children = node.children.map((child) => normalizeNavNode(child));
         }

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

@@ -7,11 +7,13 @@
  * @module isg
  */
 export { loadCacheManifest, saveCacheManifest, createEmptyManifest } from './manifest.js';
-export { shouldRebuildPage, createCacheEntry, updateCacheEntry } from './builder.js';
+export { shouldRebuildPage, createCacheEntry, updateCacheEntry, hasRecordedReads, } from './builder.js';
+export type { RenderedAssets } from './builder.js';
+export { pruneOrphanedPages } from './prune.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,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,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

@@ -9,14 +9,16 @@
 // Manifest management
 export { loadCacheManifest, saveCacheManifest, createEmptyManifest } from './manifest.js';
 // Build decision logic
-export { shouldRebuildPage, createCacheEntry, updateCacheEntry } from './builder.js';
+export { shouldRebuildPage, createCacheEntry, updateCacheEntry, hasRecordedReads, } from './builder.js';
+// Removal of pages that no longer exist
+export { pruneOrphanedPages } from './prune.js';
 // Build locking
 export { BuildLockManager, withBuildLock } from './build-lock.js';
 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,20 @@ 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;
+        }
+    }
+    for (const field of ['readsCollection', 'readsNav']) {
+        if (entryObj[field] !== undefined && typeof entryObj[field] !== 'boolean') {
+            console.warn(`Invalid cache entry for ${path}: "${field}" must be a boolean if present`);
+            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/isg/prune.d.ts

@@ -0,0 +1,32 @@
+import type { CacheManifest } from '../../types/index.js';
+/**
+ * Result of {@link pruneOrphanedPages}.
+ */
+export interface PruneResult {
+    /** Cache keys whose output file was deleted */
+    removed: string[];
+    /** Output files that could not be deleted, with the reason */
+    failed: Array<{
+        key: string;
+        message: string;
+    }>;
+}
+/**
+ * Removes the output of pages that no longer exist, such as a deleted post or a tag that no
+ * post uses anymore.
+ *
+ * Every manifest entry whose cache key is not one of this build's pages is an orphan: its
+ * HTML file is deleted, then its entry is dropped from the manifest, and so are the folders
+ * that deleting it leaves empty. Only files the manifest records are deleted, so files from
+ * the static directory or from other tools in the output directory stay. Nothing is deleted
+ * outside the output directory, including through a folder that links to somewhere else, and
+ * neither is a file that one of this build's pages writes under another path.
+ *
+ * @param manifest - The cache manifest; orphaned entries are removed from it, except those
+ *   whose file could not be deleted, so the next build tries again
+ * @param liveKeys - Cache keys of this build's pages, rendered or served from the cache
+ * @param outDir - The output directory
+ * @returns The deleted outputs and the ones that could not be deleted
+ */
+export declare function pruneOrphanedPages(manifest: CacheManifest, liveKeys: ReadonlySet<string>, outDir: string): Promise<PruneResult>;
+//# sourceMappingURL=prune.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../../src/core/isg/prune.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAW1D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAuEtB"}

package/dist/core/isg/prune.js

@@ -0,0 +1,113 @@
+import { dirname, resolve } from 'node:path';
+import { isPathWithinDirectory, lstat, pathExists, readdir, realpath, remove, stat, } from '../utils/index.js';
+/**
+ * Removes the output of pages that no longer exist, such as a deleted post or a tag that no
+ * post uses anymore.
+ *
+ * Every manifest entry whose cache key is not one of this build's pages is an orphan: its
+ * HTML file is deleted, then its entry is dropped from the manifest, and so are the folders
+ * that deleting it leaves empty. Only files the manifest records are deleted, so files from
+ * the static directory or from other tools in the output directory stay. Nothing is deleted
+ * outside the output directory, including through a folder that links to somewhere else, and
+ * neither is a file that one of this build's pages writes under another path.
+ *
+ * @param manifest - The cache manifest; orphaned entries are removed from it, except those
+ *   whose file could not be deleted, so the next build tries again
+ * @param liveKeys - Cache keys of this build's pages, rendered or served from the cache
+ * @param outDir - The output directory
+ * @returns The deleted outputs and the ones that could not be deleted
+ */
+export async function pruneOrphanedPages(manifest, liveKeys, outDir) {
+    const result = { removed: [], failed: [] };
+    const outRoot = resolve(outDir);
+    let realRoot;
+    // Files of this build's pages, read the first time a file is about to be deleted. A stale
+    // entry can name one of them by another path: through a linked folder, or in other letter
+    // case after renaming About.md to about.md on a case-insensitive file system.
+    let liveFiles;
+    const isLiveFile = async (path) => {
+        const id = await fileIdentity(path);
+        if (id === undefined) {
+            return false;
+        }
+        if (!liveFiles) {
+            liveFiles = new Set();
+            for (const key of liveKeys) {
+                const liveId = await fileIdentity(resolve(outRoot, key.replace(/^\/+/, '')));
+                if (liveId !== undefined) {
+                    liveFiles.add(liveId);
+                }
+            }
+        }
+        return liveFiles.has(id);
+    };
+    for (const key of Object.keys(manifest.entries)) {
+        if (liveKeys.has(key)) {
+            continue;
+        }
+        // Cache keys are output paths relative to the output directory, such as /blog/post.html
+        const relativePath = key.replace(/^\/+/, '');
+        const outputPath = resolve(outRoot, relativePath);
+        let removed = false;
+        try {
+            if (relativePath.endsWith('.html') &&
+                outputPath !== outRoot &&
+                isPathWithinDirectory(outRoot, outputPath) &&
+                (await pathExists(outputPath)) &&
+                (await stat(outputPath)).isFile()) {
+                // Resolves links, so a folder linked to somewhere outside is left alone
+                realRoot ??= await realpath(outRoot);
+                if (isPathWithinDirectory(realRoot, await realpath(dirname(outputPath))) &&
+                    !(await isLiveFile(outputPath))) {
+                    await remove(outputPath);
+                    removed = true;
+                }
+            }
+        }
+        catch (error) {
+            // The entry stays, so the next build tries again
+            result.failed.push({ key, message: error instanceof Error ? error.message : String(error) });
+            continue;
+        }
+        delete manifest.entries[key];
+        if (removed) {
+            result.removed.push(key);
+            try {
+                await removeEmptyFolders(dirname(outputPath), outRoot);
+            }
+            catch {
+                // An empty folder left behind does no harm
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Identifies a file by its device and file number, which every path to the file shares.
+ *
+ * @returns The identity, or undefined when the file is missing or the file system reports no
+ *   file numbers
+ */
+async function fileIdentity(path) {
+    try {
+        const stats = await stat(path);
+        return stats.ino ? `${stats.dev}:${stats.ino}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Deletes a folder and its parents while they are empty, stopping at the output directory
+ * and at links, which stay even when the folder they point to is empty.
+ */
+async function removeEmptyFolders(folder, outRoot) {
+    let current = folder;
+    while (current !== outRoot && isPathWithinDirectory(outRoot, current)) {
+        if ((await lstat(current)).isSymbolicLink() || (await readdir(current)).length > 0) {
+            return;
+        }
+        await remove(current);
+        current = dirname(current);
+    }
+}

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