@stati/core 1.29.2 → 2.0.1

package/dist/core/templates.js

@@ -1,12 +1,12 @@
 import { Eta } from 'eta';
-import { join, relative, basename, posix } from 'node:path';
-import glob from 'fast-glob';
-import { createFallbackLogger } from './utils/index.js';
-import { TEMPLATE_EXTENSION } from '../constants.js';
-import { getStatiVersion, isCollectionIndexPage, discoverLayout, resolveSrcDir, createTemplateError, createValidatingPartialsProxy, createValidatingContextProxy, propValue, slugify, wrapPartialsAsCallable, createNavigationHelpers, } from './utils/index.js';
+import { join, relative } from 'node:path';
+import { createFallbackLogger, getStatiVersion, isCollectionIndexPage, resolveSrcDir, createTemplateError, propValue, slugify, createNavigationHelpers, } from './utils/index.js';
 import { getCollections, resolveCollectionPath, createCollectionView, copyPaginationData, copyGeneratedData, } from './collections.js';
 import { isDevelopment, isProduction } from '../env.js';
 import { generateSEO, resolveGeneratedImagePlaceholders } from '../seo/index.js';
+import { TemplateIndex } from './template-index.js';
+import { RenderScope, failingTemplateOf, runInRenderScope, } from './template-render.js';
+import { createStatiEtaPlugin, installEtaPlugin } from './eta-plugin.js';
 /**
  * `stati.image()` when images are turned off: a plain `<img>`, attributes escaped.
  */
@@ -46,60 +46,6 @@ function createNavView(helpers, reads) {
     }
     return view;
 }
-/**
- * Discovers partials in the hierarchy for a given page path.
- * Scans all parent directories for folders starting with underscore.
- *
- * @param pagePath - The path to the page (relative to srcDir), with `/` or `\` separators
- * @param config - Stati configuration
- * @returns Object mapping partial names to their file paths
- */
-export async function discoverPartials(pagePath, config) {
-    const srcDir = resolveSrcDir(config);
-    const partials = {};
-    // Get the directory of the current page. Windows paths use backslashes, so convert them
-    // first, or the folders between the root and the page's own folder are skipped.
-    const pageDir = posix.dirname(pagePath.replace(/\\/g, '/'));
-    const pathSegments = pageDir === '.' ? [] : pageDir.split('/');
-    // Scan from root to current directory (least specific first)
-    // This allows more specific partials to override less specific ones
-    const dirsToScan = [];
-    if (pathSegments.length > 0) {
-        // Add root directory first, then parent directories, then current
-        dirsToScan.push(''); // Root directory first
-        // Add directories from root to current
-        for (let i = 1; i <= pathSegments.length; i++) {
-            dirsToScan.push(pathSegments.slice(0, i).join('/'));
-        }
-    }
-    else {
-        dirsToScan.push(''); // Root directory only
-    }
-    for (const dir of dirsToScan) {
-        const searchDir = dir ? join(srcDir, dir) : srcDir;
-        // Find all underscore folders in this directory level
-        const globPattern = join(searchDir, '_*/').replace(/\\/g, '/');
-        const underscoreFolders = await glob(globPattern, {
-            absolute: true,
-            onlyDirectories: true,
-        });
-        // Scan each underscore folder for .eta files
-        for (const folderPath of underscoreFolders) {
-            const etaFiles = await glob('**/*.eta', {
-                cwd: folderPath,
-                absolute: false,
-            });
-            for (const etaFile of etaFiles) {
-                const partialName = basename(etaFile, TEMPLATE_EXTENSION);
-                const fullPath = join(folderPath, etaFile);
-                // Get relative path from srcDir to the partial file
-                const relativePath = relative(srcDir, fullPath);
-                partials[partialName] = posix.normalize(relativePath);
-            }
-        }
-    }
-    return partials;
-}
 /**
  * Cached template engine for dev mode to avoid re-creating on each rebuild.
  *
@@ -118,6 +64,12 @@ let cachedTemplateEngine = null;
 export function clearTemplateEngineCache() {
     cachedTemplateEngine = null;
 }
+/**
+ * Creates the template engine: Eta with `stati` as its data variable and Stati's plugin,
+ * which replaces Eta's own `include()`, `layout()` and `block()` in templates.
+ *
+ * @throws {Error} When the installed Eta generates code the plugin does not recognize
+ */
 export function createTemplateEngine(config) {
     const templateDir = resolveSrcDir(config);
     // In dev mode, reuse a single cached engine across rebuilds to avoid
@@ -125,8 +77,8 @@ export function createTemplateEngine(config) {
     if (isDevelopment() && cachedTemplateEngine && cachedTemplateEngine.templateDir === templateDir) {
         return cachedTemplateEngine.eta;
     }
-    // Enable the template cache in dev too so partials/layouts compile once and are
-    // reused across rebuilds; template edits clear this cache via clearTemplateEngineCache().
+    // Enable the template cache in dev too so templates compile once and are reused
+    // across rebuilds; template edits clear this cache via clearTemplateEngineCache().
     const useCache = isDevelopment() || isProduction();
     const eta = new Eta({
         views: templateDir,
@@ -136,33 +88,40 @@ export function createTemplateEngine(config) {
         // Debug mode wraps runtime errors with the template path and line number,
         // which the dev error overlay uses to point at the failing line
         debug: isDevelopment(),
+        plugins: [createStatiEtaPlugin()],
     });
+    installEtaPlugin(eta);
     if (isDevelopment()) {
         cachedTemplateEngine = { templateDir, eta };
     }
     return eta;
 }
+/**
+ * Renders a page: its layout (chosen by front matter `layout:` or discovery), the parents the
+ * layout names with `stati.layout()`, and every template they include, plus the page's Open
+ * Graph template when it gets a generated image. Records every template and name lookup for
+ * the ISG cache.
+ */
 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 index = extras?.templateIndex ?? (await TemplateIndex.load(resolveSrcDir(config)));
+    const scope = new RenderScope({ page, eta, index, logger: log, development: isDevelopment() });
+    return runInRenderScope(scope, () => renderPageInScope(scope, body, config, navigation, allPages, assets, toc, extras?.images));
+}
+async function renderPageInScope(scope, body, config, navigation, allPages, assets, toc, pageImages) {
+    const { page, logger: log, index } = scope;
+    // The generated Open Graph image is known once the og template has rendered, before the
+    // layout. 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);
-    const partialPaths = await discoverPartials(relativePath, config);
-    // Count templates: partials + layout (if found)
-    const partialsCount = Object.keys(partialPaths).length;
     // What this render reads from shared data, so the cache can rebuild the page when it changes
     const reads = { collection: false, nav: false };
     // The page's collection: its own on index pages, the one it belongs to on other pages, or
     // the one its front matter names. Collections are computed once per page list.
     let collectionData;
-    const isIndexPage = allPages && isCollectionIndexPage(page, allPages);
+    const isIndexPage = allPages !== undefined && isCollectionIndexPage(page, allPages);
     if (allPages) {
         const collectionPath = resolveCollectionPath(page, allPages);
         const data = collectionPath !== undefined
@@ -172,11 +131,13 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             collectionData = createCollectionView(data, reads);
         }
     }
-    // Discover the appropriate layout using hierarchical layout.eta convention
-    // Pass isIndexPage flag to enable index.eta lookup for aggregation pages
-    const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isIndexPage);
-    // Calculate total templates loaded (partials + layout if present)
-    const templatesLoaded = partialsCount + (layoutPath ? 1 : 0);
+    // The layout: front matter `layout:` by the name lookup, otherwise layout.eta discovery
+    // (index.eta first on index pages)
+    const layout = index.resolvePageLayout(scope.pageFile, page.frontMatter.layout, isIndexPage);
+    for (const lookup of layout.lookups) {
+        scope.record(lookup);
+    }
+    reportFrontMatterLayout(scope, layout);
     // Create navigation helpers
     const navTree = navigation || [];
     const navHelpers = createNavigationHelpers(navTree, page);
@@ -204,24 +165,22 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             return currentNavNode;
         },
     });
-    // Create base context for partial rendering
-    const baseContext = {
+    // Values every template of the page shares. Each render adds props, body, include and layout.
+    // The site's helpers live under `helpers`; the root holds only Stati's own API.
+    const values = {
         site: config.site,
         page: pageContext,
         content: body,
-        nav: createNavView(navHelpers, reads), // Replace navigation with nav helpers
-        collection: collectionData, // Add collection data
-        // Set on paginated listings and on pages generated from [param].md templates. Placed before
-        // the filters, like slugify, so that an existing filter with the same name keeps working.
+        nav: createNavView(navHelpers, reads),
+        collection: collectionData,
+        // Set on paginated listings and on pages generated from [param].md templates
         pagination: page.pagination ? copyPaginationData(page.pagination) : undefined,
         generated: page.generated ? copyGeneratedData(page.generated) : undefined,
-        slugify,
-        // Add custom filters to context
-        ...(config.eta?.filters || {}),
+        // A copy, so a template that replaces a helper does not change it for later pages
+        helpers: { ...config.helpers },
         generator: {
             version: getStatiVersion(),
         },
-        // Stati utilities object with helper functions
         generateSEO: (tags) => generateSEO({
             page,
             config,
@@ -230,141 +189,101 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
             deferGeneratedImage: ogState.pending,
         }, tags),
         propValue,
+        slugify,
         // 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
-    const renderedPartials = {};
-    const maxPasses = 3; // Prevent infinite loops
-    for (let pass = 0; pass < maxPasses; pass++) {
-        // Each pass renders all partials to ensure they have access to all previously rendered ones
-        // TODO: Optimize by tracking which partials changed or have dependencies
-        const partialsToRender = { ...partialPaths };
-        if (Object.keys(partialsToRender).length === 0) {
-            break;
-        }
-        let progressMade = false;
-        const passRenderedPartials = {};
-        for (const [partialName, partialPath] of Object.entries(partialsToRender)) {
-            try {
-                // Create context with all previously rendered partials available
-                const combinedPartials = { ...renderedPartials, ...passRenderedPartials };
-                // Wrap partials as callable before passing to validation proxy
-                const callablePartials = wrapPartialsAsCallable(eta, combinedPartials, partialPaths, baseContext);
-                const partialContext = createValidatingContextProxy({
-                    ...baseContext,
-                    partials: createValidatingPartialsProxy(callablePartials), // Include both previous and current pass partials with validation
-                });
-                const renderedContent = await eta.renderAsync(partialPath, partialContext);
-                passRenderedPartials[partialName] = renderedContent;
-                progressMade = true;
-            }
-            catch (error) {
-                // If this is the last pass, log the error and create placeholder
-                if (pass === maxPasses - 1) {
-                    log.warning(`Failed to render partial ${partialName} at ${partialPath}: ${error instanceof Error ? error.message : String(error)}`);
-                    // In development mode, throw enhanced template error for partials too
-                    if (isDevelopment()) {
-                        const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), partialPath);
-                        throw templateError;
-                    }
-                    passRenderedPartials[partialName] = `<!-- Error rendering partial: ${partialName} -->`;
-                    progressMade = true;
-                }
-                // Otherwise, use existing content if available, or skip for retry
-                else if (renderedPartials[partialName]) {
-                    passRenderedPartials[partialName] = renderedPartials[partialName];
-                }
-                // For failed partials on non-last pass, still count as progress to allow retries
-                else {
-                    progressMade = true;
-                }
-            }
-        }
-        // Update the rendered partials with this pass's results
-        Object.assign(renderedPartials, passRenderedPartials);
-        // If no progress was made, break to avoid infinite loop
-        if (!progressMade) {
-            break;
-        }
-        // If this is pass 0, always do at least one more pass to allow interdependencies
-        if (pass === 0) {
-            continue;
-        }
-        // For subsequent passes, only continue if we're not at max passes yet
-        if (pass >= maxPasses - 1) {
-            break;
-        }
-    }
-    // Render the Open Graph template with the layout's context, minus the page body, so the
+    // Render the Open Graph template with the layout's values, minus the page body, so the
     // generated image is known before the layout renders its SEO tags
     if (pageImages && ogState.pending) {
         // Copy the page's property descriptors so that navNode stays a getter: spreading would
         // read it and count every page with a card as reading the navigation
-        const ogPage = Object.defineProperties({}, Object.getOwnPropertyDescriptors(baseContext.page));
+        const ogPage = Object.defineProperties({}, Object.getOwnPropertyDescriptors(pageContext));
         ogPage.content = '';
-        const ogBaseContext = {
-            ...baseContext,
-            content: '',
-            page: ogPage,
-            og: pageImages.ogSize(),
+        const ogBase = {
+            id: 'og',
+            values: { ...values, content: '', page: ogPage, og: pageImages.ogSize() },
         };
-        const ogContext = createValidatingContextProxy({
-            ...ogBaseContext,
-            partials: createValidatingPartialsProxy(wrapPartialsAsCallable(eta, renderedPartials, partialPaths, ogBaseContext)),
-        });
-        ogState.image = (await pageImages.renderOg(ogContext, eta)) ?? undefined;
+        ogState.image = (await pageImages.renderOg(createOgRenderer(scope, ogBase))) ?? undefined;
         ogState.pending = false;
-        baseContext.ogImage = ogState.image;
+        values.ogImage = ogState.image;
     }
-    // Wrap final rendered partials as callable before passing to layout context
-    const callablePartials = wrapPartialsAsCallable(eta, renderedPartials, partialPaths, baseContext);
-    const context = createValidatingContextProxy({
-        ...baseContext,
-        partials: createValidatingPartialsProxy(callablePartials), // Add rendered partials with validation
+    const result = (html) => ({
+        html,
+        templatesLoaded: scope.templates.size,
+        templateRenders: scope.renders,
+        includeCacheHits: scope.includeCacheHits,
+        ogImage: ogState.image,
+        reads,
+        templates: scope.templateFiles(layout.file),
+        templateLookups: [...scope.lookups.values()],
     });
+    if (!layout.file) {
+        log.warning('No layout template found, using fallback');
+        return result(createFallbackHtml(page, body));
+    }
     try {
-        if (!layoutPath) {
-            log.warning('No layout template found, using fallback');
-            return {
-                html: createFallbackHtml(page, body),
-                templatesLoaded,
-                ogImage: ogState.image,
-                reads,
-            };
-        }
-        const html = await eta.renderAsync(layoutPath, context);
-        return {
-            html: resolveGeneratedImagePlaceholders(html, ogState.image),
-            templatesLoaded,
-            ogImage: ogState.image,
-            reads,
-        };
+        const html = await scope.renderAsync({ id: 'page', values }, { file: layout.file });
+        return result(resolveGeneratedImagePlaceholders(html, ogState.image));
     }
     catch (error) {
-        log.error(`Error rendering layout ${layoutPath || 'unknown'}: ${error instanceof Error ? error.message : String(error)}`);
-        // In development mode, throw enhanced template error for better debugging
+        const failure = error instanceof Error ? error : new Error(String(error));
+        const failed = failingTemplateOf(failure) ?? layout.file;
+        // In development, throw the error for the overlay; it points at the innermost template
         if (isDevelopment()) {
-            const templateError = createTemplateError(error instanceof Error ? error : new Error(String(error)), layoutPath || undefined);
+            const failedPath = join(index.srcDir, failed);
+            const templateError = createTemplateError(failure, failedPath);
+            const where = scope.displayPath(templateError.filePath ?? failedPath);
+            log.error(`Error rendering ${where} for ${page.url}: ${templateError.message}`);
             throw templateError;
         }
-        return {
-            html: createFallbackHtml(page, body),
-            templatesLoaded,
-            ogImage: ogState.image,
-            reads,
-        };
+        log.error(`Error rendering ${scope.display(failed)} for ${page.url}: ${failure.message}`);
+        return result(createFallbackHtml(page, body));
     }
 }
+/**
+ * Warns about a front matter `layout:` value that names no template, with the templates it
+ * could have meant. Layout discovery picks the page's layout instead.
+ */
+function reportFrontMatterLayout(scope, layout) {
+    const unresolved = layout.unresolvedFrontMatter;
+    if (!unresolved) {
+        return;
+    }
+    const page = scope.displayPath(scope.page.sourcePath);
+    const used = layout.file === null ? 'the fallback HTML' : scope.display(layout.file);
+    const didYouMean = unresolved.suggestions.length > 0
+        ? ` Did you mean ${unresolved.suggestions.map((name) => `"${name}"`).join(', ')}?`
+        : '';
+    scope.logger.warning(`${page}: front matter layout ${JSON.stringify(unresolved.value)} ${unresolved.problem}; using ${used}.${didYouMean}`);
+}
+/**
+ * Lets the image pipeline find the page's Open Graph template through the template index,
+ * recording the lookup, and render it through the render scope, so it can use
+ * `stati.include()` and `stati.layout()` like any template.
+ */
+function createOgRenderer(scope, base) {
+    return {
+        find(templateName) {
+            const name = templateName.replace(/\.eta$/, '');
+            const file = scope.index.lookup(name, scope.pageFolder);
+            scope.record({ name, from: scope.pageFolder, file });
+            return file === null ? null : join(scope.index.srcDir, file);
+        },
+        render(template) {
+            return 'path' in template
+                ? scope.renderAsync(base, {
+                    file: relative(scope.index.srcDir, template.path).replace(/\\/g, '/'),
+                })
+                : scope.renderAsync(base, { source: template.source });
+        },
+    };
+}
 function createFallbackHtml(page, body) {
     const title = page.frontMatter.title || 'Untitled';
     const description = page.frontMatter.description || '';

package/dist/core/utils/context-validation.utils.d.ts

@@ -6,14 +6,18 @@ export declare function isPassthroughProperty(prop: string | symbol): boolean;
  * Thrown in development when a template reads a property that does not exist
  * on the template context.
  *
- * The suggestions are encoded in the message because Eta's debug mode rethrows
- * runtime errors as a new error that only keeps the original message and name.
+ * The suggestions are encoded in the message, which Eta's debug mode copies into
+ * the error it rethrows for each template the error passes through.
  * Use {@link parseUnknownPropertyMessage} to read them back.
  */
 export declare class UnknownTemplatePropertyError extends Error {
     readonly propertyPath: string;
     readonly suggestions: string[];
-    constructor(propertyPath: string, suggestions: string[], availableKeys: string[]);
+    /**
+     * @param hint - Explanation shown instead of the suggestions, for a property that only some
+     *   templates have
+     */
+    constructor(propertyPath: string, suggestions: string[], availableKeys: string[], hint?: string);
 }
 /**
  * Reads an {@link UnknownTemplatePropertyError} message back into a short message
@@ -35,9 +39,9 @@ export declare function parseUnknownPropertyMessage(message: string): {
  * instead of silently rendering `undefined`. The error reaches the dev server's
  * error overlay.
  *
- * Validates the top-level `stati.*` keys (including custom filters, which are
- * spread onto the context) and one level down for `site`, `nav`, `collection`,
- * and `generator`. Frontmatter under `stati.page` is not validated.
+ * Validates the top-level `stati.*` keys and one level down for `site`, `nav`,
+ * `collection`, `generator` and `helpers`, so a misspelt helper is caught too.
+ * Frontmatter under `stati.page` is not validated.
  *
  * Only active in development; other environments get the context back unchanged.
  */

package/dist/core/utils/context-validation.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-validation.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/context-validation.utils.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAEpE;AAmCD;;;;;;;GAOG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,WAAW,EAAE,MAAM,EAAE,CAAC;gBAE1B,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE;CAMjF;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAoBxD;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAqD5E"}
+{"version":3,"file":"context-validation.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/context-validation.utils.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAEpE;AA2CD;;;;;;;GAOG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtC;;;OAGG;gBACS,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM;CAMhG;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAsBxD;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CA4D5E"}

package/dist/core/utils/context-validation.utils.js

@@ -34,41 +34,55 @@ const SITE_CONFIG_KEYS = {
 /**
  * Context properties whose own keys form a closed set and are validated one level
  * down, with keys that may be legitimately absent at runtime.
- * `page` is left out because frontmatter keys differ from page to page, and
- * `partials` already has its own validating proxy.
+ * `page` is left out because frontmatter keys differ from page to page.
  */
 const VALIDATED_NESTED_PROPERTIES = {
     site: Object.keys(SITE_CONFIG_KEYS),
     nav: [],
     collection: [],
     generator: [],
+    helpers: [],
 };
 /**
  * Context properties searched for an exact match when a key is missing from the
- * root, so that `stati.title` can suggest `stati.page.title` and `stati.header`
- * can suggest `stati.partials.header`.
+ * root, so that `stati.title` can suggest `stati.page.title` and `stati.formatDate`
+ * can suggest `stati.helpers.formatDate`.
  */
-const CROSS_LEVEL_PROPERTIES = ['page', 'site', 'nav', 'partials'];
+const CROSS_LEVEL_PROPERTIES = ['page', 'site', 'nav', 'helpers'];
+/**
+ * Explanations for root properties that exist only in some templates, shown instead of
+ * spelling suggestions when a template reads one where it is absent.
+ */
+const ABSENT_PROPERTY_HINTS = {
+    body: "stati.body is set only in templates rendered by stati.layout() or stati.include(); the page's Markdown is stati.content",
+};
 /**
  * Thrown in development when a template reads a property that does not exist
  * on the template context.
  *
- * The suggestions are encoded in the message because Eta's debug mode rethrows
- * runtime errors as a new error that only keeps the original message and name.
+ * The suggestions are encoded in the message, which Eta's debug mode copies into
+ * the error it rethrows for each template the error passes through.
  * Use {@link parseUnknownPropertyMessage} to read them back.
  */
 export class UnknownTemplatePropertyError extends Error {
     propertyPath;
     suggestions;
-    constructor(propertyPath, suggestions, availableKeys) {
-        super(formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys));
+    /**
+     * @param hint - Explanation shown instead of the suggestions, for a property that only some
+     *   templates have
+     */
+    constructor(propertyPath, suggestions, availableKeys, hint) {
+        super(formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys, hint));
         this.name = 'UnknownTemplatePropertyError';
         this.propertyPath = propertyPath;
-        this.suggestions = suggestions;
+        this.suggestions = hint ? [hint] : suggestions;
     }
 }
-function formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys) {
+function formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys, hint) {
     const base = `Unknown property "${propertyPath}".`;
+    if (hint) {
+        return `${base} ${hint}.`;
+    }
     if (suggestions.length > 0) {
         const quoted = suggestions.map((s) => `"${s}"`);
         const list = quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(', ')} or ${quoted.at(-1)}`;
@@ -87,11 +101,11 @@ function formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys)
  * ```
  */
 export function parseUnknownPropertyMessage(message) {
-    const match = message.match(/^Unknown property "([^"]+)"\.(?: Did you mean (.+)\?| Available properties: (.*)\.)?$/);
+    const match = message.match(/^Unknown property "([^"]+)"\.(?: Did you mean (.+)\?| Available properties: (.*)\.| (.+)\.)?$/);
     if (!match) {
         return undefined;
     }
-    const [, propertyPath, didYouMean, available] = match;
+    const [, propertyPath, didYouMean, available, hint] = match;
     const suggestions = [];
     if (didYouMean) {
         for (const [, name] of didYouMean.matchAll(/"([^"]+)"/g)) {
@@ -102,6 +116,9 @@ export function parseUnknownPropertyMessage(message) {
         const parentPath = propertyPath.slice(0, propertyPath.lastIndexOf('.'));
         suggestions.push(`Available properties on ${parentPath}: ${available || '(none)'}`);
     }
+    else if (hint) {
+        suggestions.push(hint);
+    }
     return { message: `Unknown property "${propertyPath}"`, suggestions };
 }
 function listKeys(target, extraKeys) {
@@ -126,9 +143,9 @@ function createValidatingObjectProxy(target, path, extraKeys) {
  * instead of silently rendering `undefined`. The error reaches the dev server's
  * error overlay.
  *
- * Validates the top-level `stati.*` keys (including custom filters, which are
- * spread onto the context) and one level down for `site`, `nav`, `collection`,
- * and `generator`. Frontmatter under `stati.page` is not validated.
+ * Validates the top-level `stati.*` keys and one level down for `site`, `nav`,
+ * `collection`, `generator` and `helpers`, so a misspelt helper is caught too.
+ * Frontmatter under `stati.page` is not validated.
  *
  * Only active in development; other environments get the context back unchanged.
  */
@@ -157,6 +174,12 @@ export function createValidatingContextProxy(context) {
             }
             const name = String(prop);
             const availableKeys = listKeys(obj, []);
+            const hint = Object.hasOwn(ABSENT_PROPERTY_HINTS, name)
+                ? ABSENT_PROPERTY_HINTS[name]
+                : undefined;
+            if (hint) {
+                throw new UnknownTemplatePropertyError(`stati.${name}`, [], availableKeys, hint);
+            }
             // An exact match one level down (stati.title -> stati.page.title) is a
             // stronger signal than a spelling match, so it goes first
             const suggestions = [];

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

@@ -12,7 +12,7 @@ export declare const PUBLISHED_DATE_FIELDS: readonly ["publishedAt", "published"
  *
  * Checks {@link PUBLISHED_DATE_FIELDS} in order and returns the first valid value.
  * Accepts strings (quoted YAML dates) and `Date` objects (unquoted YAML dates,
- * which gray-matter parses into `Date`). Missing, `null` and empty values are skipped;
+ * which YAML parses into `Date`). Missing, `null` and empty values are skipped;
  * other invalid values are reported through `onInvalid` and skipped, so a bad
  * `publishedAt` does not hide a valid `date`.
  *

package/dist/core/utils/date.utils.js

@@ -12,7 +12,7 @@ export const PUBLISHED_DATE_FIELDS = ['publishedAt', 'published', 'date', 'creat
  *
  * Checks {@link PUBLISHED_DATE_FIELDS} in order and returns the first valid value.
  * Accepts strings (quoted YAML dates) and `Date` objects (unquoted YAML dates,
- * which gray-matter parses into `Date`). Missing, `null` and empty values are skipped;
+ * which YAML parses into `Date`). Missing, `null` and empty values are skipped;
  * other invalid values are reported through `onInvalid` and skipped, so a bad
  * `publishedAt` does not hide a valid `date`.
  *

package/dist/core/utils/dev-css-watcher.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-css-watcher.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/dev-css-watcher.utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa9E;AA0BD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAgC3B"}
+{"version":3,"file":"dev-css-watcher.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/dev-css-watcher.utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAc9E;AA0BD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAgC3B"}

package/dist/core/utils/dev-css-watcher.utils.js

@@ -1,5 +1,5 @@
 import chokidar from 'chokidar';
-import fg from 'fast-glob';
+import { glob } from 'tinyglobby';
 import { pathExists } from './fs.utils.js';
 /**
  * Returns concrete CSS files currently present in outDir.
@@ -11,11 +11,12 @@ export async function discoverOutputCssFiles(outDir) {
     if (!(await pathExists(outDir))) {
         return [];
     }
-    const cssFiles = await fg('**/*.css', {
+    const cssFiles = await glob('**/*.css', {
         cwd: outDir,
         absolute: true,
         onlyFiles: true,
         dot: false,
+        expandDirectories: false,
     });
     return cssFiles;
 }

package/dist/core/utils/error-overlay.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-overlay.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/error-overlay.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AA0sBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAiJnF;AAsFD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAkCd"}
+{"version":3,"file":"error-overlay.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/error-overlay.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AA6pBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAiJnF;AAsFD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAkCd"}