@stati/core 1.26.1 → 1.27.0

package/README.md

@@ -63,20 +63,24 @@ This is my first page. It's just Markdown.
 **3. Build or develop:**
 
 ```typescript
-import { build, createDevServer } from '@stati/core';
+import { build, createDevServer, setEnv } from '@stati/core';
 
 // Development with live reload
 const server = await createDevServer({
   port: 3000,
   open: true,
 });
+await server.start();
 
-// Or build for production
+// Or build for production (build() alone runs a development build)
+setEnv('production');
 const stats = await build({
   clean: true,
 });
 ```
 
+Most projects use the `stati` command from [`@stati/cli`](https://www.npmjs.com/package/@stati/cli) instead (`stati dev`, `stati build`), which sets the environment for you.
+
 That's it! Your site is ready.
 
 ---
@@ -111,7 +115,7 @@ my-site/
 ├── site/           # Your content (Markdown + templates)
 │   ├── index.md    # Homepage → /
 │   └── blog/
-│       └── hello.md # Blog post → /blog/hello/
+│       └── hello.md # Blog post → /blog/hello
 ├── public/         # Static assets (CSS, images)
 └── stati.config.js # Configuration (optional)
 ```
@@ -162,7 +166,7 @@ Customize layouts with [Eta templates](https://eta.js.org):
 
 Only rebuild what changed:
 
-- Smart caching based on file modification times
+- Smart caching based on hashes of each page's content and templates
 - TTL-based refresh for dynamic content
 - Tag-based invalidation for related content
 
@@ -175,7 +179,7 @@ await invalidate('tag:blog');
 // Invalidate by path
 await invalidate('path:/posts');
 
-// Invalidate old content (3+ months)
+// Invalidate pages rendered within the last 3 months
 await invalidate('age:3months');
 ```
 
@@ -183,10 +187,10 @@ await invalidate('age:3months');
 
 SEO optimization works automatically with zero configuration:
 
-- Meta tags (title, description, keywords)
+- Meta tags (title, description, keywords from front matter)
 - Open Graph for social sharing
 - Twitter Cards
-- Structured data (JSON-LD)
+- Structured data (JSON-LD) from `seo.structuredData` in front matter
 
 Enable sitemap and robots.txt with one config option.
 
@@ -217,7 +221,7 @@ This is all you need! Stati automatically enables:
 
 ### Extended Configuration (Common Options)
 
-Below are commonly used configuration options. This is **not a complete list** - see the [full configuration documentation](https://stati.build/configuration/) for all available options.
+Below are commonly used configuration options. This is **not a complete list** - see the [full configuration documentation](https://stati.build/configuration/file/) for all available options.
 
 ```javascript
 import { defineConfig } from '@stati/core';
@@ -264,8 +268,8 @@ export default defineConfig({
     ttlSeconds: 86400,        // Cache TTL: 24 hours (default: 21600 / 6 hours)
     maxAgeCapDays: 30,        // Max age for aging rules (default: 365)
     aging: [
-      { untilDays: 7, ttlSeconds: 86400 },   // 1 day cache for week-old content
-      { untilDays: 30, ttlSeconds: 604800 }, // 1 week cache for month-old content
+      { untilDays: 7, ttlSeconds: 86400 },   // up to 7 days old: 1 day
+      { untilDays: 30, ttlSeconds: 604800 }, // up to 30 days old (and older): 1 week
     ],
   },
 
@@ -342,9 +346,9 @@ export default defineConfig({
 
 ### Build Functions
 
-#### `build(options?: BuildOptions): Promise<BuildStats>`
+#### `build(options?: BuildOptions): Promise<BuildResult>`
 
-Build your static site for production.
+Build your static site. `build()` uses Stati's current environment, which is `development` unless you call `setEnv('production')` first (the `stati build` command does). Sitemap, robots.txt and RSS are only generated in production.
 
 **Options:**
 
@@ -353,15 +357,18 @@ Build your static site for production.
   force?: boolean;        // Force rebuild of all pages (ignores cache)
   clean?: boolean;        // Clean output directory before build
   includeDrafts?: boolean; // Include draft pages in build
-  configPath?: string;    // Custom config file path
+  configPath?: string;    // Config file; only its directory is used to find stati.config.*
+  metrics?: MetricsOptions; // Collect build metrics
+  logger?: Logger;        // Custom logger for build output
 }
 ```
 
 **Example:**
 
 ```typescript
-import { build } from '@stati/core';
+import { build, setEnv } from '@stati/core';
 
+setEnv('production');
 const stats = await build({
   clean: true,
   force: false,
@@ -371,7 +378,7 @@ const stats = await build({
 console.log(`Built ${stats.totalPages} pages in ${stats.buildTimeMs}ms`);
 ```
 
-**Returns:** Build statistics including pages built, duration, and cache hits.
+**Returns:** Build statistics (`totalPages`, `assetsCount`, `buildTimeMs`, `outputSizeBytes`, `cacheHits`, `cacheMisses`), plus `buildMetrics` when metrics are enabled.
 
 ---
 
@@ -386,10 +393,12 @@ Start a development server with live reload.
   port?: number;          // Port number (default: 3000)
   host?: string;          // Host address (default: 'localhost')
   open?: boolean;         // Auto-open browser (default: false)
-  configPath?: string;    // Custom config file path
+  logger?: Logger;        // Custom logger
 }
 ```
 
+The config is always loaded from the current working directory.
+
 **Example:**
 
 ```typescript
@@ -399,11 +408,12 @@ const server = await createDevServer({
   port: 3000,
   open: true,
 });
+await server.start();
 
-console.log(`Dev server running at http://localhost:3000`);
+console.log(`Dev server running at ${server.url}`);
 ```
 
-**Returns:** Server instance with methods to stop and restart.
+**Returns:** A server object with `start()`, `stop()` and `url`. Nothing listens until you call `start()`.
 
 ---
 
@@ -418,16 +428,19 @@ Start a production preview server to test your built site locally.
   port?: number;          // Port number (default: 4000)
   host?: string;          // Host address (default: 'localhost')
   open?: boolean;         // Auto-open browser (default: false)
-  configPath?: string;    // Custom config file path
+  logger?: Logger;        // Custom logger
 }
 ```
 
+The config (used to find the output directory) is always loaded from the current working directory.
+
 **Example:**
 
 ```typescript
-import { createPreviewServer } from '@stati/core';
+import { build, createPreviewServer, setEnv } from '@stati/core';
 
 // First build your site
+setEnv('production');
 await build({ clean: true });
 
 // Then preview it
@@ -435,11 +448,12 @@ const server = await createPreviewServer({
   port: 4000,
   open: true,
 });
+await server.start();
 
-console.log(`Preview server running at http://localhost:4000`);
+console.log(`Preview server running at ${server.url}`);
 ```
 
-**Returns:** Server instance with methods to stop.
+**Returns:** A server object with `start()`, `stop()` and `url`.
 
 **Note:** Unlike `createDevServer`, the preview server serves the static files from your `dist/` directory without live reload or rebuilding. This is useful for testing your production build locally before deployment.
 
@@ -452,9 +466,9 @@ Invalidate cache by tags, paths, patterns, or age.
 **Query Syntax:**
 
 - `tag:blog` - Invalidate pages with specific tag
-- `path:/posts` - Invalidate pages under path
-- `glob:/blog/**` - Invalidate by glob pattern
-- `age:3months` - Invalidate content younger than 3 months
+- `path:/posts` - Invalidate cache entries whose key (output path, such as `/posts/hello.html`) starts with this prefix
+- `glob:/blog/**` - Invalidate by glob pattern matched against the whole key
+- `age:3months` - Invalidate pages rendered within the last 3 months
 - No query - Clear entire cache
 
 **Examples:**
@@ -468,7 +482,7 @@ await invalidate('tag:news');
 // Invalidate by path prefix
 await invalidate('path:/blog/2024/');
 
-// Invalidate old content
+// Invalidate pages rendered within the last 6 months
 await invalidate('age:6months');
 
 // Multiple criteria (OR logic)
@@ -533,6 +547,7 @@ import type {
 
   // Build
   BuildOptions,
+  BuildResult,
   BuildContext,
   BuildStats,
 
@@ -551,7 +566,10 @@ import type {
   // Cache
   InvalidationResult,
   AgingRule,
-} from '@stati/core/types';
+} from '@stati/core';
+
+// Template and cache types are only exported from the types entry point
+import type { TemplateContext, CacheManifest } from '@stati/core/types';
 ```
 
 > **Need more types?** This is a curated list of commonly used types. For the complete type reference including all SEO, sitemap, and configuration types, see the [API Types Documentation](https://stati.build/api/types/).
@@ -564,9 +582,9 @@ import type {
 
 Stati supports rich Markdown features out of the box:
 
-- **Front-matter** - YAML, TOML, or JSON metadata
+- **Front-matter** - YAML (default) or JSON (`---json`) metadata
 - **Plugins** - Full markdown-it ecosystem compatibility
-- **Syntax highlighting** - Code blocks with language support
+- **Syntax highlighting** - Code blocks get `language-*` classes; add a plugin such as `markdown-it-prism` to highlight them
 - **Custom rendering** - Configure parser behavior
 - **Draft mode** - Mark pages as `draft: true`
 
@@ -592,7 +610,7 @@ Powered by [Eta](https://eta.js.org) for fast, flexible templates:
 - **Partials** - Reusable components
 - **Custom filters** - Transform data in templates
 - **Type-safe helpers** - Access page data with autocomplete
-- **Hot reload** - See template changes instantly
+- **Live reload** - The browser reloads when a template changes
 
 **Template structure:**
 
@@ -604,11 +622,11 @@ Powered by [Eta](https://eta.js.org) for fast, flexible templates:
     <title><%= stati.page.title %> - <%= stati.site.title %></title>
   </head>
   <body>
-    <%~ include('_partials/header') %>
+    <%~ stati.partials.header %>
     <main>
       <%~ stati.content %>
     </main>
-    <%~ include('_partials/footer') %>
+    <%~ stati.partials.footer %>
   </body>
 </html>
 ```
@@ -617,7 +635,7 @@ Powered by [Eta](https://eta.js.org) for fast, flexible templates:
 
 Automatic navigation hierarchy based on your file structure:
 
-- **Auto-generated tree** - Reflects directory structure
+- **Auto-generated tree** - Built from your folders (each folder of pages is a top-level node)
 - **Breadcrumbs** - Parent-child relationships
 - **Custom ordering** - Use `order` in front-matter
 - **Index pages** - Special handling for `index.md`
@@ -654,7 +672,7 @@ Built for productivity:
 
 Smart caching for lightning-fast builds:
 
-- **Modification tracking** - Rebuild only changed files
+- **Content hashing** - Rebuild pages whose content or templates changed
 - **Incremental builds** - Skip unchanged pages
 - **Tag invalidation** - Update related content together
 - **TTL-based refresh** - Control cache lifetime
@@ -667,9 +685,9 @@ export default defineConfig({
   isg: {
     ttlSeconds: 21600,     // 6 hours default
     aging: [
-      { untilDays: 7, ttlSeconds: 3600 },    // Recent: 1 hour
-      { untilDays: 30, ttlSeconds: 86400 },  // Month: 1 day
-      // Older content uses default TTL
+      { untilDays: 7, ttlSeconds: 3600 },    // up to 7 days old: 1 hour
+      { untilDays: 30, ttlSeconds: 86400 },  // up to 30 days old: 1 day
+      // Older content also uses the last rule (1 day)
     ],
   },
 });
@@ -708,8 +726,8 @@ export default defineConfig({
   },
   isg: {
     aging: [
-      { untilDays: 30, ttlSeconds: 3600 },   // Fresh posts: 1 hour
-      { untilDays: 365, ttlSeconds: 86400 }, // Year-old: 1 day
+      { untilDays: 30, ttlSeconds: 3600 },   // up to 30 days old: 1 hour
+      { untilDays: 365, ttlSeconds: 86400 }, // up to a year old (and older): 1 day
     ],
   },
 });
@@ -738,8 +756,8 @@ export default defineConfig({
 
 ## Requirements
 
-- **Node.js** >=22
-- **npm** 11.5.1 or higher (or equivalent package manager)
+- **Node.js** ^22.12.0 || >=24
+- **A package manager**: npm, pnpm, yarn or bun
 
 ---
 

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;AAkB3B;;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,CAwB7D;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,CAuMvB"}
+{"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"}

package/dist/core/templates.js

@@ -3,7 +3,7 @@ import { join, dirname, 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, getCollectionPathForPage, resolveSrcDir, createTemplateError, createValidatingPartialsProxy, propValue, wrapPartialsAsCallable, createNavigationHelpers, } from './utils/index.js';
+import { getStatiVersion, isCollectionIndexPage, discoverLayout, getCollectionPathForPage, resolveSrcDir, createTemplateError, createValidatingPartialsProxy, createValidatingContextProxy, propValue, wrapPartialsAsCallable, createNavigationHelpers, } from './utils/index.js';
 import { isDevelopment, isProduction } from '../env.js';
 import { generateSEO } from '../seo/index.js';
 /**
@@ -206,6 +206,9 @@ export function createTemplateEngine(config) {
         cache: useCache,
         cacheFilepaths: useCache,
         varName: 'stati',
+        // 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(),
     });
     if (isDevelopment()) {
         cachedTemplateEngine = { templateDir, eta };
@@ -274,6 +277,9 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
         generateSEO: (tags) => generateSEO({ page, config, site: config.site }, tags),
         propValue,
         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,
     };
     // Render partials and store their content
     // Use multiple passes to allow partials to reference other partials
@@ -294,10 +300,10 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
                 const combinedPartials = { ...renderedPartials, ...passRenderedPartials };
                 // Wrap partials as callable before passing to validation proxy
                 const callablePartials = wrapPartialsAsCallable(eta, combinedPartials, partialPaths, baseContext);
-                const partialContext = {
+                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;
@@ -341,10 +347,10 @@ export async function renderPage(page, body, config, eta, navigation, allPages,
     }
     // Wrap final rendered partials as callable before passing to layout context
     const callablePartials = wrapPartialsAsCallable(eta, renderedPartials, partialPaths, baseContext);
-    const context = {
+    const context = createValidatingContextProxy({
         ...baseContext,
         partials: createValidatingPartialsProxy(callablePartials), // Add rendered partials with validation
-    };
+    });
     try {
         if (!layoutPath) {
             log.warning('No layout template found, using fallback');

package/dist/core/utils/callable-partials.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callable-partials.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/callable-partials.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE1B;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAC1C,QAAQ,IAAI,MAAM,CAAC;IACnB,OAAO,IAAI,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,EACR,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,eAAe,EAAE,MAAM,GACtB,eAAe,CAqDjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CA8BjC"}
+{"version":3,"file":"callable-partials.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/callable-partials.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAK1B;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAC1C,QAAQ,IAAI,MAAM,CAAC;IACnB,OAAO,IAAI,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,EACR,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,eAAe,EAAE,MAAM,GACtB,eAAe,CA0DjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CA+BjC"}

package/dist/core/utils/callable-partials.utils.js

@@ -1,3 +1,6 @@
+import { isDevelopment } from '../../env.js';
+import { createValidatingContextProxy } from './context-validation.utils.js';
+import { createValidatingPartialsProxy } from './partial-validation.utils.js';
 /**
  * Creates a callable partial that can be used both as a value and as a function.
  * This enables both syntaxes:
@@ -34,16 +37,21 @@ export function makeCallablePartial(eta, partialPath, baseContext, renderedConte
         }
         // Props provided - re-render with merged context
         try {
-            const mergedContext = {
+            const mergedContext = createValidatingContextProxy({
                 ...baseContext,
                 props, // Make props available as stati.props
-            };
+            });
             // Render the partial with the merged context using renderAsync
             // This is a synchronous call despite the name when used with already-loaded templates
             const result = eta.render(partialPath, mergedContext);
             return result || '';
         }
         catch (error) {
+            // In development, let the error reach the calling template so it ends up
+            // in the error overlay instead of a hidden HTML comment
+            if (isDevelopment()) {
+                throw error;
+            }
             console.error(`Error rendering callable partial ${partialPath} with props:`, error);
             return `<!-- Error rendering partial with props: ${error instanceof Error ? error.message : String(error)} -->`;
         }
@@ -97,12 +105,13 @@ export function makeCallablePartial(eta, partialPath, baseContext, renderedConte
 export function wrapPartialsAsCallable(eta, partials, partialPaths, baseContext) {
     const callablePartials = {};
     // Create a context that will have partials updated to the callable versions
-    // This enables nested callable partial calls
+    // This enables nested callable partial calls. The getter runs when a partial is
+    // rendered with props, after all callables exist, and wraps them in the same
+    // validating proxy that layouts and pre-rendered partials get.
     const contextWithCallablePartials = {
         ...baseContext,
-        // The partials property will be updated after all callables are created
         get partials() {
-            return callablePartials;
+            return createValidatingPartialsProxy(callablePartials);
         },
     };
     for (const [name, renderedContent] of Object.entries(partials)) {

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

@@ -0,0 +1,45 @@
+/**
+ * Checks whether a property access should bypass validation.
+ */
+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.
+ * 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[]);
+}
+/**
+ * Reads an {@link UnknownTemplatePropertyError} message back into a short message
+ * and a list of overlay suggestions. Returns `undefined` for any other message.
+ *
+ * @example
+ * ```typescript
+ * parseUnknownPropertyMessage('Unknown property "stati.paeg". Did you mean "stati.page"?');
+ * // { message: 'Unknown property "stati.paeg"', suggestions: ['Did you mean "stati.page"?'] }
+ * ```
+ */
+export declare function parseUnknownPropertyMessage(message: string): {
+    message: string;
+    suggestions: string[];
+} | undefined;
+/**
+ * Wraps the template context so that reading a property that does not exist
+ * throws an {@link UnknownTemplatePropertyError} with "did you mean" suggestions
+ * 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.
+ *
+ * Only active in development; other environments get the context back unchanged.
+ */
+export declare function createValidatingContextProxy<T extends object>(context: T): T;
+//# sourceMappingURL=context-validation.utils.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,175 @@
+import { isDevelopment } from '../../env.js';
+import { findSimilarNames } from './similarity.utils.js';
+/**
+ * Properties that must resolve normally even when they are not defined on the
+ * object, because the runtime, serializers, or test tooling probe for them.
+ */
+const PASSTHROUGH_PROPERTIES = new Set([
+    'length',
+    'constructor',
+    'then', // Promise detection
+    '$$typeof', // React inspection
+    'nodeType', // DOM node detection
+    'asymmetricMatch', // Jest/Vitest matcher
+    'toJSON', // JSON serialization
+]);
+/**
+ * Checks whether a property access should bypass validation.
+ */
+export function isPassthroughProperty(prop) {
+    return typeof prop === 'symbol' || prop in Object.prototype || PASSTHROUGH_PROPERTIES.has(prop);
+}
+/**
+ * Every `SiteConfig` field. Optional fields that a site leaves unset are absent at
+ * runtime, so they are listed here to keep `stati.site.description` from being
+ * reported as unknown. Typed as a Record so a new `SiteConfig` field fails to compile
+ * until it is added.
+ */
+const SITE_CONFIG_KEYS = {
+    title: true,
+    baseUrl: true,
+    defaultLocale: true,
+    description: true,
+};
+/**
+ * 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.
+ */
+const VALIDATED_NESTED_PROPERTIES = {
+    site: Object.keys(SITE_CONFIG_KEYS),
+    nav: [],
+    collection: [],
+    generator: [],
+};
+/**
+ * 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`.
+ */
+const CROSS_LEVEL_PROPERTIES = ['page', 'site', 'nav', 'partials'];
+/**
+ * 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.
+ * Use {@link parseUnknownPropertyMessage} to read them back.
+ */
+export class UnknownTemplatePropertyError extends Error {
+    propertyPath;
+    suggestions;
+    constructor(propertyPath, suggestions, availableKeys) {
+        super(formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys));
+        this.name = 'UnknownTemplatePropertyError';
+        this.propertyPath = propertyPath;
+        this.suggestions = suggestions;
+    }
+}
+function formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys) {
+    const base = `Unknown property "${propertyPath}".`;
+    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)}`;
+        return `${base} Did you mean ${list}?`;
+    }
+    return `${base} Available properties: ${availableKeys.join(', ')}.`;
+}
+/**
+ * Reads an {@link UnknownTemplatePropertyError} message back into a short message
+ * and a list of overlay suggestions. Returns `undefined` for any other message.
+ *
+ * @example
+ * ```typescript
+ * parseUnknownPropertyMessage('Unknown property "stati.paeg". Did you mean "stati.page"?');
+ * // { message: 'Unknown property "stati.paeg"', suggestions: ['Did you mean "stati.page"?'] }
+ * ```
+ */
+export function parseUnknownPropertyMessage(message) {
+    const match = message.match(/^Unknown property "([^"]+)"\.(?: Did you mean (.+)\?| Available properties: (.*)\.)?$/);
+    if (!match) {
+        return undefined;
+    }
+    const [, propertyPath, didYouMean, available] = match;
+    const suggestions = [];
+    if (didYouMean) {
+        for (const [, name] of didYouMean.matchAll(/"([^"]+)"/g)) {
+            suggestions.push(`Did you mean "${name}"?`);
+        }
+    }
+    else if (available !== undefined) {
+        const parentPath = propertyPath.slice(0, propertyPath.lastIndexOf('.'));
+        suggestions.push(`Available properties on ${parentPath}: ${available || '(none)'}`);
+    }
+    return { message: `Unknown property "${propertyPath}"`, suggestions };
+}
+function listKeys(target, extraKeys) {
+    return [...new Set([...Object.keys(target), ...extraKeys])].sort();
+}
+function createValidatingObjectProxy(target, path, extraKeys) {
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            if (prop in obj || isPassthroughProperty(prop) || extraKeys.includes(prop)) {
+                return Reflect.get(obj, prop, receiver);
+            }
+            const name = String(prop);
+            const availableKeys = listKeys(obj, extraKeys);
+            const suggestions = findSimilarNames(name, availableKeys).map((key) => `${path}.${key}`);
+            throw new UnknownTemplatePropertyError(`${path}.${name}`, suggestions, availableKeys);
+        },
+    });
+}
+/**
+ * Wraps the template context so that reading a property that does not exist
+ * throws an {@link UnknownTemplatePropertyError} with "did you mean" suggestions
+ * 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.
+ *
+ * Only active in development; other environments get the context back unchanged.
+ */
+export function createValidatingContextProxy(context) {
+    if (!isDevelopment()) {
+        return context;
+    }
+    const nestedProxies = new Map();
+    return new Proxy(context, {
+        get(obj, prop, receiver) {
+            if (prop in obj || isPassthroughProperty(prop)) {
+                const value = Reflect.get(obj, prop, receiver);
+                const nestedExtraKeys = typeof prop === 'string' && Object.hasOwn(VALIDATED_NESTED_PROPERTIES, prop)
+                    ? VALIDATED_NESTED_PROPERTIES[prop]
+                    : undefined;
+                if (nestedExtraKeys && typeof value === 'object' && value !== null) {
+                    // Cache so that repeated reads return the same proxy (stati.nav === stati.nav)
+                    let nested = nestedProxies.get(prop);
+                    if (!nested) {
+                        nested = createValidatingObjectProxy(value, `stati.${String(prop)}`, nestedExtraKeys);
+                        nestedProxies.set(prop, nested);
+                    }
+                    return nested;
+                }
+                return value;
+            }
+            const name = String(prop);
+            const availableKeys = listKeys(obj, []);
+            // 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 = [];
+            for (const parent of CROSS_LEVEL_PROPERTIES) {
+                const parentValue = obj[parent];
+                if (typeof parentValue === 'object' &&
+                    parentValue !== null &&
+                    Object.hasOwn(parentValue, name)) {
+                    suggestions.push(`stati.${parent}.${name}`);
+                }
+            }
+            suggestions.push(...findSimilarNames(name, availableKeys).map((key) => `stati.${key}`));
+            throw new UnknownTemplatePropertyError(`stati.${name}`, suggestions.slice(0, 3), availableKeys);
+        },
+    });
+}

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;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAwbnF;AA0DD;;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;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"}