@moku-labs/web 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -1,72 +1,39 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
+const require_convention = require("./convention-Dr8jxG70.cjs");
 let _moku_labs_core = require("@moku-labs/core");
-let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
-let node_path$1 = __toESM(node_path, 1);
-node_path = __toESM(node_path);
+let node_path$1 = require_convention.__toESM(node_path, 1);
+node_path = require_convention.__toESM(node_path);
 let gray_matter = require("gray-matter");
-gray_matter = __toESM(gray_matter, 1);
+gray_matter = require_convention.__toESM(gray_matter, 1);
 let _shikijs_rehype = require("@shikijs/rehype");
-_shikijs_rehype = __toESM(_shikijs_rehype, 1);
+_shikijs_rehype = require_convention.__toESM(_shikijs_rehype, 1);
 let rehype_sanitize = require("rehype-sanitize");
-rehype_sanitize = __toESM(rehype_sanitize, 1);
+rehype_sanitize = require_convention.__toESM(rehype_sanitize, 1);
 let rehype_stringify = require("rehype-stringify");
-rehype_stringify = __toESM(rehype_stringify, 1);
+rehype_stringify = require_convention.__toESM(rehype_stringify, 1);
 let unified = require("unified");
 let rehype_raw = require("rehype-raw");
-rehype_raw = __toESM(rehype_raw, 1);
+rehype_raw = require_convention.__toESM(rehype_raw, 1);
 let remark_directive = require("remark-directive");
-remark_directive = __toESM(remark_directive, 1);
+remark_directive = require_convention.__toESM(remark_directive, 1);
 let remark_frontmatter = require("remark-frontmatter");
-remark_frontmatter = __toESM(remark_frontmatter, 1);
+remark_frontmatter = require_convention.__toESM(remark_frontmatter, 1);
 let remark_gfm = require("remark-gfm");
-remark_gfm = __toESM(remark_gfm, 1);
+remark_gfm = require_convention.__toESM(remark_gfm, 1);
 let remark_parse = require("remark-parse");
-remark_parse = __toESM(remark_parse, 1);
+remark_parse = require_convention.__toESM(remark_parse, 1);
 let remark_rehype = require("remark-rehype");
-remark_rehype = __toESM(remark_rehype, 1);
+remark_rehype = require_convention.__toESM(remark_rehype, 1);
 let unist_util_visit = require("unist-util-visit");
 let hast_util_sanitize = require("hast-util-sanitize");
 let reading_time = require("reading-time");
-reading_time = __toESM(reading_time, 1);
+reading_time = require_convention.__toESM(reading_time, 1);
+let node_fs = require("node:fs");
 let node_crypto = require("node:crypto");
 let feed = require("feed");
-let _resvg_resvg_js = require("@resvg/resvg-js");
-let satori = require("satori");
-satori = __toESM(satori);
-let preact_jsx_runtime = require("preact/jsx-runtime");
+let preact = require("preact");
 let preact_render_to_string = require("preact-render-to-string");
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
@@ -295,112 +262,45 @@ function validateSchema(ctx) {
 	freezeMap(state.publicMap);
 }
 //#endregion
-//#region src/plugins/env/providers.ts
-/**
-* @file env plugin — built-in providers: dotenv, processEnv, cloudflareBindings.
-*/
-/** Default dotenv file path: optional local overrides. */
-const DEFAULT_DOTENV_PATH = ".env.local";
-/**
-* Strips a single matching pair of surrounding double or single quotes from a
-* value. Leaves unquoted values (and trailing inline comments) untouched.
-*
-* @param value - The already-trimmed raw value.
-* @returns The value with one outer quote pair removed, if present.
-* @example
-* ```ts
-* stripQuotes('"a"'); // "a"
-* stripQuotes("plain # c"); // "plain # c"
-* ```
-*/
-function stripQuotes(value) {
-	if (value.length >= 2) {
-		const first = value[0];
-		const last = value.at(-1);
-		if ((first === "\"" || first === "'") && first === last) return value.slice(1, -1);
-	}
-	return value;
-}
-/**
-* Parses `.env`-style text into a flat record. Handles CRLF/LF, blank lines,
-* full-line `#` comments, first-`=` splitting, key/value trimming, and a single
-* outer quote pair. Does not strip trailing inline comments on unquoted values.
-*
-* @param text - The raw file contents.
-* @returns A flat record of parsed key/value pairs.
-* @example
-* ```ts
-* parseDotenv('A=1\nB="two"'); // { A: "1", B: "two" }
-* ```
-*/
-function parseDotenv(text) {
-	const out = {};
-	for (const line of text.split(/\r?\n/)) {
-		const trimmed = line.trim();
-		if (trimmed === "" || trimmed.startsWith("#")) continue;
-		const eq = trimmed.indexOf("=");
-		if (eq === -1) continue;
-		const key = trimmed.slice(0, eq).trim();
-		out[key] = stripQuotes(trimmed.slice(eq + 1).trim());
-	}
-	return out;
-}
+//#region src/plugins/env/providers.browser.ts
+/** Default `globalThis` property holding a runtime-injected public-env snapshot. */
+const DEFAULT_GLOBAL_KEY = "__ENV__";
 /**
-* A zero-dependency `.env`-style provider that re-reads and re-parses the file
-* from disk on every `load()`. Missing file resolves to `{}` (optional
-* overrides). Strips a single outer quote pair; does not strip trailing inline
-* comments on unquoted values.
+* A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+* `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+* Contains zero `node:*` imports, so it is safe to include in the client bundle.
+* Never throws on missing sources — each absent source resolves to `{}`.
 *
-* @param path - Path to the dotenv file. Defaults to `.env.local`.
-* @returns An {@link EnvProvider} named `dotenv:<path>` that reads fresh per call.
+* @param options - Optional settings.
+* @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+* @returns An {@link EnvProvider} named `browser-env`.
 * @example
 * ```ts
-* const provider = dotenv(".env.local");
+* const provider = browserEnv();
 * provider.load(); // { PUBLIC_API_URL: "/api", ... }
 * ```
 */
-function dotenv(path = DEFAULT_DOTENV_PATH) {
-	return {
-		name: `dotenv:${path}`,
-		/**
-		* Reads and parses the dotenv file fresh from disk; `{}` if it is missing.
-		*
-		* @returns The parsed environment record, or `{}` when the file is absent.
-		* @example
-		* ```ts
-		* dotenv(".env.local").load();
-		* ```
-		*/
-		load() {
-			if (!(0, node_fs.existsSync)(path)) return {};
-			return parseDotenv((0, node_fs.readFileSync)(path, "utf8"));
-		}
-	};
-}
-/**
-* A provider that returns a shallow copy of `process.env` at `load()` time.
-*
-* @returns An {@link EnvProvider} named `process-env`.
-* @example
-* ```ts
-* const provider = processEnv();
-* provider.load().HOME; // current process value
-* ```
-*/
-function processEnv() {
+function browserEnv(options) {
+	const globalKey = options?.globalKey ?? DEFAULT_GLOBAL_KEY;
 	return {
-		name: "process-env",
+		name: "browser-env",
 		/**
-		* Returns a shallow copy of `process.env` at call time.
+		* Merges `import.meta.env` with `globalThis[globalKey]`, the runtime global
+		* winning. Each absent source resolves to `{}`; never throws.
 		*
-		* @returns A fresh shallow copy of `process.env`.
+		* @returns The merged environment record.
 		* @example
 		* ```ts
-		* processEnv().load();
+		* browserEnv().load();
 		* ```
 		*/
 		load() {
-			return { ...process.env };
+			const importEnv = {}.env ?? {};
+			const globalObject = globalThis[globalKey] ?? {};
+			return {
+				...importEnv,
+				...globalObject
+			};
 		}
 	};
 }
@@ -846,12 +746,29 @@ const logPlugin = (0, _moku_labs_core.createCorePlugin)("log", {
 const coreConfig = (0, _moku_labs_core.createCoreConfig)("web", {
 	config: { mode: "production" },
 	plugins: [logPlugin, envPlugin],
-	pluginConfigs: {
-		log: { mode: "production" },
-		env: { providers: [dotenv(), processEnv()] }
-	}
+	pluginConfigs: { log: { mode: "production" } }
 });
-const { createPlugin: createPlugin$1, createCore } = coreConfig;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and the core
+* plugin APIs (`log`, `env`). Plugin types are fully inferred from the spec
+* object — never write them explicitly. This is the binding every built-in
+* plugin is wired with, and the one consumer plugins should use too.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+* ```
+*/
+const createPlugin$1 = coreConfig.createPlugin;
+/**
+* Step 2 of the factory chain — captures the framework's default plugin set and
+* returns the consumer entry points ({@link createApp} + a re-exported
+* `createPlugin`). Wired once in `src/index.ts`; consumers don't call it directly.
+*/
+const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
@@ -979,6 +896,25 @@ function createI18nApi(ctx) {
 		}
 	};
 }
+/**
+* Internationalization plugin — locale registry plus a flat translation helper
+* with default-locale fallback. Pure config-as-data (no state or events);
+* consumed read-only by content, router, head, and build.
+*
+* @example Register locales and translations
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     i18n: {
+*       locales: ["en", "uk"],
+*       defaultLocale: "en",
+*       localeNames: { en: "English", uk: "Українська" },
+*       translations: { uk: { "nav.home": "Головна" } }
+*     }
+*   }
+* });
+* ```
+*/
 const i18nPlugin = createPlugin$1("i18n", {
 	config: {
 		locales: ["en"],
@@ -1379,6 +1315,23 @@ function articleToUrl(locale, slug) {
 	return `/${locale}/${slug}/`;
 }
 /**
+* Build the canonical "article not found" error for {@link createContentApi.load}.
+* Centralised so the null-resolve path and the production draft-suppression path
+* throw an IDENTICAL message — drafts must be indistinguishable from missing
+* articles in production (no new error shape).
+*
+* @param slug - Article directory name.
+* @param locale - Requested locale code.
+* @returns The not-found Error to throw.
+* @example
+* ```ts
+* throw articleNotFound("intro", "uk");
+* ```
+*/
+function articleNotFound(slug, locale) {
+	return /* @__PURE__ */ new Error(`[web] content article "${slug}" not found for locale "${locale}".\n  Looked for ${slug}/${locale}.md and the default-locale fallback.`);
+}
+/**
 * Plugin `api` factory: assembles the kernel-free {@link ContentApiContext} from
 * the plugin context (resolving i18n via `ctx.require`) and delegates to
 * {@link createContentApi}. Referenced directly as the plugin's `api` so
@@ -1612,11 +1565,16 @@ function createContentApi(ctx) {
 		/**
 		* Resolve and render a single article for one locale with locale fallback.
 		* Throws a `[web] content` error when neither the requested nor the
-		* default-locale file exists.
+		* default-locale file exists. In production a `draft` article is suppressed
+		* and throws the SAME not-found error (drafts must be indistinguishable from
+		* missing articles so unpublished content is never disclosed); in
+		* development drafts load normally.
 		*
 		* @param slug - Article directory name.
 		* @param locale - Requested locale code.
 		* @returns The resolved Article.
+		* @throws {Error} `[web] content` not-found when no file matches, or when the
+		*   resolved article is a draft and `global.mode === "production"`.
 		* @example
 		* ```ts
 		* const article = await api.load("intro", "uk");
@@ -1624,7 +1582,8 @@ function createContentApi(ctx) {
 		*/
 		async load(slug, locale) {
 			const article = await resolveArticle(ctx, slug, locale);
-			if (article === null) throw new Error(`[web] content article "${slug}" not found for locale "${locale}".\n  Looked for ${slug}/${locale}.md and the default-locale fallback.`);
+			if (article === null) throw articleNotFound(slug, locale);
+			if (ctx.global.mode === "production" && article.computed.status === "draft") throw articleNotFound(slug, locale);
 			const cache = ctx.state.articles.get(locale) ?? /* @__PURE__ */ new Map();
 			cache.set(slug, article);
 			ctx.state.articles.set(locale, cache);
@@ -1774,6 +1733,26 @@ function validateContentConfig(config) {
 * and `content:invalidated`.
 * @see README.md
 */
+/**
+* Content plugin — Markdown pipeline: discovers files, parses frontmatter, renders
+* to sanitized HTML (rehype-sanitize unless `trustedContent`), and exposes a
+* locale-keyed Article model. Depends on i18n; emits `content:ready` and
+* `content:invalidated`.
+*
+* @example Point at a content directory and pick a Shiki theme
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     content: {
+*       contentDir: "./content",
+*       shikiTheme: "github-dark",
+*       defaultAuthor: "Ada Lovelace"
+*       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
+*     }
+*   }
+* });
+* ```
+*/
 const contentPlugin = createPlugin$1("content", {
 	depends: [i18nPlugin],
 	events: contentEvents,
@@ -1937,6 +1916,25 @@ function createSiteApi(ctx) {
 		}
 	};
 }
+/**
+* Site plugin — holds global, frozen site metadata (name, url, author,
+* description) and builds canonical URLs. Consumed by router, head, and build.
+* `name` and `url` must be non-empty (validated at `onInit`).
+*
+* @example Set your site identity
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: {
+*       name: "My Blog",
+*       url: "https://blog.dev",
+*       author: "Ada Lovelace",
+*       description: "Notes on computing"
+*     }
+*   }
+* });
+* ```
+*/
 const sitePlugin = createPlugin$1("site", {
 	config: {
 		name: "",
@@ -2063,6 +2061,24 @@ function toTypedRoute(entry) {
 	};
 }
 /**
+* Project a compiled route into the serializable {@link ClientRoute} view: only
+* `pattern` / `name` / `meta`, with a fresh `meta` copy and NO `_handlers` closures.
+*
+* @param entry - The compiled route entry.
+* @returns A `ClientRoute` carrying only JSON-serializable fields.
+* @example
+* ```ts
+* toClientRoute(compiledEntry); // { pattern, name, meta }
+* ```
+*/
+function toClientRoute(entry) {
+	return {
+		pattern: entry.pattern,
+		name: entry.name,
+		meta: { ...entry.meta }
+	};
+}
+/**
 * Creates the router plugin API surface. Every closure reads the compiled table
 * from `ctx.state` and returns values/fresh copies — never the raw state arrays.
 *
@@ -2132,11 +2148,113 @@ function createApi$4(ctx) {
 		*/
 		manifest() {
 			return [...readTable(state).byName.values()].map((entry) => entry.definition);
+		},
+		/**
+		* Serializable, specificity-sorted projection of the route table for client
+		* shipping — `{ pattern, name, meta }` entries with NO `_handlers` closures.
+		*
+		* @returns A fresh, frozen, specificity-sorted read-only array of client routes.
+		* @example
+		* ```ts
+		* const json = JSON.stringify(api.clientManifest());
+		* ```
+		*/
+		clientManifest() {
+			return Object.freeze(readTable(state).compiled.map((entry) => toClientRoute(entry)));
+		},
+		/**
+		* The resolved render mode (single source of truth for static/hybrid/spa).
+		*
+		* @returns `"ssg" | "spa" | "hybrid"`.
+		* @example
+		* ```ts
+		* if (api.mode() !== "ssg") emitClientData();
+		* ```
+		*/
+		mode() {
+			return state.mode;
 		}
 	};
 }
 //#endregion
+//#region src/plugins/router/iso-match.ts
+/**
+* Parse a single path segment into its `{…}` placeholder, or `false` for a static
+* segment. Plain loop over the brace delimiters (no backtracking regex). Shared by
+* the build-time compiler and this isomorphic matcher so the two never diverge.
+*
+* @param segment - One `/`-delimited segment, e.g. `{slug}` or `about`.
+* @returns The parsed placeholder, or `false` when the segment is static.
+* @example
+* ```ts
+* parsePlaceholder("{slug:?}"); // { name: "slug", optional: true }
+* ```
+*/
+function parsePlaceholder$1(segment) {
+	if (!segment.startsWith("{") || !segment.endsWith("}")) return false;
+	const inner = segment.slice(1, -1);
+	if (inner.endsWith(":?")) return {
+		name: inner.slice(0, -2),
+		optional: true
+	};
+	return {
+		name: inner,
+		optional: false
+	};
+}
+/**
+* Counts the dynamic (`{param}` / `{param:?}` / `:param`) segments in a route
+* pattern — fewer dynamic segments rank as more specific. The optional `{lang:?}`
+* segment is excluded so locale-prefixing does not affect priority (identical to
+* the build-time compiler's count, which sourced this logic).
+*
+* @param pattern - The route pattern string.
+* @returns The number of dynamic (non-lang) segments.
+* @example
+* ```ts
+* dynamicSegmentCount("/blog/{slug}/"); // 1
+* dynamicSegmentCount("/{lang:?}/{slug}/"); // 1
+* ```
+*/
+function dynamicSegmentCount(pattern) {
+	let count = 0;
+	for (const segment of pattern.split("/")) {
+		const placeholder = parsePlaceholder$1(segment);
+		const isBraceDynamic = placeholder && !(placeholder.name === "lang" && placeholder.optional);
+		const isColonDynamic = !placeholder && segment.startsWith(":");
+		if (isBraceDynamic || isColonDynamic) count += 1;
+	}
+	return count;
+}
+/**
+* Comparator that orders two routes most-specific-first (fewest dynamic segments
+* first). Equal specificity yields `0` so a stable sort preserves declaration
+* order — the exact ordering the compiled matcher table uses, guaranteeing
+* build-time and client-time route resolution can never diverge.
+*
+* @param a - First route (carries its `pattern` string).
+* @param a.pattern - First route's pattern string.
+* @param b - Second route (carries its `pattern` string).
+* @param b.pattern - Second route's pattern string.
+* @returns Negative if `a` is more specific, positive if `b` is, `0` on a tie.
+* @example
+* ```ts
+* routes.toSorted(bySpecificity);
+* ```
+*/
+function bySpecificity(a, b) {
+	return dynamicSegmentCount(a.pattern) - dynamicSegmentCount(b.pattern);
+}
+//#endregion
 //#region src/plugins/router/builders/compile.ts
+/**
+* @file router plugin — compilation + validation domain.
+*
+* Pure functions invoked from `onInit`: validate the route map, then compile each
+* route into URLPattern matchers + URL/file builders, count dynamic segments,
+* sort by specificity, and assemble the immutable `MatcherTable`. Receives DATA
+* only (`CompileInput`) — never the plugin ctx.
+*/
 /** Shared `[web]` error prefix for router validation failures. */
 const ERROR_PREFIX$8 = "[web] router";
 /**
@@ -2251,27 +2369,6 @@ function buildFilePath(pattern, params) {
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
-* Count dynamic segments in a pattern (lower = more specific). The optional
-* `{lang:?}` segment is excluded so locale-prefixing does not affect priority.
-*
-* @param pattern - The route pattern.
-* @returns The number of dynamic (non-lang) segments.
-* @example
-* ```ts
-* countDynamicSegments("/{lang:?}/{slug}/"); // 1
-* ```
-*/
-function countDynamicSegments(pattern) {
-	let count = 0;
-	for (const segment of pattern.split("/")) {
-		const placeholder = parsePlaceholder(segment);
-		const isBraceDynamic = placeholder && !(placeholder.name === "lang" && placeholder.optional);
-		const isColonDynamic = !placeholder && segment.startsWith(":");
-		if (isBraceDynamic || isColonDynamic) count += 1;
-	}
-	return count;
-}
-/**
 * Compile a single route definition into its `CompiledRoute` entry.
 *
 * @param name - The route name key.
@@ -2293,7 +2390,7 @@ function compileRoute(name, definition, input) {
 	return {
 		name,
 		pattern,
-		dynamicSegmentCount: countDynamicSegments(pattern),
+		dynamicSegmentCount: dynamicSegmentCount(pattern),
 		matchers,
 		matchFn: createMatchFunction(matchers, input.defaultLocale),
 		/**
@@ -2350,10 +2447,7 @@ function compileRoutes(input) {
 		byName.set(name, entry);
 	}
 	return {
-		compiled: declarationOrder.map((entry, index) => ({
-			entry,
-			index
-		})).toSorted((a, b) => a.entry.dynamicSegmentCount === b.entry.dynamicSegmentCount ? a.index - b.index : a.entry.dynamicSegmentCount - b.entry.dynamicSegmentCount).map((wrapped) => wrapped.entry),
+		compiled: declarationOrder.toSorted(bySpecificity),
 		byName
 	};
 }
@@ -2466,6 +2560,21 @@ function route(pattern) {
 			return set("render", handler);
 		},
 		/**
+		* Attach the client-side validation gate (raw `unknown` → this route's data
+		* type). Runs at the trust boundary before `render` on the client; throw to
+		* reject malformed data (spa falls back to HTML-over-fetch).
+		*
+		* @param handler - The validator/parser.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/shop/{id}/").parse(raw => ProductSchema.parse(raw));
+		* ```
+		*/
+		parse(handler) {
+			return set("parse", handler);
+		},
+		/**
 		* Attach the head/SEO handler.
 		*
 		* @param handler - The head handler.
@@ -2492,9 +2601,11 @@ function route(pattern) {
 			return set("generate", handler);
 		},
 		/**
-		* Merge an arbitrary metadata bag into the route's `_meta`.
+		* Merge an arbitrary metadata bag into the route's `_meta`. The bag MUST be
+		* JSON-serializable — it is projected verbatim into `clientManifest()` and
+		* shipped to the browser, so functions/symbols/class instances are unsupported.
 		*
-		* @param meta - Metadata to merge.
+		* @param meta - JSON-serializable metadata to merge.
 		* @returns The same builder for chaining.
 		* @example
 		* ```ts
@@ -2564,8 +2675,31 @@ function defineRoutes(routes) {
 * ```
 */
 function createState$4(_ctx) {
-	return { table: null };
+	return {
+		table: null,
+		mode: _ctx.config.mode ?? "hybrid"
+	};
 }
+/**
+* Router plugin — typed, named route definitions with locale-aware URL generation
+* and matching. Author routes with {@link route} + {@link defineRoutes}. Depends
+* on site (base URL) and i18n (locales).
+*
+* @example Define routes and choose a render mode
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     router: {
+*       routes: defineRoutes({
+*         home: route("/"),
+*         article: route("/blog/{slug}/")
+*       }),
+*       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
+*     }
+*   }
+* });
+* ```
+*/
 const routerPlugin = createPlugin$1("router", {
 	depends: [sitePlugin, i18nPlugin],
 	helpers: {
@@ -3079,6 +3213,25 @@ function createState$3(_ctx) {
 * @file head — Standard Plugin wiring harness (logic in primitives/compose/api/config).
 * @see README.md
 */
+/**
+* Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
+* Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
+* ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
+* Depends on site, i18n, and router.
+*
+* @example Set global head defaults
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     head: {
+*       titleTemplate: "%s — My Blog",
+*       twitterCard: "summary_large_image",
+*       twitterHandle: "@moku_labs"
+*     }
+*   }
+* });
+* ```
+*/
 const headPlugin = createPlugin$1("head", {
 	depends: [
 		sitePlugin,
@@ -3143,6 +3296,29 @@ function resolveEntrypoints(candidates) {
 	return [];
 }
 /**
+* Resolve the authoritative JS client entrypoint (#8): when `config.clientEntry` is
+* set, use it directly (the authoritative override); otherwise fall back to the
+* conventional candidate scan. When neither yields an entry, `ctx.log.warn` (no
+* client bundle is produced) and an empty list is returned.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The resolved JS entrypoint list (possibly empty).
+* @example
+* ```ts
+* resolveJsEntrypoints(ctx);
+* ```
+*/
+function resolveJsEntrypoints(ctx) {
+	const { clientEntry } = ctx.config;
+	if (typeof clientEntry === "string" && clientEntry.length > 0) return [clientEntry];
+	const scanned = resolveEntrypoints(JS_ENTRY_CANDIDATES);
+	if (scanned.length === 0) ctx.log.warn("build:bundle", {
+		clientEntry: "none",
+		scanned: JS_ENTRY_CANDIDATES
+	});
+	return scanned;
+}
+/**
 * Run one bundler pass for a single asset kind and record the hashed output
 * paths under `state.buildCache` keyed by the original entry basename.
 *
@@ -3190,7 +3366,7 @@ async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
-	const jsEntrypoints = options.jsEntrypoints ?? resolveEntrypoints(JS_ENTRY_CANDIDATES);
+	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
 	await runOne(ctx, runner, "css", cssEntrypoints, node_path$1.default.join(outDir, "assets"), minify);
 	await runOne(ctx, runner, "js", jsEntrypoints, node_path$1.default.join(outDir, "assets"), minify);
 }
@@ -3357,10 +3533,160 @@ async function processImages(ctx, options = {}) {
 	return copied;
 }
 //#endregion
-//#region src/plugins/build/phases/og-images.tsx
+//#region src/plugins/build/phases/locale-redirects.ts
 /**
-* @file build phase 4 — og-images. Renders one OG image per published article via
-* Satori → SVG → resvg → PNG, bounded by `p-limit(4)`, with a persisted
+* @file build phase — locale-redirects. For each non-prefixed route path, emits a
+* redirect HTML page (`<meta http-equiv="refresh">` + canonical `<link>`) at the
+* bare path that points at the default-locale-prefixed URL. Deliberately does NOT
+* emit a Cloudflare `_redirects` catch-all (an SSG infinite-loop trap). Gated by
+* `config.localeRedirects` (false/unset disables).
+*/
+/**
+* Render a redirect HTML page: a `0;url` refresh meta + a canonical link to `target`.
+*
+* @param target - The default-locale-prefixed URL to redirect to.
+* @returns The complete redirect HTML document string.
+* @example
+* ```ts
+* redirectHtml("/en/about/");
+* ```
+*/
+function redirectHtml(target) {
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}"></head><body><a href="${target}">Redirecting…</a></body></html>`;
+}
+/**
+* Correlate manifest definitions to compiled `TypedRoute` entries by pattern (the
+* shared stable key); routes without a compiled entry are skipped.
+*
+* @param router - The router API exposing `manifest` + `entries`.
+* @returns Pairs of `[definition, entry]` for every correlated route.
+* @example
+* ```ts
+* pairRoutes(router);
+* ```
+*/
+function pairRoutes(router) {
+	const byPattern = /* @__PURE__ */ new Map();
+	for (const entry of router.entries()) byPattern.set(entry.pattern, entry);
+	const pairs = [];
+	for (const definition of router.manifest()) {
+		const entry = byPattern.get(definition.pattern);
+		if (entry) pairs.push([definition, entry]);
+	}
+	return pairs;
+}
+/**
+* Expand one route into bare→default redirect jobs for the default locale. Uses
+* `generate?.(defaultLocale)` (or a single empty-params instance) and emits a job
+* only when the bare file path differs from the default-locale URL (i.e. the route
+* is locale-prefixed) — otherwise no redirect is needed.
+*
+* @param definition - The route definition (carries `generate`).
+* @param entry - The compiled `TypedRoute` (owns `toFile`/`toUrl`).
+* @param defaultLocale - The default locale to redirect bare paths to.
+* @returns Redirect jobs of `{ file, target }` for this route.
+* @example
+* ```ts
+* await expandRedirects(def, entry, "en");
+* ```
+*/
+async function expandRedirects(definition, entry, defaultLocale) {
+	const parameterSets = definition._handlers.generate ? await definition._handlers.generate(defaultLocale) : [{}];
+	const jobs = [];
+	for (const raw of parameterSets) {
+		const params = raw ?? {};
+		const file = entry.toFile(params);
+		const target = entry.toUrl({
+			...params,
+			lang: defaultLocale
+		});
+		if (target !== entry.toUrl(params)) jobs.push({
+			file,
+			target
+		});
+	}
+	return jobs;
+}
+/**
+* Emits one bare-path redirect HTML page per locale-prefixed route path, each a
+* `0;url` refresh + canonical link to the default-locale URL. Never writes a
+* Cloudflare `_redirects` file. No-op (returns `null`) when `localeRedirects` is
+* false/unset.
+*
+* @param ctx - Plugin context (provides `require`, `config`, `log`).
+* @returns The count of redirect pages written, or `null` when disabled.
+* @example
+* ```ts
+* const result = await generateLocaleRedirects(ctx);
+* ```
+*/
+async function generateLocaleRedirects(ctx) {
+	if (!ctx.config.localeRedirects) {
+		ctx.log.debug("build:locale-redirects", { skipped: true });
+		return null;
+	}
+	const router = ctx.require(routerPlugin);
+	const defaultLocale = ctx.require(i18nPlugin).defaultLocale();
+	const jobs = (await Promise.all(pairRoutes(router).map(([definition, entry]) => expandRedirects(definition, entry, defaultLocale)))).flat();
+	await Promise.all(jobs.map(async ({ file, target }) => {
+		const filePath = node_path$1.default.join(ctx.config.outDir, file);
+		await (0, node_fs_promises.mkdir)(node_path$1.default.dirname(filePath), { recursive: true });
+		await (0, node_fs_promises.writeFile)(filePath, redirectHtml(target), "utf8");
+	}));
+	ctx.log.debug("build:locale-redirects", { written: jobs.length });
+	return { written: jobs.length };
+}
+//#endregion
+//#region src/plugins/build/phases/not-found.ts
+/**
+* @file build phase — not-found. Emits `outDir/404.html` from configured route
+* content or a built-in default. Gated by `config.notFound` (false/unset disables).
+*/
+/** The built-in default 404 page body when no custom route content is supplied. */
+const DEFAULT_BODY = "<h1>404</h1><p>The page you requested could not be found.</p>";
+/**
+* Wrap a body fragment in a minimal HTML document for the 404 page.
+*
+* @param body - The inner body HTML (default or configured).
+* @returns The complete HTML document string.
+* @example
+* ```ts
+* wrap("<h1>404</h1>");
+* ```
+*/
+function wrap(body) {
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>404 — Not Found</title></head><body>${body}</body></html>`;
+}
+/**
+* Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
+* default page; when it is `{ route }`, writes the supplied route content verbatim
+* inside the document shell. No-op (returns `null`) when `notFound` is false/unset.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The written file path, or `null` when disabled.
+* @example
+* ```ts
+* const result = await generateNotFound(ctx);
+* ```
+*/
+async function generateNotFound(ctx) {
+	const { notFound, outDir } = ctx.config;
+	if (!notFound) {
+		ctx.log.debug("build:not-found", { skipped: true });
+		return null;
+	}
+	const body = typeof notFound === "object" && notFound.route ? notFound.route : DEFAULT_BODY;
+	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
+	const file = node_path$1.default.join(outDir, "404.html");
+	await (0, node_fs_promises.writeFile)(file, wrap(body), "utf8");
+	ctx.log.debug("build:not-found", { path: file });
+	return { path: file };
+}
+//#endregion
+//#region src/plugins/build/phases/og-images.tsx
+/**
+* @file build phase 4 — og-images. Renders one OG image per published article via
+* Satori → SVG → resvg → PNG, bounded by `p-limit(4)`, with a persisted
 * content-hash cache (`<outDir>/.cache/og-images.json`) skipping unchanged articles.
 * Gated by config.ogImage (object enables; false disables).
 */
@@ -3376,76 +3702,131 @@ const FONT_EXTENSIONS$1 = [
 	".woff"
 ];
 /**
-* Compute the content-hash cache key for an article: `sha256(title+template+size)`.
+* Compute a stable cache key for the `fonts` configuration so a font change
+* invalidates cached PNGs. Hashes the name/path/weight/style of each entry (order
+* preserved); an empty/omitted list yields a fixed sentinel.
 *
-* @param title - The article title.
-* @param template - The resolved OG template identifier.
-* @param size - The output dimensions.
-* @returns The hex-encoded SHA-256 digest.
+* @param fonts - The configured OG fonts (optional).
+* @returns A short stable key derived from the fonts list.
 * @example
 * ```ts
-* ogHash("Hello", "default", { width: 1200, height: 630 });
+* fontsKey([{ name: "Inter", path: "./Inter.ttf" }]);
 * ```
 */
-function ogHash(title, template, size) {
-	return (0, node_crypto.createHash)("sha256").update(`${title}|${template}|${size.width}x${size.height}`).digest("hex");
+function fontsKey(fonts) {
+	if (!fonts || fonts.length === 0) return "default-font";
+	const parts = fonts.map((font) => `${font.name}:${font.path}:${font.weight ?? 400}:${font.style ?? "normal"}`);
+	return (0, node_crypto.createHash)("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
 }
 /**
-* Resolve the first font file in `fontDir` and read its bytes for Satori.
+* Compute the content-hash cache key for an article OG image. Covers the FULL
+* {@link RichOgInput} (title/description/date/tags/author/locale/siteName/size),
+* the resolved `template`, and a {@link fontsKey} of the fonts list — so changing
+* any input field OR the fonts invalidates the cached PNG.
 *
-* @param fontDir - Directory containing at least one font file.
-* @returns The font name + bytes, or `null` when no font is present.
+* @param input - The full rich OG input for the card.
+* @param template - The resolved OG template identifier.
+* @param fontsHash - The {@link fontsKey} of the configured fonts.
+* @returns The hex-encoded SHA-256 digest.
 * @example
 * ```ts
-* await loadFont("./fonts");
+* ogHash(input, "default", fontsKey());
 * ```
 */
-async function loadFont(fontDir) {
-	if (!(0, node_fs.existsSync)(fontDir)) return void 0;
-	const font = (await (0, node_fs_promises.readdir)(fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
-	if (!font) return void 0;
-	return {
+function ogHash(input, template, fontsHash) {
+	const payload = [
+		input.title,
+		input.description,
+		input.date,
+		input.tags.join(","),
+		input.author ?? "",
+		input.locale,
+		input.siteName,
+		`${input.size.width}x${input.size.height}`,
+		template,
+		fontsHash
+	].join("|");
+	return (0, node_crypto.createHash)("sha256").update(payload).digest("hex");
+}
+/**
+* Load the configured OG fonts ONCE per build. When `ogImage.fonts` is set, each
+* `path` is read to a Buffer (outside any per-image loop) and mapped to a Satori
+* font entry; otherwise the first font file found in `fontDir` is used as a single
+* 400/normal fallback.
+*
+* @param og - The font directory + optional explicit fonts list.
+* @param og.fontDir - Directory scanned for a fallback font when `fonts` is unset.
+* @param og.fonts - Explicit named fonts (each loaded once).
+* @returns The loaded fonts (empty when no font is available).
+* @example
+* ```ts
+* await loadFonts({ fontDir: "./fonts" });
+* ```
+*/
+async function loadFonts(og) {
+	if (og.fonts && og.fonts.length > 0) return Promise.all(og.fonts.map(async (font) => ({
+		name: font.name,
+		data: await (0, node_fs_promises.readFile)(font.path),
+		weight: font.weight ?? 400,
+		style: font.style ?? "normal"
+	})));
+	if (!(0, node_fs.existsSync)(og.fontDir)) return [];
+	const file = (await (0, node_fs_promises.readdir)(og.fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
+	if (!file) return [];
+	return [{
 		name: "OG",
-		data: await (0, node_fs_promises.readFile)(node_path.default.join(fontDir, font))
-	};
+		data: await (0, node_fs_promises.readFile)(node_path.default.join(og.fontDir, file)),
+		weight: 400,
+		style: "normal"
+	}];
 }
 /**
-* The default PNG renderer: Satori renders a card to SVG, resvg rasterizes to PNG.
+* The built-in default OG card — a centered title on a dark background. Used when
+* no custom `ogImage.render` hook is configured. (`@jsxImportSource preact`.)
 *
-* @param ctx - The font directory + template wiring for the renderer.
-* @param ctx.fontDir - Directory containing at least one font file.
-* @returns An {@link OgPngRenderer} bound to the loaded font.
+* @param input - The rich OG input (only `title` is used by the default card).
+* @returns The Preact `VNode` for the default card.
+* @example
+* ```ts
+* defaultCard(input);
+* ```
+*/
+function defaultCard(input) {
+	return (0, preact.h)("div", { style: {
+		display: "flex",
+		width: "100%",
+		height: "100%",
+		alignItems: "center",
+		justifyContent: "center",
+		fontSize: 64,
+		background: "#0b0b0c",
+		color: "#ffffff"
+	} }, input.title);
+}
+/**
+* The default PNG renderer: a Preact `VNode` (custom `render` hook or the built-in
+* card) is rendered to SVG by Satori, then rasterized to PNG by resvg. Both native
+* deps are imported LAZILY (browser-safe goal); the VNode→Satori-input cast happens
+* at this single framework boundary only.
+*
+* @param ctx - The renderer wiring (preloaded fonts + optional custom card).
+* @param ctx.fonts - Fonts loaded once for the whole render pass.
+* @param ctx.render - Optional custom card renderer; defaults to {@link defaultCard}.
+* @returns An {@link OgPngRenderer} bound to the loaded fonts + renderer.
 * @example
 * ```ts
-* const render = makeDefaultRenderer({ fontDir: "./fonts" });
+* const render = makeDefaultRenderer({ fonts, render: undefined });
 * ```
 */
 function makeDefaultRenderer(ctx) {
-	const fontPromise = loadFont(ctx.fontDir);
-	return async ({ title, width, height }) => {
-		const font = await fontPromise;
-		if (!font) throw new Error("[web] build.ogImage no font available for rendering");
-		return new _resvg_resvg_js.Resvg(await (0, satori.default)(/* @__PURE__ */ (0, preact_jsx_runtime.jsx)("div", {
-			style: {
-				display: "flex",
-				width: "100%",
-				height: "100%",
-				alignItems: "center",
-				justifyContent: "center",
-				fontSize: 64,
-				background: "#0b0b0c",
-				color: "#ffffff"
-			},
-			children: title
-		}), {
-			width,
-			height,
-			fonts: [{
-				name: font.name,
-				data: font.data,
-				weight: 400,
-				style: "normal"
-			}]
+	return async (input) => {
+		if (ctx.fonts.length === 0) throw new Error("[web] build.ogImage no font available for rendering");
+		const { default: satori } = await import("satori");
+		const { Resvg } = await import("@resvg/resvg-js");
+		return new Resvg(await satori((ctx.render ?? defaultCard)(input), {
+			width: input.size.width,
+			height: input.size.height,
+			fonts: ctx.fonts
 		})).render().asPng();
 	};
 }
@@ -3463,13 +3844,59 @@ function selectArticles(byLocale) {
 	return ([...byLocale.values()][0] ?? []).filter((article) => article.computed.status === "published");
 }
 /**
+* Build the {@link RichOgInput} for one article from its frontmatter/computed
+* fields plus the resolved size and site name.
+*
+* @param article - The published article to render a card for.
+* @param size - The resolved OG output dimensions.
+* @param siteName - The site name (from the site plugin, or `""` when unavailable).
+* @returns The fully-populated rich OG input.
+* @example
+* ```ts
+* buildInput(article, { width: 1200, height: 630 }, "Blog");
+* ```
+*/
+function buildInput(article, size, siteName) {
+	const input = {
+		title: article.frontmatter.title,
+		description: article.frontmatter.description,
+		date: article.frontmatter.date,
+		tags: [...article.frontmatter.tags],
+		locale: article.locale,
+		siteName,
+		size
+	};
+	if (article.frontmatter.author !== void 0) input.author = article.frontmatter.author;
+	return input;
+}
+/**
+* Resolve the site name via `ctx.require(sitePlugin)`, falling back to `""` when the
+* site API is unavailable (e.g. unit mocks that omit it).
+*
+* @param ctx - Plugin context (provides `require`).
+* @returns The site name, or `""` when the site plugin is not wired.
+* @example
+* ```ts
+* resolveSiteName(ctx);
+* ```
+*/
+function resolveSiteName(ctx) {
+	try {
+		return ctx.require(sitePlugin).name();
+	} catch {
+		return "";
+	}
+}
+/**
 * Renders OG images for published articles with a `p-limit(4)` concurrency pool.
-* Computes `sha256(title+template+size)` per article and skips regeneration when
-* the hash matches `state.ogImageHashCache`; writes the cache back to
-* `<outDir>/.cache/og-images.json`. No-op when `config.ogImage` is false.
+* Computes {@link ogHash} (full {@link RichOgInput} + template + fonts) per article
+* and skips regeneration when the hash matches `state.ogImageHashCache`; writes the
+* cache back to `<outDir>/.cache/og-images.json`. The configured `ogImage.render`
+* hook (when present) builds each card; otherwise the built-in card is used. Fonts
+* are loaded ONCE for the whole pass. No-op when `config.ogImage` is false.
 *
-* @param ctx - Plugin context (provides `state`, `config`, `log`).
-* @param options - Optional dependency-injection seam (PNG renderer).
+* @param ctx - Plugin context (provides `require`, `state`, `config`, `log`).
+* @param options - Optional dependency-injection seam (PNG rasterizer).
 * @returns The render/skip counts + peak concurrency, or `null` when disabled.
 * @example
 * ```ts
@@ -3483,9 +3910,17 @@ async function generateOgImages(ctx, options = {}) {
 		return null;
 	}
 	const { default: pLimit } = await import("p-limit");
-	const size = og.size ?? DEFAULT_SIZE;
-	const template = og.template ?? "default";
-	const renderPng = options.renderPng ?? makeDefaultRenderer({ fontDir: og.fontDir });
+	const config = og;
+	const size = config.size ?? DEFAULT_SIZE;
+	const template = config.template ?? "default";
+	const fontsHash = fontsKey(config.fonts);
+	const fonts = options.renderPng ? [] : await loadFonts(config);
+	const renderHook = config.render ? { render: config.render } : {};
+	const renderPng = options.renderPng ?? makeDefaultRenderer({
+		fonts,
+		...renderHook
+	});
+	const siteName = resolveSiteName(ctx);
 	const articles = selectArticles(readCachedContent(ctx));
 	const cache = ctx.state.ogImageHashCache;
 	await loadDiskCache(ctx.config.outDir, cache);
@@ -3497,7 +3932,8 @@ async function generateOgImages(ctx, options = {}) {
 	const outDir = node_path.default.join(ctx.config.outDir, "og");
 	await Promise.all(articles.map((article) => limit(async () => {
 		const key = article.computed.contentId;
-		const hash = ogHash(article.frontmatter.title, template, size);
+		const input = buildInput(article, size, siteName);
+		const hash = ogHash(input, template, fontsHash);
 		if (cache.get(key) === hash) {
 			skipped += 1;
 			return;
@@ -3505,10 +3941,7 @@ async function generateOgImages(ctx, options = {}) {
 		active += 1;
 		peakConcurrency = Math.max(peakConcurrency, active);
 		try {
-			const png = await renderPng({
-				title: article.frontmatter.title,
-				...size
-			});
+			const png = await renderPng(input);
 			await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 			await (0, node_fs_promises.writeFile)(node_path.default.join(outDir, `${key}.png`), png);
 			cache.set(key, hash);
@@ -3563,28 +3996,329 @@ async function persistDiskCache(outDir, cache) {
 	await (0, node_fs_promises.writeFile)(node_path.default.join(dir, "og-images.json"), JSON.stringify(Object.fromEntries(cache)), "utf8");
 }
 //#endregion
+//#region src/plugins/data/load-json.ts
+/**
+* @file `loadJson` — the data plugin's isomorphic JSON read primitive (the
+* SSG↔SPA seam). Internal to the `data` plugin (NOT a framework-root export):
+* `data.load(locale)` uses it, and consumers read through `app.data.load(locale)`.
+*
+* A read runs in BOTH worlds: on Node it reads the emitted data file from disk;
+* on the client (browser) it fetches the same data over HTTP. `loadJson` is the
+* single point where those two worlds differ — everything above it (the route's
+* `load`/`render`) is shared, so SSR/client parity is structural, not hoped-for.
+*
+* The browser path uses the `fetch` global. The Node path lazy-imports
+* `node:fs/promises` via `await import(...)`, so a browser bundle that includes
+* `loadJson` never statically pulls `node:*` (the bundler splits the Node branch
+* into its own chunk that the browser never loads).
+*/
+/**
+* Read + parse a JSON resource, isomorphically. In a browser (`document`
+* defined) it `fetch`es `pathOrUrl`; on Node it reads the file from disk. Throws
+* on a failed fetch or unreadable file so the caller (`route.load`/`data.load`)
+* can decide whether to fall back.
+*
+* @template T - The expected shape of the parsed JSON.
+* @param pathOrUrl - A site-root URL (browser) or filesystem path (Node).
+* @returns The parsed JSON, typed as `T`.
+* @throws {Error} If the browser fetch is not OK, or the Node file read fails.
+* @example
+* ```ts
+* // Browser: fetch("/_data/en/articles.json")
+* // Node:    read "dist/_data/en/articles.json"
+* const articles = await loadJson<Article[]>("/_data/en/articles.json");
+* ```
+*/
+async function loadJson(pathOrUrl) {
+	if (typeof document === "undefined") {
+		const { readFile } = await import("node:fs/promises");
+		return JSON.parse(await readFile(pathOrUrl, "utf8"));
+	}
+	const response = await fetch(pathOrUrl);
+	if (!response.ok) throw new Error(`[web] loadJson: failed to fetch ${pathOrUrl} (${String(response.status)}).`);
+	return response.json();
+}
+//#endregion
+//#region src/plugins/data/api.ts
+/**
+* @file data plugin — API factory (the agnostic data provider surface).
+*
+* Node-free by construction: this module statically imports only types + the pure
+* convention. The Node write side (`write()`) reaches its `node:fs` writer through
+* a lazy `await import("./writer")` at call time, so a browser bundle that composes
+* `data` for the read side never pulls `node:*`. The read side (`at()`) uses only
+* the isomorphic `loadJson` (whose Node branch is itself lazy).
+*/
+/**
+* Trim a single trailing slash from a config dir so `fileFor` joins cleanly.
+*
+* @param dir - The configured output dir (e.g. `"_data"` or `"_data/"`).
+* @returns The dir without a trailing slash.
+* @example
+* ```ts
+* trimTrailingSlash("_data/"); // "_data"
+* ```
+*/
+function trimTrailingSlash(dir) {
+	return dir.endsWith("/") ? dir.slice(0, -1) : dir;
+}
+/**
+* Builds the data provider — the agnostic bridge. `write()` is the Node persist
+* side; `at()` is the browser read side; `urlFor`/`fileFor` are the pure
+* convention. No `onStart`/`onStop` (holds no long-lived resource).
+*
+* @param ctx - The data plugin context.
+* @returns The {@link DataProvider} mounted at `app.data`.
+* @example
+* ```ts
+* const api = dataApi(ctx);
+* await api.write([{ path: "/en/hello/", data: article }]); // Node build
+* await api.at("/en/hello/");                               // browser
+* ```
+*/
+function dataApi(ctx) {
+	return {
+		/**
+		* READ (browser) — fetch (and cache) the persisted data for a page path.
+		* Returns the raw JSON as `unknown` (the caller's `route.parse` validates it),
+		* or `null` if the fetch/parse fails (so `spa` can fall back to HTML).
+		*
+		* @param path - The page URL path (e.g. `/en/hello/`).
+		* @returns The page's raw data, or `null` on failure.
+		* @example
+		* ```ts
+		* const raw = await api.at("/en/hello/");
+		* ```
+		*/
+		async at(path) {
+			if (ctx.state.cache.has(path)) return ctx.state.cache.get(path);
+			try {
+				const data = await loadJson(`${ctx.config.baseUrl}${require_convention.dataSuffix(path)}`);
+				ctx.state.cache.set(path, data);
+				return data;
+			} catch {
+				return null;
+			}
+		},
+		/**
+		* WRITE (Node) — persist one JSON file per entry, keyed by page path. Called by
+		* `build` after it expands routes. Lazily loads its `node:fs` writer (keeping a
+		* browser bundle node-free).
+		*
+		* @param entries - The per-page data to persist.
+		* @param options - Optional `{ outDir }` override (defaults to `./dist`).
+		* @param options.outDir - Build output directory the write happens under.
+		* @returns A summary of the written files.
+		* @example
+		* ```ts
+		* await api.write([{ path: "/en/hello/", data: article }], { outDir: "dist" });
+		* ```
+		*/
+		async write(entries, options) {
+			const { writeData } = await Promise.resolve().then(() => require("./writer-DAF0pM25.cjs"));
+			return writeData(ctx, entries, options);
+		},
+		/**
+		* PURE — the browser fetch URL for a page path.
+		*
+		* @param path - The page URL path.
+		* @returns The site-root-relative data URL.
+		* @example
+		* ```ts
+		* api.urlFor("/en/hello/"); // "/_data/en/hello/index.json"
+		* ```
+		*/
+		urlFor(path) {
+			return `${ctx.config.baseUrl}${require_convention.dataSuffix(path)}`;
+		},
+		/**
+		* PURE — the `outDir`-relative file path for a page path.
+		*
+		* @param path - The page URL path.
+		* @returns The output-relative file path.
+		* @example
+		* ```ts
+		* api.fileFor("/en/hello/"); // "_data/en/hello/index.json"
+		* ```
+		*/
+		fileFor(path) {
+			return `${trimTrailingSlash(ctx.config.outputDir)}/${require_convention.dataSuffix(path)}`;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/data/config.ts
+/**
+* Typed default data config (R6: no inline `as`). `outputDir` is the WRITE path
+* (filesystem, relative to the build `outDir`); `baseUrl` is the matching READ URL
+* (site-root-relative) the browser fetches from — the defaults agree
+* (`"_data"` ↔ `"/_data/"`).
+*
+* @example
+* ```ts
+* createPlugin("data", { config: defaultDataConfig });
+* ```
+*/
+const defaultDataConfig = {
+	outputDir: "_data",
+	baseUrl: "/_data/"
+};
+//#endregion
+//#region src/plugins/data/state.ts
+/**
+* Creates initial data state: a null `lastWrite` slot (populated by the Node
+* `write()` side) and an empty `cache` (populated lazily by the browser `at(path)`
+* side on first fetch).
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global framework configuration.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns Fresh data state with no recorded write and an empty per-path cache.
+* @example
+* ```ts
+* const state = createDataState({ global: {}, config });
+* ```
+*/
+function createDataState(_ctx) {
+	return {
+		lastWrite: null,
+		cache: /* @__PURE__ */ new Map()
+	};
+}
+//#endregion
+//#region src/plugins/data/validate.ts
+/**
+* Validates the resolved data config: the browser `baseUrl` must be a non-empty,
+* site-root-relative URL path. The emit/read pipelines are wired in build waves 3/4.
+*
+* @param config - The resolved plugin configuration.
+* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @example
+* ```ts
+* validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
+* ```
+*/
+function validateDataConfig(config) {
+	if (typeof config.baseUrl !== "string" || !config.baseUrl.startsWith("/")) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
+}
+//#endregion
+//#region src/plugins/data/index.ts
+/**
+* @file data — Standard tier plugin (wiring-only). The AGNOSTIC data provider for
+* the SSG→DATA→SPA pattern.
+*
+* Owns ONE contract — `page path → persisted JSON file` — and nothing about what
+* the data is: `write(entries)` persists per-page JSON on Node (build supplies the
+* entries it already expanded); `at(path)` fetches + caches it in the browser as
+* `unknown`, which the route's `parse` validates before `render`. NOT a framework
+* default — the consumer composes it where needed (Node build AND/OR browser app).
+*
+* **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
+* a lazy `import()` inside `write()`. Build ordering is a call-site contract: build
+* writes data during its pages phase (after its Phase-0 clean), via `app.data.write`.
+* No `onStart`/`onStop`.
+* @see README.md
+*/
+/**
+* Data plugin — the agnostic data provider. Mounts `write(entries)` (Node persist),
+* `at(path)` (browser read), and the pure `urlFor`/`fileFor` convention at `app.data`.
+*
+* @example
+* ```ts
+* // Node build: `build` calls app.data.write(...) during its pages phase when
+* // router.mode !== "ssg". Just compose the plugin:
+* const app = createApp({
+*   plugins: [dataPlugin, contentPlugin, buildPlugin],
+*   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+* });
+* await app.start();
+* await app.build.run();   // writes HTML + per-page data sidecars
+*
+* // Browser app: compose `dataPlugin` too; spa fetches via app.data.at(path) on nav.
+* ```
+*/
+const dataPlugin = createPlugin$1("data", {
+	config: defaultDataConfig,
+	createState: createDataState,
+	onInit: (ctx) => validateDataConfig(ctx.config),
+	api: dataApi
+});
+//#endregion
 //#region src/plugins/build/phases/pages.tsx
 /**
 * @file build phase 3 — pages. Pulls `router.manifest()` + `head.render(route, data)`
 * and SSR-renders each route to static HTML (preact-render-to-string). Appends the
 * build-id meta tag after `head.render()` returns. Does NOT compose `<head>` itself.
 */
+/** Template placeholder for the composed `<head>` inner HTML. */
+const HEAD_PLACEHOLDER = "<!--moku:head-->";
+/** Template placeholder for the SSR-rendered body HTML. */
+const BODY_PLACEHOLDER = "<!--moku:body-->";
+/** Template placeholder for the injected asset `<link>`/`<script>` tags. */
+const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
 /**
-* Compose the full static HTML document, injecting the build-id meta tag into
-* `<head>` AFTER the head plugin's composed HTML (build metadata, not content).
+* Read the bundle phase's hashed asset manifest for one kind from `state.buildCache`
+* as a typed {@link BuildCacheEntry} (no `Map<string, unknown>` reads).
 *
-* @param headHtml - The composed `<head>` inner HTML from `head.render`.
-* @param bodyHtml - The SSR-rendered body HTML.
-* @param runId - The per-run build id injected as `<meta name="build-id">`.
-* @param locale - The page locale for the `<html lang>` attribute.
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The hashed-path manifest entry, or an empty object when absent.
+* @example
+* ```ts
+* readManifest(ctx, "css");
+* ```
+*/
+function readManifest(ctx, kind) {
+	const entry = ctx.state.buildCache.get(kind);
+	return entry && typeof entry === "object" ? entry : {};
+}
+/**
+* Build the asset `<link>`/`<script>` tag block from the hashed manifests. Returns
+* an empty string when `config.injectAssets === false`. Asset paths are emitted as
+* absolute (`/`-rooted) URLs.
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @returns The injected asset tags, or `""` when injection is disabled.
+* @example
+* ```ts
+* buildAssetTags(ctx);
+* ```
+*/
+function buildAssetTags(ctx) {
+	if (ctx.config.injectAssets === false) return "";
+	const css = Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`);
+	const js = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`);
+	return [...css, ...js].join("");
+}
+/**
+* Compose the full static HTML document with the in-code shell, injecting the
+* build-id meta tag into `<head>` AFTER the head plugin's composed HTML (build
+* metadata, not content) and the asset tags at the end of `<head>`.
+*
+* @param parts - The composed head/body/assets/locale pieces.
 * @returns The complete HTML document string.
 * @example
 * ```ts
-* renderDocument("<title>Hi</title>", "<h1>Hi</h1>", "run-1", "en");
+* renderDocument({ head: "<title>Hi</title>", body: "<h1>Hi</h1>", assets: "", locale: "en" });
+* ```
+*/
+function renderDocument(parts) {
+	return `<!DOCTYPE html><html lang="${parts.locale}"><head>${parts.head}${parts.assets}</head><body>${parts.body}</body></html>`;
+}
+/**
+* Fill a shell template's `<!--moku:head-->` / `<!--moku:body-->` /
+* `<!--moku:assets-->` placeholders deterministically at build time.
+*
+* @param template - The raw shell template HTML.
+* @param parts - The composed head/body/assets pieces.
+* @returns The filled document string.
+* @example
+* ```ts
+* fillTemplate(shell, { head, body, assets, locale: "en" });
 * ```
 */
-function renderDocument(headHtml, bodyHtml, runId, locale) {
-	return `<!DOCTYPE html><html lang="${locale}"><head>${headHtml}${`<meta name="build-id" content="${runId}">`}</head><body>${bodyHtml}</body></html>`;
+function fillTemplate(template, parts) {
+	return template.replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets);
 }
 /**
 * Expand one route definition into its concrete page instances across all
@@ -3661,18 +4395,24 @@ function adaptHeadConfig(config) {
 	return adapted;
 }
 /**
-* Render one page instance to its static HTML document and write it to disk.
+* Render one page instance to its static HTML document and write it to disk. Uses
+* the configured shell `template` (filled at build time) when supplied, otherwise
+* the in-code shell; injects the precomputed asset tags + build-id meta.
 *
 * @param ctx - Plugin context (provides `require`, `state`, `config`).
 * @param instance - The concrete page instance to render.
+* @param shell - Wiring shared across instances (asset tags + optional template).
+* @param shell.assets - The injected asset `<link>`/`<script>` tags.
+* @param shell.template - The shell template HTML, or `null` for the in-code shell.
 * @returns The instance's URL and rendered HTML (HTML reused for the root page).
 * @example
 * ```ts
-* await renderInstance(ctx, instance);
+* await renderInstance(ctx, instance, { assets: "", template: null });
 * ```
 */
-async function renderInstance(ctx, instance) {
+async function renderInstance(ctx, instance, shell) {
 	const { definition, entry, params, locale, name } = instance;
+	const hasData = definition._handlers.load !== void 0;
 	const data = definition._handlers.load ? await definition._handlers.load(params, locale) : void 0;
 	const routeContext = {
 		params,
@@ -3689,14 +4429,24 @@ async function renderInstance(ctx, instance) {
 	};
 	if (headConfig) resolved.head = adaptHeadConfig(headConfig);
 	const headHtml = ctx.require(headPlugin).render(resolved, data);
+	const buildIdMeta = `<meta name="build-id" content="${ctx.state.runId ?? ""}">`;
 	const vnode = definition._handlers.render?.(routeContext);
-	const html = renderDocument(headHtml, vnode ? (0, preact_render_to_string.renderToString)(vnode) : "", ctx.state.runId ?? "", locale);
+	const bodyHtml = vnode ? (0, preact_render_to_string.renderToString)(vnode) : "";
+	const parts = {
+		head: `${headHtml}${buildIdMeta}`,
+		body: bodyHtml,
+		assets: shell.assets,
+		locale
+	};
+	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
 	const filePath = (0, node_path.join)(ctx.config.outDir, entry.toFile(params));
 	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(filePath), { recursive: true });
 	await (0, node_fs_promises.writeFile)(filePath, html, "utf8");
 	return {
 		url,
-		html
+		html,
+		data,
+		hasData
 	};
 }
 /**
@@ -3714,14 +4464,56 @@ async function renderInstance(ctx, instance) {
 * const { pageCount, rootHtml } = await renderPages(ctx);
 * ```
 */
+/**
+* Enforce the data-validation contract: in `hybrid`/`spa` mode, any route that
+* has BOTH a `render` and a `load` (so it will be client-data-navigated) MUST
+* declare a `.parse()` validator — otherwise fetched JSON would reach `render`
+* unvalidated. Converts a runtime safety hole into a build error.
+*
+* @param manifest - The route definitions from `router.manifest()`.
+* @param mode - The resolved render mode.
+* @throws {Error} If a data-navigable route is missing `.parse()` in hybrid/spa mode.
+* @example
+* ```ts
+* assertDataValidators(router.manifest(), router.mode());
+* ```
+*/
+function assertDataValidators(manifest, mode) {
+	if (mode === "ssg") return;
+	for (const definition of manifest) {
+		const { render, load, parse } = definition._handlers;
+		if (render && load && !parse) throw new Error(`[web] build: route "${definition.pattern}" enables client data navigation (router mode "${mode}") but has no .parse() validator. Add .parse(raw => /* validate → data */) so fetched JSON is validated before render, or set router mode "ssg" to disable data navigation.`);
+	}
+}
 async function renderPages(ctx) {
 	const router = ctx.require(routerPlugin);
 	const manifest = router.manifest();
 	ctx.state.manifest = [...manifest];
+	const mode = router.mode();
+	assertDataValidators(manifest, mode);
 	const byPattern = makeEntryMap(router);
 	const locales = ctx.require(i18nPlugin).locales();
+	const templatePath = ctx.config.template;
+	const template = typeof templatePath === "string" && (0, node_fs.existsSync)(templatePath) ? await (0, node_fs_promises.readFile)(templatePath, "utf8") : null;
+	const shell = {
+		assets: buildAssetTags(ctx),
+		template
+	};
 	const instances = (await Promise.all(manifest.map((definition) => expandRoute(definition, locales, byPattern)))).flat();
-	const rendered = await Promise.all(instances.map((instance) => renderInstance(ctx, instance)));
+	const rendered = await Promise.all(instances.map((instance) => renderInstance(ctx, instance, shell)));
+	if (mode !== "ssg" && ctx.has("data")) {
+		const entries = rendered.filter((page) => page.hasData).map((page) => ({
+			path: page.url,
+			data: page.data
+		}));
+		if (entries.length > 0) {
+			const summary = await ctx.require(dataPlugin).write(entries, { outDir: ctx.config.outDir });
+			ctx.log.debug("build:data", {
+				files: summary.fileCount,
+				bytes: summary.bytes
+			});
+		}
+	}
 	const root = rendered.find((page) => page.url === "/" || page.url === "");
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {
@@ -3729,6 +4521,37 @@ async function renderPages(ctx) {
 		rootHtml: root?.html ?? null
 	};
 }
+/**
+* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
+* preserving the nested directory structure. Skips silently (returns `null`) when
+* the source directory does not exist.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The copy result, or `null` when the public directory is absent.
+* @example
+* ```ts
+* const result = await copyPublic(ctx);
+* ```
+*/
+async function copyPublic(ctx) {
+	const from = ctx.config.publicDir ?? "public";
+	if (!(0, node_fs.existsSync)(from)) {
+		ctx.log.debug("build:public", {
+			skipped: true,
+			from
+		});
+		return null;
+	}
+	await (0, node_fs_promises.cp)(from, ctx.config.outDir, { recursive: true });
+	ctx.log.debug("build:public", {
+		from,
+		dest: ctx.config.outDir
+	});
+	return {
+		from: node_path$1.default.normalize(from),
+		copied: 1
+	};
+}
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -3832,6 +4655,9 @@ const PHASE_ORDER = [
 	"feeds",
 	"sitemap",
 	"og-images",
+	"public",
+	"not-found",
+	"locale-redirects",
 	"root-index"
 ];
 /**
@@ -3875,10 +4701,11 @@ function resetRun(ctx) {
 	ctx.state.runId = `${Date.now()}-${(0, node_crypto.randomUUID)()}`;
 }
 /**
-* Phase 4 — run feeds / sitemap / og-images concurrently, each gated by its config
-* flag, isolated with `Promise.allSettled` so one failure does not lose the others.
-* A disabled output is skipped entirely — it emits NO `build:phase` boundary (the
-* `withPhase` wrapper is gated on the config flag, not just the phase body).
+* Phase 4 — run feeds / sitemap / og-images / public / not-found / locale-redirects
+* concurrently, each gated by its config flag (or, for `public`, the presence of the
+* source dir), isolated with `Promise.allSettled` so one failure does not lose the
+* others. A disabled output is skipped entirely — it emits NO `build:phase` boundary
+* (the `withPhase` wrapper is gated on the config flag, not just the phase body).
 *
 * @param ctx - The phase context.
 * @example
@@ -3891,6 +4718,9 @@ async function runOutputs(ctx) {
 	if (ctx.config.feeds) tasks.push(withPhase(ctx, "feeds", () => generateFeeds(ctx)));
 	if (ctx.config.sitemap) tasks.push(withPhase(ctx, "sitemap", () => generateSitemap(ctx)));
 	if (ctx.config.ogImage) tasks.push(withPhase(ctx, "og-images", () => generateOgImages(ctx)));
+	if ((0, node_fs.existsSync)(ctx.config.publicDir ?? "public")) tasks.push(withPhase(ctx, "public", () => copyPublic(ctx)));
+	if (ctx.config.notFound) tasks.push(withPhase(ctx, "not-found", () => generateNotFound(ctx)));
+	if (ctx.config.localeRedirects) tasks.push(withPhase(ctx, "locale-redirects", () => generateLocaleRedirects(ctx)));
 	const settled = await Promise.allSettled(tasks);
 	for (const outcome of settled) if (outcome.status === "rejected") ctx.log.error("build:outputs", { reason: String(outcome.reason) });
 }
@@ -4033,6 +4863,9 @@ function validateFonts(og) {
 */
 function validateConfig$1(config) {
 	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$5}.outDir: must be a non-empty string.`);
+	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$5}.publicDir: must be a string when set.`);
+	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$5}.template: must be a string path when set.`);
+	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$5}.clientEntry: must be a string path when set.`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion
@@ -4086,6 +4919,27 @@ function createState$2(ctx) {
 * @file build — Complex plugin: SSG orchestrator (wiring harness only).
 * @see README.md
 */
+/**
+* Build plugin — the static-site-generation orchestrator. Renders every route to
+* `outDir`, and optionally emits feeds, a sitemap, optimized images, and OG
+* images. Depends on site, i18n, content, router, and head; emits `build:phase`.
+*
+* @example Configure the production build
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     build: {
+*       outDir: "dist",
+*       minify: true,
+*       feeds: true,
+*       sitemap: true,
+*       images: true,
+*       ogImage: false // or an object to enable + configure OG-image generation
+*     }
+*   }
+* });
+* ```
+*/
 const buildPlugin = createPlugin$1("build", {
 	depends: [
 		sitePlugin,
@@ -4885,6 +5739,24 @@ function createState$1(_ctx) {
 * Depends: site. Emits: deploy:complete.
 * @see README.md
 */
+/**
+* Deploy plugin — ships the built `outDir` to Cloudflare Pages via the injectable
+* wrangler subprocess, with entropy-gated secret scrubbing of logged output.
+* Depends on site; emits `deploy:complete`.
+*
+* @example Configure the deploy target
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     deploy: {
+*       target: "cloudflare-pages",
+*       outDir: "dist",
+*       productionBranch: "main"
+*     }
+*   }
+* });
+* ```
+*/
 const deployPlugin = createPlugin$1("deploy", {
 	config: defaultConfig,
 	depends: [sitePlugin],
@@ -4961,7 +5833,7 @@ function spaEvents(register) {
 }
 //#endregion
 //#region src/plugins/spa/types.ts
-var types_exports$7 = /* @__PURE__ */ __exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
+var types_exports$8 = /* @__PURE__ */ require_convention.__exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
 /** Allowed hook names — single source of truth for fail-fast validation. */
 const COMPONENT_HOOK_NAMES = [
 	"onCreate",
@@ -5431,11 +6303,12 @@ function resolveClickTarget(event) {
 * Navigation API is unavailable).
 *
 * @param handlers - The navigation lifecycle callbacks.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
 * @returns A teardown that removes the attached listeners.
 * @example
 * const dispose = attachHistoryFallback(handlers);
 */
-function attachHistoryFallback(handlers) {
+function attachHistoryFallback(handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
 	/**
 	* Intercept an internal-link click and run a History-API navigation.
 	*
@@ -5456,7 +6329,7 @@ function attachHistoryFallback(handlers) {
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		performNavigation(url.pathname, handlers).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -5465,7 +6338,7 @@ function attachHistoryFallback(handlers) {
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		performNavigation(location.pathname, handlers).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -5479,11 +6352,12 @@ function attachHistoryFallback(handlers) {
 *
 * @param navigation - The Navigation API object to attach the listener to.
 * @param handlers - The navigation lifecycle callbacks.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
 * @returns A teardown that removes the `navigate` listener.
 * @example
 * const dispose = attachNavigationApi(navigation, handlers);
 */
-function attachNavigationApi(navigation, handlers) {
+function attachNavigationApi(navigation, handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
 	/**
 	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
 	*
@@ -5508,7 +6382,7 @@ function attachNavigationApi(navigation, handlers) {
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await performNavigation(url.pathname, handlers);
+				await navigate(url.pathname);
 				if (navEvent.navigationType === "traverse") navEvent.scroll();
 				else window.scrollTo(0, 0);
 			}
@@ -5522,13 +6396,14 @@ function attachNavigationApi(navigation, handlers) {
 * fallback. Returns a teardown removing every listener it attached.
 *
 * @param handlers - The navigation lifecycle callbacks the kernel supplies.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
 * @returns A teardown removing all attached listeners.
 * @example
-* const dispose = attachRouter(handlers);
+* const dispose = attachRouter(handlers, navigate);
 */
-function attachRouter(handlers) {
+function attachRouter(handlers, navigate) {
 	const navigation = getNavigation();
-	return navigation ? attachNavigationApi(navigation, handlers) : attachHistoryFallback(handlers);
+	return navigation ? attachNavigationApi(navigation, handlers, navigate) : attachHistoryFallback(handlers, navigate);
 }
 //#endregion
 //#region src/plugins/spa/state.ts
@@ -5647,6 +6522,20 @@ function currentLocationUrl() {
 	return location.pathname + location.search;
 }
 /**
+* Apply the matched route's `head` config to the live document (minimal client
+* head-sync for the DATA path: title only — the full meta sync runs on the
+* HTML-over-fetch path from the fetched `<head>`).
+*
+* @param route - The matched route definition.
+* @param routeContext - The render context (params/data/locale).
+* @example
+* syncDataHead(hit.route, { params, data, locale });
+*/
+function syncDataHead(route, routeContext) {
+	const title = route._handlers.head?.(routeContext)?.title;
+	if (title !== void 0 && title !== "") document.title = title;
+}
+/**
 * Builds the single shared SPA kernel — a pure factory over state/config/emit.
 * Unit-testable with a mock state object and a spy emit; no Moku ctx involved.
 *
@@ -5710,6 +6599,71 @@ function createSpaKernel(state, config, emit, deps) {
 		onEnd: handleEnd,
 		onError: handleError
 	};
+	/**
+	* The client DATA path: match `pathname`, fetch the page's PERSISTED data via the
+	* `data` reader, VALIDATE it through the route's `parse` gate, then run the
+	* route's OWN `render` (the same component the build used for SSG) and
+	* Preact-render the VNode into the swap region. Returns `false` (touching nothing
+	* the fallback cares about) on no-match / no-render / no-data / fetch-miss /
+	* parse-throw, so the caller falls back to HTML-over-fetch. `route.load` does NOT
+	* run on the client — the build already persisted its output.
+	*
+	* @param pathname - The destination pathname (search stripped for matching).
+	* @returns `true` if the route was rendered from validated data, else `false`.
+	* @example
+	* if (await tryDataRender("/en/world/")) return;
+	*/
+	const tryDataRender = async (pathname) => {
+		if (!deps.dataAt) return false;
+		const matchPath = pathname.split("?")[0] ?? pathname;
+		const hit = deps.router.match(matchPath);
+		if (!hit?.route._handlers.render) return false;
+		try {
+			const raw = await deps.dataAt(pathname);
+			if (raw === null) return false;
+			const data = hit.route._handlers.parse ? hit.route._handlers.parse(raw) : raw;
+			const locale = hit.params.lang ?? document.documentElement.lang ?? "";
+			const routeContext = {
+				params: hit.params,
+				data,
+				locale
+			};
+			const vnode = hit.route._handlers.render(routeContext);
+			const region = document.querySelector(resolved.swapSelector);
+			if (!region) return false;
+			handleStart(pathname);
+			const { renderVNode } = await Promise.resolve().then(() => require("./render-BSTM0Akv.cjs"));
+			syncDataHead(hit.route, routeContext);
+			unmountPageSpecific(state, emit);
+			runSwap(() => {
+				region.replaceChildren();
+				renderVNode(vnode, region);
+				scanAndMount(state, emit, resolved.swapSelector);
+				notifyNavEnd(state);
+			}, resolved.viewTransitions);
+			state.currentUrl = pathname;
+			progress?.done();
+			emit("spa:navigated", { url: pathname });
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	/**
+	* Unified navigation: try the client DATA path first (only when the `data`
+	* plugin is composed), then fall back to HTML-over-fetch (which itself falls
+	* back to a full `location.href` reload). Injected into the router so every
+	* navigation entry point (Navigation API, History, programmatic) goes through it.
+	*
+	* @param pathname - The destination pathname.
+	* @returns A promise resolving once the swap (or fallback) is dispatched.
+	* @example
+	* await navigate("/en/world/");
+	*/
+	const navigate = async (pathname) => {
+		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
+		await performNavigation(pathname, handlers);
+	};
 	return {
 		/**
 		* Register config components and seed currentUrl from the document.
@@ -5732,7 +6686,7 @@ function createSpaKernel(state, config, emit, deps) {
 			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
 			progress = createProgressBar(resolved.progressBar);
 			state.currentUrl = currentLocationUrl();
-			state.destroyRouter = attachRouter(handlers);
+			state.destroyRouter = attachRouter(handlers, navigate);
 			scanAndMount(state, emit, resolved.swapSelector);
 			state.started = true;
 		},
@@ -5755,7 +6709,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*/
 		processNav(path) {
 			if (typeof document === "undefined") return;
-			performNavigation(path, handlers).catch(() => {});
+			navigate(path).catch(() => {});
 		},
 		/**
 		* Scan the swap region and mount components for matching elements.
@@ -5782,20 +6736,41 @@ function createSpaKernel(state, config, emit, deps) {
 	};
 }
 /**
+* Structural by-name handle for the OPTIONAL `data` plugin. `ctx.require` resolves
+* a plugin by its `name` at runtime, so this lets `spa` obtain the `data` reader
+* WITHOUT importing the `data` plugin or its types — keeping `spa` decoupled and
+* its `depends` at `[router, head]`. The phantom types only the `at` slice it uses.
+*/
+const dataPluginHandle = {
+	name: "data",
+	spec: void 0,
+	_phantom: {
+		config: void 0,
+		state: void 0,
+		api: void 0,
+		events: {}
+	}
+};
+/**
 * Builds the shared kernel from the plugin context, stores it on `ctx.state`
 * and `kernelRef`, and runs its init step (validate config, register
-* config.components, seed currentUrl). Extracted from index.ts onInit to keep
-* wiring under budget.
+* config.components, seed currentUrl). Captures the OPTIONAL `data` reader when
+* the `data` plugin is composed (enabling client DATA navigation).
 *
-* @param ctx - The plugin context (state/config/emit/require/log).
+* @param ctx - The plugin context (state/config/emit/require/has/log).
 * @example
 * initSpa(ctx);
 */
 function initSpa(ctx) {
-	const kernel = createSpaKernel(ctx.state, ctx.config, ctx.emit, {
+	const deps = {
 		router: ctx.require(routerPlugin),
 		head: ctx.require(headPlugin)
-	});
+	};
+	if (ctx.has("data")) {
+		const reader = ctx.require(dataPluginHandle);
+		deps.dataAt = (path) => reader.at(path);
+	}
+	const kernel = createSpaKernel(ctx.state, ctx.config, ctx.emit, deps);
 	ctx.state.kernel = kernel;
 	kernelRef.current = kernel;
 	kernel.init();
@@ -5857,6 +6832,26 @@ function disposeSpa() {
 * Emits: spa:navigate, spa:navigated, spa:component-mount, spa:component-unmount.
 * @see README.md
 */
+/**
+* SPA plugin — progressive client-side navigation layered over the static site:
+* swaps a page region on navigation, with an optional progress bar and View
+* Transitions. Register interactive islands with {@link createComponent}. Depends
+* on router and head; emits `spa:navigate`, `spa:navigated`, `spa:component-mount`,
+* and `spa:component-unmount`.
+*
+* @example Enable view transitions and a custom swap region
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     spa: {
+*       swapSelector: "main > section",
+*       viewTransitions: true,
+*       progressBar: true
+*     }
+*   }
+* });
+* ```
+*/
 const spaPlugin = createPlugin$1("spa", {
 	depends: [routerPlugin, headPlugin],
 	config: defaultSpaConfig,
@@ -5872,38 +6867,240 @@ const spaPlugin = createPlugin$1("spa", {
 });
 //#endregion
 //#region src/plugins/build/types.ts
-var types_exports = /* @__PURE__ */ __exportAll({});
+var types_exports = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/content/types.ts
-var types_exports$1 = /* @__PURE__ */ __exportAll({});
+var types_exports$1 = /* @__PURE__ */ require_convention.__exportAll({});
+//#endregion
+//#region src/plugins/data/types.ts
+var types_exports$2 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/deploy/types.ts
-var types_exports$2 = /* @__PURE__ */ __exportAll({});
+var types_exports$3 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/env/types.ts
-var types_exports$3 = /* @__PURE__ */ __exportAll({});
+var types_exports$4 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/head/types.ts
-var types_exports$4 = /* @__PURE__ */ __exportAll({});
+var types_exports$5 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/log/types.ts
-var types_exports$5 = /* @__PURE__ */ __exportAll({});
+var types_exports$6 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
 //#region src/plugins/router/types.ts
-var types_exports$6 = /* @__PURE__ */ __exportAll({});
-const { createApp, createPlugin } = createCore(coreConfig, {
+var types_exports$7 = /* @__PURE__ */ require_convention.__exportAll({});
+//#endregion
+//#region src/plugins/env/providers.ts
+/**
+* @file env plugin — built-in providers: dotenv, processEnv, cloudflareBindings.
+*/
+/** Default dotenv file path: optional local overrides. */
+const DEFAULT_DOTENV_PATH = ".env.local";
+/** Property on `globalThis` that the consumer sets per Cloudflare request. */
+const CLOUDFLARE_GLOBAL = "__CLOUDFLARE_ENV__";
+/**
+* Strips a single matching pair of surrounding double or single quotes from a
+* value. Leaves unquoted values (and trailing inline comments) untouched.
+*
+* @param value - The already-trimmed raw value.
+* @returns The value with one outer quote pair removed, if present.
+* @example
+* ```ts
+* stripQuotes('"a"'); // "a"
+* stripQuotes("plain # c"); // "plain # c"
+* ```
+*/
+function stripQuotes(value) {
+	if (value.length >= 2) {
+		const first = value[0];
+		const last = value.at(-1);
+		if ((first === "\"" || first === "'") && first === last) return value.slice(1, -1);
+	}
+	return value;
+}
+/**
+* Parses `.env`-style text into a flat record. Handles CRLF/LF, blank lines,
+* full-line `#` comments, first-`=` splitting, key/value trimming, and a single
+* outer quote pair. Does not strip trailing inline comments on unquoted values.
+*
+* @param text - The raw file contents.
+* @returns A flat record of parsed key/value pairs.
+* @example
+* ```ts
+* parseDotenv('A=1\nB="two"'); // { A: "1", B: "two" }
+* ```
+*/
+function parseDotenv(text) {
+	const out = {};
+	for (const line of text.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq === -1) continue;
+		const key = trimmed.slice(0, eq).trim();
+		out[key] = stripQuotes(trimmed.slice(eq + 1).trim());
+	}
+	return out;
+}
+/**
+* A zero-dependency `.env`-style provider that re-reads and re-parses the file
+* from disk on every `load()`. Missing file resolves to `{}` (optional
+* overrides). Strips a single outer quote pair; does not strip trailing inline
+* comments on unquoted values.
+*
+* @param path - Path to the dotenv file. Defaults to `.env.local`.
+* @returns An {@link EnvProvider} named `dotenv:<path>` that reads fresh per call.
+* @example
+* ```ts
+* const provider = dotenv(".env.local");
+* provider.load(); // { PUBLIC_API_URL: "/api", ... }
+* ```
+*/
+function dotenv(path = DEFAULT_DOTENV_PATH) {
+	return {
+		name: `dotenv:${path}`,
+		/**
+		* Reads and parses the dotenv file fresh from disk; `{}` if it is missing.
+		*
+		* @returns The parsed environment record, or `{}` when the file is absent.
+		* @example
+		* ```ts
+		* dotenv(".env.local").load();
+		* ```
+		*/
+		load() {
+			if (!(0, node_fs.existsSync)(path)) return {};
+			return parseDotenv((0, node_fs.readFileSync)(path, "utf8"));
+		}
+	};
+}
+/**
+* A provider that returns a shallow copy of `process.env` at `load()` time.
+*
+* @returns An {@link EnvProvider} named `process-env`.
+* @example
+* ```ts
+* const provider = processEnv();
+* provider.load().HOME; // current process value
+* ```
+*/
+function processEnv() {
+	return {
+		name: "process-env",
+		/**
+		* Returns a shallow copy of `process.env` at call time.
+		*
+		* @returns A fresh shallow copy of `process.env`.
+		* @example
+		* ```ts
+		* processEnv().load();
+		* ```
+		*/
+		load() {
+			return { ...process.env };
+		}
+	};
+}
+/**
+* A provider that reads live, per-request Cloudflare bindings from
+* `globalThis.__CLOUDFLARE_ENV__` at `load()` time (`?? {}` when absent). Never
+* caches the binding object; the consumer owns the global's request lifecycle.
+*
+* @returns An {@link EnvProvider} named `cloudflare`.
+* @example
+* ```ts
+* globalThis.__CLOUDFLARE_ENV__ = env; // set by the request handler
+* const provider = cloudflareBindings();
+* provider.load(); // reads the current request's bindings
+* ```
+*/
+function cloudflareBindings() {
+	return {
+		name: "cloudflare",
+		/**
+		* Reads `globalThis.__CLOUDFLARE_ENV__` fresh, never caching the bindings.
+		*
+		* @returns The current Cloudflare bindings, or `{}` when the global is unset.
+		* @example
+		* ```ts
+		* cloudflareBindings().load();
+		* ```
+		*/
+		load() {
+			return globalThis[CLOUDFLARE_GLOBAL] ?? {};
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @file `@moku-labs/web` — a Moku Layer-2 content static-site + SPA framework.
+*
+* `createApp`'s defaults are the **isomorphic** plugins that run unchanged on both
+* Node and the browser (`site`, `i18n`, `router`, `head`, `spa`, plus the
+* `log`/`env` core). The Node-only plugins (`content`, `build`, `deploy`,
+* `data`) are exported for Layer-3 composition: add them with
+* `createApp({ plugins: [...] })` in a Node build; omit them in a browser app.
+* The framework never hard-blocks either runtime — the consumer composes the
+* variant it needs and supplies the matching `env` provider.
+* @see README.md
+*/
+const framework = createCore(coreConfig, {
 	plugins: [
 		sitePlugin,
 		i18nPlugin,
 		routerPlugin,
-		contentPlugin,
 		headPlugin,
-		buildPlugin,
-		spaPlugin,
-		deployPlugin
+		spaPlugin
 	],
 	pluginConfigs: {}
 });
+/**
+* Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
+* Your overrides are merged over the framework defaults through the 4-level config
+* cascade, every plugin's lifecycle runs, and a fully-typed, frozen app is returned.
+*
+* The defaults are the isomorphic plugin set (`site`, `i18n`, `router`, `head`,
+* `spa` + `log`/`env` core). Add the Node-only plugins for an SSG build:
+* `createApp({ plugins: [contentPlugin, buildPlugin, deployPlugin] })`.
+*
+* @param options - Optional configuration:
+*  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
+*  - `config` — global framework config (e.g. `{ mode: "development" }`).
+*  - `plugins` — extra plugins (Node-only built-ins or your own) merged into the app and its type.
+*  - `onReady` / `onError` / `onStart` / `onStop` — lifecycle callbacks.
+* @returns The initialized app: `start()`, `stop()`, every plugin's API, and `log`.
+* @example
+* ```ts
+* // Node SSG build — add the node-only plugins:
+* const app = createApp({
+*   plugins: [contentPlugin, buildPlugin, deployPlugin],
+*   pluginConfigs: {
+*     site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes" },
+*     router: { routes: defineRoutes({ home: route("/"), post: route("/blog/{slug}/") }) }
+*   }
+* });
+* await app.start();
+* await app.build.run();
+* ```
+*/
+const createApp = framework.createApp;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and core
+* APIs. Plugin types are inferred from the spec object — never written explicitly.
+* Pass the result to {@link createApp} via `plugins`.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+*
+* const app = createApp({ plugins: [analytics] });
+* ```
+*/
+const createPlugin = framework.createPlugin;
 //#endregion
 Object.defineProperty(exports, "Build", {
 	enumerable: true,
@@ -5917,50 +7114,60 @@ Object.defineProperty(exports, "Content", {
 		return types_exports$1;
 	}
 });
-Object.defineProperty(exports, "Deploy", {
+Object.defineProperty(exports, "Data", {
 	enumerable: true,
 	get: function() {
 		return types_exports$2;
 	}
 });
-Object.defineProperty(exports, "Env", {
+Object.defineProperty(exports, "Deploy", {
 	enumerable: true,
 	get: function() {
 		return types_exports$3;
 	}
 });
-Object.defineProperty(exports, "Head", {
+Object.defineProperty(exports, "Env", {
 	enumerable: true,
 	get: function() {
 		return types_exports$4;
 	}
 });
-Object.defineProperty(exports, "Log", {
+Object.defineProperty(exports, "Head", {
 	enumerable: true,
 	get: function() {
 		return types_exports$5;
 	}
 });
-Object.defineProperty(exports, "Router", {
+Object.defineProperty(exports, "Log", {
 	enumerable: true,
 	get: function() {
 		return types_exports$6;
 	}
 });
-Object.defineProperty(exports, "Spa", {
+Object.defineProperty(exports, "Router", {
 	enumerable: true,
 	get: function() {
 		return types_exports$7;
 	}
 });
+Object.defineProperty(exports, "Spa", {
+	enumerable: true,
+	get: function() {
+		return types_exports$8;
+	}
+});
+exports.browserEnv = browserEnv;
 exports.buildArticleHead = buildArticleHead;
 exports.buildPlugin = buildPlugin;
 exports.canonical = canonical;
+exports.cloudflareBindings = cloudflareBindings;
 exports.contentPlugin = contentPlugin;
 exports.createApp = createApp;
 exports.createPlugin = createPlugin;
+exports.dataPlugin = dataPlugin;
 exports.defineRoutes = defineRoutes;
 exports.deployPlugin = deployPlugin;
+exports.dotenv = dotenv;
 exports.envPlugin = envPlugin;
 exports.feedLink = feedLink;
 exports.headPlugin = headPlugin;
@@ -5970,6 +7177,7 @@ exports.jsonLd = jsonLd;
 exports.logPlugin = logPlugin;
 exports.meta = meta;
 exports.og = og;
+exports.processEnv = processEnv;
 exports.route = route;
 exports.routerPlugin = routerPlugin;
 exports.sitePlugin = sitePlugin;