@moku-labs/web 0.5.6 → 1.0.0

package/dist/browser.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
-import { t as dataSuffix } from "./convention-X3zLTlJ8.mjs";
+import { n as relativeDataFile, t as dataSuffix } from "./convention-CepUwWmT.mjs";
 import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
@@ -115,6 +115,12 @@ function createEnvState() {
 const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
 /** Error prefix for all resolution-pipeline failures. */
 const ERROR_PREFIX$9 = "[web]";
+/** The `Map` mutators redefined as throwers when a map is frozen. */
+const FROZEN_METHODS = [
+	"set",
+	"clear",
+	"delete"
+];
 /**
 * Throws the canonical frozen-map error; installed as a map's `set`/`clear`/`delete`.
 *
@@ -128,6 +134,21 @@ function frozenThrower() {
 	throw new TypeError(FROZEN_MESSAGE);
 }
 /**
+* Coerces a raw provider value to its effective presence: an empty string counts
+* as "absent" so a `KEY=""` falls through to later providers.
+*
+* @param raw - The raw value a provider supplied for a key (possibly `undefined`).
+* @returns The value, or `undefined` when it is missing or an empty string.
+* @example
+* ```ts
+* coerceEmpty(""); // => undefined
+* coerceEmpty("3000"); // => "3000"
+* ```
+*/
+function coerceEmpty(raw) {
+	return raw === "" ? void 0 : raw;
+}
+/**
 * Merges providers in array order, coercing empty strings to `undefined` before
 * precedence so a `KEY=""` falls through to later providers. First non-empty
 * value wins.
@@ -139,14 +160,11 @@ function frozenThrower() {
 * mergeProviders({ providers: [a, b], schema: {}, publicPrefix: "PUBLIC_" });
 * ```
 */
-function mergeProviders(config) {
+function mergeProviders$1(config) {
 	const merged = {};
-	for (const provider of config.providers) {
-		const values = provider.load();
-		for (const [key, raw] of Object.entries(values)) {
-			const value = raw === "" ? void 0 : raw;
-			if (value !== void 0 && merged[key] === void 0) merged[key] = value;
-		}
+	for (const provider of config.providers) for (const [key, raw] of Object.entries(provider.load())) {
+		const value = coerceEmpty(raw);
+		if (value !== void 0 && merged[key] === void 0) merged[key] = value;
 	}
 	return merged;
 }
@@ -181,11 +199,7 @@ function crossCheckPublicPrefix(config) {
 * ```
 */
 function freezeMap(map) {
-	for (const method of [
-		"set",
-		"clear",
-		"delete"
-	]) Object.defineProperty(map, method, {
+	for (const method of FROZEN_METHODS) Object.defineProperty(map, method, {
 		value: frozenThrower,
 		writable: false,
 		configurable: false,
@@ -194,6 +208,41 @@ function freezeMap(map) {
 	Object.freeze(map);
 }
 /**
+* Populates `state.publicMap` with the schema-driven public subset: every
+* `public:true` schema key that resolved to a defined value. This map is the only
+* sanctioned input to a browser-facing `define`, so it stays schema-scoped (never
+* includes non-schema provider keys).
+*
+* @param schema - The per-variable schema from {@link EnvConfig}.
+* @param merged - The merged provider values keyed by variable name.
+* @param publicMap - The mutable public map to fill in place.
+* @example
+* ```ts
+* populatePublicMap(config.schema, merged, state.publicMap);
+* ```
+*/
+function populatePublicMap(schema, merged, publicMap) {
+	for (const [key, spec] of Object.entries(schema)) {
+		const value = merged[key];
+		if (spec.public === true && value !== void 0) publicMap.set(key, value);
+	}
+}
+/**
+* Populates `state.resolved` with EVERY merged key that carries a defined value
+* (spec/02 Lifecycle §5), including non-schema provider keys so
+* `ctx.env.require()` works for dynamic keys.
+*
+* @param merged - The merged provider values keyed by variable name.
+* @param resolved - The mutable resolved map to fill in place.
+* @example
+* ```ts
+* populateResolved(merged, state.resolved);
+* ```
+*/
+function populateResolved(merged, resolved) {
+	for (const [key, value] of Object.entries(merged)) resolved.set(key, value);
+}
+/**
 * Resolves, validates, and freezes the environment table at `onInit`.
 *
 * Pipeline order: merge providers (with empty-string → undefined coercion) →
@@ -213,17 +262,14 @@ function freezeMap(map) {
 function validateSchema(ctx) {
 	const { config, state } = ctx;
 	const { schema } = config;
-	const merged = mergeProviders(config);
+	const merged = mergeProviders$1(config);
 	crossCheckPublicPrefix(config);
 	for (const [key, spec] of Object.entries(schema)) {
 		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
 		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$9} env: required variable "${key}" is not defined by any provider or default.`);
 	}
-	for (const [key, spec] of Object.entries(schema)) {
-		const value = merged[key];
-		if (spec.public === true && value !== void 0) state.publicMap.set(key, value);
-	}
-	for (const [key, value] of Object.entries(merged)) state.resolved.set(key, value);
+	populatePublicMap(schema, merged, state.publicMap);
+	populateResolved(merged, state.resolved);
 	freezeMap(state.resolved);
 	freezeMap(state.publicMap);
 }
@@ -325,7 +371,7 @@ var LogExpectAssertionError = class extends Error {
 * isPlainObject([1]); // false
 * ```
 */
-function isPlainObject(value) {
+function isPlainObject$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
@@ -351,8 +397,8 @@ function matchesPartial(actual, partial) {
 		if (!Array.isArray(actual) || actual.length !== partial.length) return false;
 		return partial.every((value, index) => matchesPartial(actual[index], value));
 	}
-	if (isPlainObject(partial)) {
-		if (!isPlainObject(actual)) return false;
+	if (isPlainObject$1(partial)) {
+		if (!isPlainObject$1(actual)) return false;
 		return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
 	}
 	return false;
@@ -387,6 +433,22 @@ function describePartial(partial) {
 	return partial === void 0 ? "" : ` matching ${JSON.stringify(partial)}`;
 }
 /**
+* Find the first entry with `event` at or after `startIndex`, scanning forward.
+*
+* @param entries - The trace array to scan.
+* @param event - Event name to find.
+* @param startIndex - Index to begin scanning from (inclusive).
+* @returns The index of the first match, or `-1` when none exists from `startIndex` on.
+* @example
+* ```ts
+* findEventAtOrAfter([{ event: "a" }, { event: "b" }] as LogEntry[], "b", 0); // 1
+* ```
+*/
+function findEventAtOrAfter(entries, event, startIndex) {
+	for (let index = startIndex; index < entries.length; index++) if (entries[index]?.event === event) return index;
+	return -1;
+}
+/**
 * Create a fluent assertion chain bound to the live `entries` array. Each method
 * reads `entries` at call time, so assertions reflect later logging.
 *
@@ -429,13 +491,9 @@ function createExpectChain(entries) {
 		toHaveEventInOrder(events) {
 			let cursor = 0;
 			for (const [position, event] of events.entries()) {
-				let nextIndex = -1;
-				for (let index = cursor; index < entries.length; index++) if (entries[index]?.event === event) {
-					nextIndex = index;
-					break;
-				}
-				if (nextIndex === -1) throw new LogExpectAssertionError(`Expected events in order ${JSON.stringify(events)}, but "${event}" (index ${position}) was not found at or after position ${cursor}.`);
-				cursor = nextIndex + 1;
+				const matchIndex = findEventAtOrAfter(entries, event, cursor);
+				if (matchIndex === -1) throw new LogExpectAssertionError(`Expected events in order ${JSON.stringify(events)}, but "${event}" (index ${position}) was not found at or after position ${cursor}.`);
+				cursor = matchIndex + 1;
 			}
 			return chain;
 		},
@@ -491,13 +549,28 @@ function append(state, level, event, data) {
 	for (const sink of state.sinks) sink.write(entry);
 }
 /**
-* Merge an `Error`'s `message`/`stack` into `data` under an `error` key,
-* preserving existing keys. Non-object `data` is coerced to `{}` first so a
-* thrown error is never silently dropped.
+* Tests whether a value is a non-null, non-array plain object.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a non-null object that is not an array.
+* @example
+* ```ts
+* isPlainObject({ a: 1 }); // true
+* isPlainObject([1]); // false
+* ```
+*/
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Merge an `Error`'s `message`/`stack` into `data` under an `error` key. The
+* `error` field is always preserved; only a plain object `data` contributes its
+* keys. Non-plain-object `data` (arrays and primitives) is replaced by `{}` —
+* its original value is not retained — so the merge target is always a record.
 *
 * @param data - Original payload (any shape).
 * @param error - The originating error to merge.
-* @returns A new object carrying the original keys plus the `error` field.
+* @returns A new object carrying any plain-object keys plus the `error` field.
 * @example
 * ```ts
 * mergeError({ target: "cf" }, new Error("boom"));
@@ -506,7 +579,7 @@ function append(state, level, event, data) {
 */
 function mergeError(data, error) {
 	return {
-		...typeof data === "object" && data !== null && !Array.isArray(data) ? data : {},
+		...isPlainObject(data) ? data : {},
 		error: {
 			message: error.message,
 			stack: error.stack
@@ -730,8 +803,22 @@ const logPlugin = createCorePlugin("log", {
 * @file Framework configuration — Config + Events types, core plugin registration.
 * @see README.md
 */
+/**
+* Step 1 of the factory chain — captures the framework's `Config`/`Events` contract
+* and registers the core plugins (`log`, `env`) whose APIs are injected onto every
+* regular plugin's context. Consumers never use this directly; it backs the exported
+* {@link createPlugin} and {@link createCore}.
+*
+* @example
+* ```ts
+* const { createPlugin, createCore } = coreConfig;
+* ```
+*/
 const coreConfig = createCoreConfig("web", {
-	config: { mode: "production" },
+	config: {
+		stage: "production",
+		mode: "hybrid"
+	},
 	plugins: [logPlugin, envPlugin],
 	pluginConfigs: { log: { mode: "production" } }
 });
@@ -917,6 +1004,40 @@ const i18nPlugin = createPlugin$1("i18n", {
 //#region src/plugins/site/api.ts
 /** Error prefix for all site lifecycle/validation failures. */
 const ERROR_PREFIX$7 = "[web]";
+/** URL protocols that qualify a parsed URL as an absolute http/https URL. */
+const HTTP_PROTOCOLS = new Set(["http:", "https:"]);
+/**
+* Strips every trailing "/" from a value, so it can own the single slash that a
+* join boundary inserts.
+*
+* @param value - The string to trim (e.g. an absolute base URL).
+* @returns The value with all trailing slashes removed.
+* @example
+* ```ts
+* trimTrailingSlashes("https://blog.dev//"); // "https://blog.dev"
+* ```
+*/
+function trimTrailingSlashes(value) {
+	let trimmed = value;
+	while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+	return trimmed;
+}
+/**
+* Strips every leading "/" from a value, so the join boundary is the only slash
+* separating it from the base.
+*
+* @param value - The string to trim (e.g. a relative path).
+* @returns The value with all leading slashes removed.
+* @example
+* ```ts
+* trimLeadingSlashes("//about/"); // "about/"
+* ```
+*/
+function trimLeadingSlashes(value) {
+	let trimmed = value;
+	while (trimmed.startsWith("/")) trimmed = trimmed.slice(1);
+	return trimmed;
+}
 /**
 * Joins a relative path against an absolute base URL, normalizing the slash
 * boundary to exactly one "/". Returns the base unchanged for an empty or
@@ -931,12 +1052,9 @@ const ERROR_PREFIX$7 = "[web]";
 * ```
 */
 function joinCanonical(base, path) {
-	let trimmedBase = base;
-	while (trimmedBase.endsWith("/")) trimmedBase = trimmedBase.slice(0, -1);
+	const trimmedBase = trimTrailingSlashes(base);
 	if (path === "" || path === "/") return trimmedBase;
-	let trimmedPath = path;
-	while (trimmedPath.startsWith("/")) trimmedPath = trimmedPath.slice(1);
-	return `${trimmedBase}/${trimmedPath}`;
+	return `${trimmedBase}/${trimLeadingSlashes(path)}`;
 }
 /**
 * Validates that a string is a non-empty trimmed value.
@@ -964,7 +1082,7 @@ function isNonEmpty(value) {
 function isAbsoluteUrl(value) {
 	try {
 		const parsed = new URL(value);
-		return parsed.protocol === "http:" || parsed.protocol === "https:";
+		return HTTP_PROTOCOLS.has(parsed.protocol);
 	} catch {
 		return false;
 	}
@@ -1098,19 +1216,86 @@ const sitePlugin = createPlugin$1("site", {
 	api: createSiteApi
 });
 //#endregion
-//#region src/plugins/router/builders/match.ts
+//#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(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(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);
+}
 /**
-* Extract named groups from a `URLPattern` match result, stripping numeric/regex
-* group keys so only declared param names remain.
+* Extract named groups from a `URLPattern` match result, dropping numeric/regex
+* group keys and `undefined` values so only declared, present params remain.
 *
 * @param groups - The `URLPatternResult.pathname.groups` object.
-* @returns A clean record of named params (numeric keys + undefined values dropped).
+* @returns A clean record of named params.
 * @example
 * ```ts
-* extractParams({ slug: "hello", "0": "x" }); // { slug: "hello" }
+* extractGroups({ slug: "hello", "0": "x" }); // { slug: "hello" }
 * ```
 */
-function extractParams(groups) {
+function extractGroups(groups) {
 	const params = {};
 	for (const [key, value] of Object.entries(groups)) {
 		if (/^\d+$/.test(key)) continue;
@@ -1118,6 +1303,15 @@ function extractParams(groups) {
 	}
 	return params;
 }
+//#endregion
+//#region src/plugins/router/builders/match.ts
+/**
+* @file router plugin — runtime matching domain.
+*
+* Pure functions that turn compiled patterns into a pathname matcher: build the
+* lang-aware/bare `URLPattern` pair, the `matchFn` (withLang first, bare fallback
+* injecting `defaultLocale`), and extract/strip params. No `ctx` here.
+*/
 /**
 * Build a pathname matcher for a single route: tries the `withLang` URLPattern,
 * then the `bare` pattern injecting `defaultLocale` on miss.
@@ -1135,10 +1329,10 @@ function extractParams(groups) {
 function createMatchFunction(matchers, defaultLocale) {
 	return (pathname) => {
 		const withLang = matchers.withLang.exec({ pathname });
-		if (withLang) return extractParams(withLang.pathname.groups);
+		if (withLang) return extractGroups(withLang.pathname.groups);
 		const bare = matchers.bare.exec({ pathname });
 		if (bare) {
-			const params = extractParams(bare.pathname.groups);
+			const params = extractGroups(bare.pathname.groups);
 			params.lang = defaultLocale;
 			return params;
 		}
@@ -1167,294 +1361,84 @@ function matchRoute(compiled, pathname) {
 	return null;
 }
 //#endregion
-//#region src/plugins/router/api.ts
+//#region src/plugins/router/builders/compile.ts
 /**
-* @file router plugin — API factory.
+* @file router plugin — compilation + validation domain.
 *
-* Closures over `ctx.state.table` exposing `match` / `toUrl` / `entries` /
-* `manifest`. Returns values/copies, never the raw `ctx.state` reference (spec/11 §2.4).
+* 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.
 */
-/** Error prefix for router API failures. */
+/** Shared `[web]` error prefix for router validation failures. */
 const ERROR_PREFIX$6 = "[web] router";
+/** Maximum number of optional `{lang:?}` segments a single pattern may declare. */
+const MAX_LANG_SEGMENTS = 1;
 /**
-* Read the compiled matcher table, throwing if `onInit` has not run yet. This
-* `null` cannot occur in practice post-`onInit`; the guard documents the invariant.
+* Whether a pattern is rooted — every route pattern must be absolute (start
+* with `/`) so it composes cleanly with the locale prefix and base URL.
 *
-* @param state - The router plugin state holder.
-* @returns The compiled, non-null matcher table.
-* @throws {Error} If the matcher table has not been compiled yet.
+* @param pattern - The user pattern to check.
+* @returns `true` when the pattern starts with `/`.
 * @example
 * ```ts
-* const table = readTable(ctx.state);
+* isPatternRooted("/{slug}/"); // true
 * ```
 */
-function readTable(state) {
-	if (state.table === null) throw new Error(`${ERROR_PREFIX$6}: matcher table accessed before onInit compiled it.`);
-	return state.table;
+function isPatternRooted(pattern) {
+	return pattern.startsWith("/");
 }
 /**
-* Project a compiled route into the public `TypedRoute` URL-utility view.
+* Whether a pattern's `{` and `}` braces are balanced — every placeholder must
+* be closed so segment parsing cannot drift.
 *
-* @param entry - The compiled route entry.
-* @returns A `TypedRoute` exposing pattern/name/meta + toUrl/toFile/match.
+* @param pattern - The user pattern to check.
+* @returns `true` when open and close brace counts are equal.
 * @example
 * ```ts
-* toTypedRoute(compiledEntry).toUrl({ slug: "x" });
+* hasBalancedBraces("/{slug}/"); // true
 * ```
 */
-function toTypedRoute(entry) {
-	return {
-		pattern: entry.pattern,
-		name: entry.name,
-		meta: { ...entry.meta },
-		toUrl: entry.toUrl,
-		toFile: entry.toFile,
-		match: entry.matchFn
-	};
+function hasBalancedBraces(pattern) {
+	return (pattern.match(/\{/g) ?? []).length === (pattern.match(/\}/g) ?? []).length;
 }
 /**
-* Project a compiled route into the serializable {@link ClientRoute} view: only
-* `pattern` / `name` / `meta`, with a fresh `meta` copy and NO `_handlers` closures.
+* Whether a pattern declares at most one optional `{lang:?}` segment — the
+* locale prefix is single-slot, so a second occurrence is ambiguous.
 *
-* @param entry - The compiled route entry.
-* @returns A `ClientRoute` carrying only JSON-serializable fields.
+* @param pattern - The user pattern to check.
+* @returns `true` when the pattern has zero or one `{lang:?}` segments.
 * @example
 * ```ts
-* toClientRoute(compiledEntry); // { pattern, name, meta }
+* hasValidLangCount("/{lang:?}/{slug}/"); // true
 * ```
 */
-function toClientRoute(entry) {
-	return {
-		pattern: entry.pattern,
-		name: entry.name,
-		meta: { ...entry.meta }
-	};
+function hasValidLangCount(pattern) {
+	return (pattern.match(/\{lang:\?\}/g) ?? []).length <= MAX_LANG_SEGMENTS;
 }
 /**
-* 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.
+* Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
+* naming the offending route/pattern on any failure: empty map, a pattern not
+* starting with `/`, unbalanced `{…}` braces, or more than one `{lang:?}` segment.
 *
-* @param ctx - Plugin context.
-* @param ctx.state - The router state holding the compiled matcher table.
-* @returns The {@link RouterApi} surface mounted at `ctx.router`.
+* @param routes - The route map registered via `pluginConfigs.router.routes`.
+* @throws {Error} If routes are empty or a pattern is malformed.
 * @example
 * ```ts
-* const api = createApi({ state });
-* api.match("/en/hello/");
-* ```
-*/
-function createApi$2(ctx) {
-	const { state } = ctx;
-	return {
-		/**
-		* Match a pathname against the compiled route table (specificity-sorted).
-		*
-		* @param pathname - URL pathname, e.g. `/en/hello/`.
-		* @returns `{ params, route }` for the most specific match, or `null`.
-		* @example
-		* ```ts
-		* api.match("/en/hello/");
-		* ```
-		*/
-		match(pathname) {
-			return matchRoute(readTable(state).compiled, pathname);
-		},
-		/**
-		* Build a URL for a named route from params.
-		*
-		* @param routeName - Route name key from the route map.
-		* @param params - Param values to substitute into the pattern.
-		* @returns The resolved URL string (e.g. `/en/hello/`).
-		* @throws {Error} If `routeName` is unknown.
-		* @example
-		* ```ts
-		* api.toUrl("article", { lang: "en", slug: "hello" });
-		* ```
-		*/
-		toUrl(routeName, params) {
-			const entry = readTable(state).byName.get(routeName);
-			if (!entry) throw new Error(`${ERROR_PREFIX$6}: unknown route name "${routeName}".`);
-			return entry.toUrl(params);
-		},
-		/**
-		* All resolved routes as typed URL utilities, in specificity order.
-		*
-		* @returns A fresh read-only array of resolved typed routes.
-		* @example
-		* ```ts
-		* for (const r of api.entries()) r.toUrl({ slug: "x" });
-		* ```
-		*/
-		entries() {
-			return readTable(state).compiled.map((entry) => toTypedRoute(entry));
-		},
-		/**
-		* The typed route set for build-time consumption (declaration order). An API
-		* return, NOT a config readback — preserves per-route types despite erasure.
-		*
-		* @returns A fresh read-only array of the typed route definitions.
-		* @example
-		* ```ts
-		* for (const def of api.manifest()) def._handlers.load?.({}, "en");
-		* ```
-		*/
-		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$5 = "[web] router";
-/**
-* Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
-* naming the offending route/pattern on any failure: empty map, a pattern not
-* starting with `/`, unbalanced `{…}` braces, or more than one `{lang:?}` segment.
-*
-* @param routes - The route map from config.
-* @throws {Error} If routes are empty, a pattern is malformed, or names collide.
-* @example
-* ```ts
-* validateRoutes({ home: route("/") });
+* validateRoutes({ home: route("/") });
 * ```
 */
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
-	if (names.length === 0) throw new Error(`${ERROR_PREFIX$5}: route map is empty — provide at least one route via pluginConfigs.router.routes.`);
+	if (names.length === 0) throw new Error(`${ERROR_PREFIX$6}: route map is empty.\n  Register at least one route via pluginConfigs.router.routes.`);
 	for (const name of names) {
 		const pattern = routes[name]?.pattern ?? "";
-		if (!pattern.startsWith("/")) throw new Error(`${ERROR_PREFIX$5}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-		if ((pattern.match(/\{/g) ?? []).length !== (pattern.match(/\}/g) ?? []).length) throw new Error(`${ERROR_PREFIX$5}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-		if ((pattern.match(/\{lang:\?\}/g) ?? []).length > 1) throw new Error(`${ERROR_PREFIX$5}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+		if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+		if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+		if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$6}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
 	}
 }
 /**
-* Parse a single path segment into its placeholder, or `false` for a static
-* segment. Uses a plain loop over the brace delimiters (no backtracking regex).
-*
-* @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(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
-	};
-}
-/**
 * Convert a user pattern to a `URLPattern` source string, in a `withLang` or
 * `bare` variant (the latter strips the optional `{lang:?}` segment). Walks the
 * pattern one `/`-segment at a time (no backtracking regex).
@@ -1486,22 +1470,29 @@ function patternToUrlPattern(pattern, variant, langRegex) {
 }
 /**
 * Build a URL from a pattern and params (substitutes `{param}` / `{param:?}`).
-* Walks segment-by-segment (no backtracking regex).
+* Walks segment-by-segment (no backtracking regex). An optional placeholder whose
+* param is absent has its segment skipped entirely (no empty segment), so a missing
+* `{lang:?}` collapses cleanly instead of leaving a double slash.
 *
 * @param pattern - The route pattern.
 * @param params - Param values to substitute.
-* @param _baseUrl - Site base URL (reserved for absolute-link construction).
 * @returns The resolved relative URL string.
 * @example
 * ```ts
-* buildUrl("/{slug}/", { slug: "hello" }, "https://blog.dev");
+* buildUrl("/{slug}/", { slug: "hello" }); // "/hello/"
 * ```
 */
-function buildUrl(pattern, params, _baseUrl) {
+function buildUrl(pattern, params) {
 	const out = [];
 	for (const segment of pattern.split("/")) {
 		const placeholder = parsePlaceholder(segment);
-		out.push(placeholder ? params[placeholder.name] ?? "" : segment);
+		if (!placeholder) {
+			out.push(segment);
+			continue;
+		}
+		const value = params[placeholder.name] ?? "";
+		if (placeholder.optional && value === "") continue;
+		out.push(value);
 	}
 	return out.join("/");
 }
@@ -1517,10 +1508,63 @@ function buildUrl(pattern, params, _baseUrl) {
 * ```
 */
 function buildFilePath(pattern, params) {
-	const cleanPath = buildUrl(pattern, params, "").replace(/^\//, "").replace(/\/$/, "");
+	const cleanPath = buildUrl(pattern, params).replace(/^\//, "").replace(/\/$/, "");
 	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
 }
 /**
+* Build both URLPattern matchers for a route — the `withLang` variant (locale
+* prefix injected) and the `bare` variant (optional `{lang:?}` stripped) — from
+* the user pattern and the active locale alternation.
+*
+* @param pattern - The user pattern, e.g. `/{lang:?}/{slug}/`.
+* @param locales - Active locale codes, joined into the alternation regex.
+* @returns The frozen `{ withLang, bare }` matcher pair.
+* @example
+* ```ts
+* const matchers = buildMatchers("/{lang:?}/{slug}/", ["en", "uk"]);
+* ```
+*/
+function buildMatchers(pattern, locales) {
+	const langRegex = `(${locales.join("|")})`;
+	return {
+		withLang: new URLPattern({ pathname: patternToUrlPattern(pattern, "withLang", langRegex) }),
+		bare: new URLPattern({ pathname: patternToUrlPattern(pattern, "bare", langRegex) })
+	};
+}
+/**
+* Build the `toUrl` closure for a route — resolves the pattern against params
+* into a relative URL. Captured per-route so callers need not re-supply the
+* pattern.
+*
+* @param pattern - The route pattern bound into the closure.
+* @returns A function mapping params to the resolved relative URL.
+* @example
+* ```ts
+* const toUrl = createToUrlFn("/{slug}/");
+* toUrl({ slug: "x" }); // "/x/"
+* ```
+*/
+function createToUrlFunction(pattern) {
+	return (params) => buildUrl(pattern, params);
+}
+/**
+* Build the `toFile` closure for a route — resolves the output file path from
+* params. Honors a custom `.toFile()` override (captured in `_handlers.toFile`)
+* when present, falling back to the pattern-derived `…/index.html` path.
+*
+* @param pattern - The route pattern bound into the closure.
+* @param definition - The route definition carrying any `toFile` override.
+* @returns A function mapping params to the output file path.
+* @example
+* ```ts
+* const toFile = createToFileFn("/{slug}/", definition);
+* toFile({ slug: "x" }); // "x/index.html"
+* ```
+*/
+function createToFileFunction(pattern, definition) {
+	return (params) => definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
+}
+/**
 * Compile a single route definition into its `CompiledRoute` entry.
 *
 * @param name - The route name key.
@@ -1534,45 +1578,17 @@ function buildFilePath(pattern, params) {
 */
 function compileRoute(name, definition, input) {
 	const { pattern } = definition;
-	const langRegex = `(${input.locales.join("|")})`;
-	const matchers = {
-		withLang: new URLPattern({ pathname: patternToUrlPattern(pattern, "withLang", langRegex) }),
-		bare: new URLPattern({ pathname: patternToUrlPattern(pattern, "bare", langRegex) })
-	};
+	const matchers = buildMatchers(pattern, input.locales);
+	const toUrl = createToUrlFunction(pattern);
+	const toFile = createToFileFunction(pattern, definition);
 	return {
 		name,
 		pattern,
 		dynamicSegmentCount: dynamicSegmentCount(pattern),
 		matchers,
 		matchFn: createMatchFunction(matchers, input.defaultLocale),
-		/**
-		* Build a URL for this route from params.
-		*
-		* @param params - Param values to substitute.
-		* @returns The resolved relative URL.
-		* @example
-		* ```ts
-		* entry.toUrl({ slug: "x" });
-		* ```
-		*/
-		toUrl(params) {
-			return buildUrl(pattern, params, input.baseUrl);
-		},
-		/**
-		* Build the output file path for this route from params. Honors a custom
-		* `.toFile()` override (captured in `_handlers.toFile`) when present, falling
-		* back to the pattern-derived `…/index.html` path otherwise.
-		*
-		* @param params - Param values to substitute.
-		* @returns The output file path.
-		* @example
-		* ```ts
-		* entry.toFile({ slug: "x" });
-		* ```
-		*/
-		toFile(params) {
-			return definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
-		},
+		toUrl,
+		toFile,
 		definition,
 		meta: { ...definition._meta }
 	};
@@ -1603,75 +1619,212 @@ function compileRoutes(input) {
 		byName
 	};
 }
+//#endregion
+//#region src/plugins/router/api.ts
+/**
+* @file router plugin — API factory.
+*
+* Closures over `ctx.state.table` exposing `match` / `toUrl` / `entries` /
+* `manifest`. Returns values/copies, never the raw `ctx.state` reference (spec/11 §2.4).
+*/
+/** Error prefix for router API failures. */
+const ERROR_PREFIX$5 = "[web] router";
 /**
-* onInit orchestrator (data-only seam, keeps `index.ts` wiring-only). Validates
-* the route map then compiles the matcher table from resolved dependency data.
+* Validate a route map and compile it into the matcher table on `ctx.state`,
+* resolving the global render `mode` + site base URL + i18n locales at call time.
+* Called by the router's `onInit` to compile `config.routes`. Re-calling replaces the table.
 *
-* @param config - Resolved router config (`routes` + `mode`).
-* @param baseUrl - Site base URL from `ctx.require(sitePlugin).url()`.
-* @param locales - Available locales from `ctx.require(i18nPlugin).locales()`.
-* @param defaultLocale - Default locale from `ctx.require(i18nPlugin).defaultLocale()`.
-* @returns The compiled, immutable matcher table for `ctx.state.table`.
+* @param ctx - The router register context (state + global mode + require).
+* @param routes - The route map to compile (an `import * as routes` namespace works).
+* @throws {Error} If the route map is empty or a pattern is malformed.
 * @example
 * ```ts
-* ctx.state.table = buildRouterTable(ctx.config, site.url(), i18n.locales(), i18n.defaultLocale());
+* registerRoutes(ctx, { home: route("/") });
 * ```
 */
-function buildRouterTable(config, baseUrl, locales, defaultLocale) {
-	validateRoutes(config.routes);
-	return compileRoutes({
-		routes: config.routes,
-		mode: config.mode ?? "hybrid",
-		baseUrl,
-		locales,
-		defaultLocale
+function registerRoutes(ctx, routes) {
+	validateRoutes(routes);
+	const i18n = ctx.require(i18nPlugin);
+	ctx.state.table = compileRoutes({
+		routes,
+		mode: ctx.global.mode,
+		baseUrl: ctx.require(sitePlugin).url(),
+		locales: i18n.locales(),
+		defaultLocale: i18n.defaultLocale()
 	});
 }
+/**
+* Read the compiled matcher table, throwing if `onInit` has not run yet. This
+* `null` cannot occur in practice post-`onInit`; the guard documents the invariant.
+*
+* @param state - The router plugin state holder.
+* @returns The compiled, non-null matcher table.
+* @throws {Error} If the matcher table has not been compiled yet.
+* @example
+* ```ts
+* const table = readTable(ctx.state);
+* ```
+*/
+function readTable(state) {
+	if (state.table === null) throw new Error(`${ERROR_PREFIX$5}: routes not registered.\n  Set pluginConfigs.router.routes before app.start() / app.build.run().`);
+	return state.table;
+}
+/**
+* Project a compiled route into the public `TypedRoute` URL-utility view.
+*
+* @param entry - The compiled route entry.
+* @returns A `TypedRoute` exposing pattern/name/meta + toUrl/toFile/match.
+* @example
+* ```ts
+* toTypedRoute(compiledEntry).toUrl({ slug: "x" });
+* ```
+*/
+function toTypedRoute(entry) {
+	return {
+		pattern: entry.pattern,
+		name: entry.name,
+		meta: { ...entry.meta },
+		toUrl: entry.toUrl,
+		toFile: entry.toFile,
+		match: entry.matchFn
+	};
+}
+/**
+* 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.
+*
+* @param ctx - Plugin context.
+* @param ctx.state - The router state holding the compiled matcher table.
+* @returns The {@link RouterApi} surface mounted at `ctx.router`.
+* @example
+* ```ts
+* const api = createApi({ state });
+* api.match("/en/hello/");
+* ```
+*/
+function createApi$2(ctx) {
+	const { state } = ctx;
+	return {
+		/**
+		* Match a pathname against the compiled route table (specificity-sorted).
+		*
+		* @param pathname - URL pathname, e.g. `/en/hello/`.
+		* @returns `{ params, route }` for the most specific match, or `null`.
+		* @example
+		* ```ts
+		* api.match("/en/hello/");
+		* ```
+		*/
+		match(pathname) {
+			return matchRoute(readTable(state).compiled, pathname);
+		},
+		/**
+		* Build a URL for a named route from params.
+		*
+		* @param routeName - Route name key from the route map.
+		* @param params - Param values to substitute into the pattern.
+		* @returns The resolved URL string (e.g. `/en/hello/`).
+		* @throws {Error} If `routeName` is unknown.
+		* @example
+		* ```ts
+		* api.toUrl("article", { lang: "en", slug: "hello" });
+		* ```
+		*/
+		toUrl(routeName, params) {
+			const entry = readTable(state).byName.get(routeName);
+			if (!entry) throw new Error(`${ERROR_PREFIX$5}: unknown route name "${routeName}".\n  Check the name matches a key in the route map registered via pluginConfigs.router.routes.`);
+			return entry.toUrl(params);
+		},
+		/**
+		* All resolved routes as typed URL utilities, in specificity order.
+		*
+		* @returns A fresh read-only array of resolved typed routes.
+		* @example
+		* ```ts
+		* for (const r of api.entries()) r.toUrl({ slug: "x" });
+		* ```
+		*/
+		entries() {
+			return readTable(state).compiled.map((entry) => toTypedRoute(entry));
+		},
+		/**
+		* The typed route set for build-time consumption (declaration order). An API
+		* return, NOT a config readback — preserves per-route types despite erasure.
+		*
+		* @returns A fresh read-only array of the typed route definitions.
+		* @example
+		* ```ts
+		* for (const def of api.manifest()) def._handlers.render?.(routeContext);
+		* ```
+		*/
+		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 — read from the global framework config (the single
+		* source of truth for static/hybrid/spa). `build`/`spa` gate data nav on it.
+		*
+		* @returns `"ssg" | "spa" | "hybrid"`.
+		* @example
+		* ```ts
+		* if (api.mode() !== "ssg") emitClientData();
+		* ```
+		*/
+		mode() {
+			return ctx.global.mode;
+		}
+	};
+}
 //#endregion
 //#region src/plugins/router/builders/route-builder.ts
 /**
-* Create a fluent route builder from a URL pattern string. Captures the pattern
-* as a literal type for compile-time param inference; `.load()` is the only method
-* that widens the data generic, so `ctx.data` in `.render()`/`.head()` is typed by
-* `.load()`'s return at the CALL SITE. The returned object is itself the route
-* definition (`pattern` / `_meta` / `_handlers`), so it slots straight into a route map.
+* Build the handler-slot setter methods for one builder instance. Each method
+* records its handler under the matching slot and returns the builder, so the chain
+* stays fluent; they differ only in slot name and documented intent. `meta` is NOT
+* here — it merges into `_meta` rather than a handler slot — so the carrier is not
+* needed, keeping this helper a pure factory over the shared `set` primitive.
 *
-* @param pattern - URL pattern with `{param}` / `{param:?}` placeholders.
-* @returns A `RouteBuilder<RouteState<P>>` carrying the typed fluent chain.
+* @param set - The record-then-return-builder primitive shared by every method.
+* @returns The handler-slot setters (`load`/`layout`/`render`/`head`/`generate`/`toJson`/`toFile`).
 * @example
 * ```ts
-* route("/{lang:?}/{slug}/")
-*   .load(({ slug }) => loadArticle(slug))
-*   .render((ctx) => <Article a={ctx.data} />)
-*   .head((ctx) => ({ title: ctx.data.title }));
+* const methods = createBuilderMethods(set);
+* methods.render(handler); // records the render handler, returns the builder
 * ```
 */
-function route(pattern) {
-	const carrier = {
-		pattern,
-		_meta: {},
-		_handlers: {}
-	};
-	const handlers = carrier._handlers;
-	/**
-	* Record a handler under `key` and return the same builder for chaining.
-	*
-	* @param key - The handler slot name.
-	* @param fn - The handler function to store.
-	* @returns The same builder instance, for fluent chaining.
-	* @example
-	* ```ts
-	* set("render", handler);
-	* ```
-	*/
-	function set(key, fn) {
-		handlers[key] = fn;
-		return builder;
-	}
-	const builder = {
-		pattern: carrier.pattern,
-		_meta: carrier._meta,
-		_handlers: carrier._handlers,
+function createBuilderMethods(set) {
+	return {
 		/**
 		* Attach a data loader; widens the data generic for downstream handlers.
 		*
@@ -1679,7 +1832,7 @@ function route(pattern) {
 		* @returns The same builder, with the data generic widened.
 		* @example
 		* ```ts
-		* route("/{slug}/").load(({ slug }) => ({ slug }));
+		* route("/{slug}/").load((ctx) => ({ slug: ctx.params.slug }));
 		* ```
 		*/
 		load(loader) {
@@ -1719,21 +1872,6 @@ 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.
@@ -1760,6 +1898,78 @@ function route(pattern) {
 			return set("generate", handler);
 		},
 		/**
+		* Attach a JSON serializer for the route's data.
+		*
+		* @param handler - The JSON serializer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/api/").toJson(() => ({ ok: true }));
+		* ```
+		*/
+		toJson(handler) {
+			return set("toJson", handler);
+		},
+		/**
+		* Override the output file-path producer.
+		*
+		* @param handler - The file-path producer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/feed/").toFile(() => "feed.xml");
+		* ```
+		*/
+		toFile(handler) {
+			return set("toFile", handler);
+		}
+	};
+}
+/**
+* Create a fluent route builder from a URL pattern string. Captures the pattern
+* as a literal type for compile-time param inference; `.load()` is the only method
+* that widens the data generic, so `ctx.data` in `.render()`/`.head()` is typed by
+* `.load()`'s return at the CALL SITE. The returned object is itself the route
+* definition (`pattern` / `_meta` / `_handlers`), so it slots straight into a route map.
+*
+* @param pattern - URL pattern with `{param}` / `{param:?}` placeholders.
+* @returns A `RouteBuilder<RouteState<P>>` carrying the typed fluent chain.
+* @example
+* ```ts
+* route("/{lang:?}/{slug}/")
+*   .load((ctx) => loadArticle(ctx.params.slug))
+*   .render((ctx) => <Article a={ctx.data} />)
+*   .head((ctx) => ({ title: ctx.data.title }));
+* ```
+*/
+function route(pattern) {
+	const carrier = {
+		pattern,
+		_meta: {},
+		_handlers: {}
+	};
+	/**
+	* Record a handler under `key` and return the builder for chaining — the one
+	* primitive every typed handler setter (`load`, `render`, …) delegates to.
+	*
+	* @param key - The handler slot name.
+	* @param fn - The handler function to store.
+	* @returns The same builder instance, for fluent chaining.
+	* @example
+	* ```ts
+	* set("render", handler);
+	* ```
+	*/
+	const set = (key, fn) => {
+		carrier._handlers[key] = fn;
+		return builder;
+	};
+	const builder = {
+		pattern: carrier.pattern,
+		_meta: carrier._meta,
+		_handlers: carrier._handlers,
+		...createBuilderMethods(set),
+		/**
 		* 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.
@@ -1774,32 +1984,6 @@ function route(pattern) {
 		meta(meta) {
 			Object.assign(carrier._meta, meta);
 			return builder;
-		},
-		/**
-		* Attach a JSON serializer for the route's data.
-		*
-		* @param handler - The JSON serializer.
-		* @returns The same builder for chaining.
-		* @example
-		* ```ts
-		* route("/api/").toJson(() => ({ ok: true }));
-		* ```
-		*/
-		toJson(handler) {
-			return set("toJson", handler);
-		},
-		/**
-		* Override the output file-path producer.
-		*
-		* @param handler - The file-path producer.
-		* @returns The same builder for chaining.
-		* @example
-		* ```ts
-		* route("/feed/").toFile(() => "feed.xml");
-		* ```
-		*/
-		toFile(handler) {
-			return set("toFile", handler);
 		}
 	};
 	return builder;
@@ -1818,6 +2002,43 @@ function route(pattern) {
 function defineRoutes(routes) {
 	return routes;
 }
+/**
+* Build a pure, app-free URL builder from a route map. `toUrl(name, params)` resolves
+* a route's path by pattern substitution using the SAME `buildUrl` as the runtime
+* `RouterApi.toUrl`, so the helper and the API can never diverge. It needs no running
+* app, router instance, base URL, or i18n — just the route map the consumer already
+* holds at module scope. So components, layouts, and hydrated islands import it
+* directly: no `app.router` reference, no manual "bind", no module global, no
+* "not bound" guard, and no createApp ↔ routes cycle.
+*
+* @param routes - The route map (typically the value returned by {@link defineRoutes}).
+* @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
+* @example
+* ```ts
+* const url = createUrls(routes);
+* url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+* ```
+*/
+function createUrls(routes) {
+	return { 
+	/**
+	* Build a route's URL path from its name and params.
+	*
+	* @param name - Route name key from the map.
+	* @param params - Path params to substitute into the pattern. Defaults to `{}`.
+	* @returns The resolved relative URL path.
+	* @throws {Error} If `name` is not present in the route map.
+	* @example
+	* ```ts
+	* url.toUrl("home", { lang: "en" }); // "/en/"
+	* ```
+	*/
+toUrl(name, params = {}) {
+		const definition = routes[name];
+		if (!definition) throw new Error(`[web] router: unknown route name "${String(name)}".\n  Check the name matches a key in the route map passed to createUrls.`);
+		return buildUrl(definition.pattern, params);
+	} };
+}
 //#endregion
 //#region src/plugins/router/state.ts
 /**
@@ -1830,52 +2051,41 @@ function defineRoutes(routes) {
 * @returns The initial router state holder.
 * @example
 * ```ts
-* const state = createState({ global: {}, config: { routes: {} } });
+* const state = createState({ global: {}, config: { mode: "hybrid" } });
 * ```
 */
 function createState$2(_ctx) {
-	return {
-		table: null,
-		mode: _ctx.config.mode ?? "hybrid"
-	};
+	return { table: null };
 }
 /**
 * 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).
+* and matching. Author routes with {@link route}, then register them the normal config
+* way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL)
+* and i18n (locales).
 *
-* @example Define routes and choose a render mode
+* @example Register routes via config, then start/build
 * ```ts
+* import * as routes from "./routes";
 * const app = createApp({
-*   pluginConfigs: {
-*     router: {
-*       routes: defineRoutes({
-*         home: route("/"),
-*         article: route("/blog/{slug}/")
-*       }),
-*       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
-*     }
-*   }
+*   config: { mode: "hybrid" },               // render mode is GLOBAL config
+*   pluginConfigs: { router: { routes } }     // declarative route map (a namespace works)
 * });
+* await app.build.run();    // or: await app.start();  — routes compiled at init
 * ```
 */
 const routerPlugin = createPlugin$1("router", {
 	depends: [sitePlugin, i18nPlugin],
 	helpers: {
 		route,
-		defineRoutes
-	},
-	config: {
-		routes: {},
-		mode: "hybrid"
+		defineRoutes,
+		createUrls
 	},
+	config: {},
 	createState: createState$2,
-	api: createApi$2,
-	onInit(ctx) {
-		const i18n = ctx.require(i18nPlugin);
-		const baseUrl = ctx.require(sitePlugin).url();
-		ctx.state.table = buildRouterTable(ctx.config, baseUrl, i18n.locales(), i18n.defaultLocale());
-	}
+	onInit: (ctx) => {
+		if (ctx.config.routes) registerRoutes(ctx, ctx.config.routes);
+	},
+	api: createApi$2
 });
 //#endregion
 //#region src/plugins/head/primitives.ts
@@ -2011,10 +2221,34 @@ function feedLink(title, url, type = "application/rss+xml") {
 	};
 }
 /**
+* Build the schema.org `Article` structured-data object for the JSON-LD block,
+* carrying only the fields the article actually provides (optional fields are
+* omitted rather than emitted as `undefined`).
+*
+* @param articleMeta - Article metadata (title, description, author, dates, image…).
+* @returns A JSON-serializable `Article` object ready to hand to {@link jsonLd}.
+* @example buildArticleJsonLd({ title: "Hi", author: "A", published: "2026-01-01" })
+*/
+function buildArticleJsonLd(articleMeta) {
+	const ld = {
+		"@context": "https://schema.org",
+		"@type": "Article",
+		headline: articleMeta.title
+	};
+	if (articleMeta.description) ld.description = articleMeta.description;
+	if (articleMeta.author) ld.author = articleMeta.author;
+	if (articleMeta.published) ld.datePublished = articleMeta.published;
+	if (articleMeta.modified) ld.dateModified = articleMeta.modified;
+	if (articleMeta.image) ld.image = articleMeta.image;
+	return ld;
+}
+/**
 * Compose the full head element set for an article page: og:type=article, published/
 * modified times, author, section, tags, plus a JSON-LD `Article` block and canonical.
 *
 * @param articleMeta - Article metadata (title, description, author, dates, tags, image…).
+*   `image`, when present, is pushed to `og:image` verbatim and must therefore be
+*   an absolute URL (this helper does not resolve relative paths against the site).
 * @param canonicalUrl - The article's canonical absolute URL.
 * @returns An ordered array of serializable head elements.
 * @example buildArticleHead({ title: "Hi", author: "A", published: "2026-01-01" }, "https://x/p")
@@ -2027,17 +2261,7 @@ function buildArticleHead(articleMeta, canonicalUrl) {
 	if (articleMeta.section) elements.push(og(`${ARTICLE_PREFIX}section`, articleMeta.section));
 	for (const tag of articleMeta.tags ?? []) elements.push(og(`${ARTICLE_PREFIX}tag`, tag));
 	if (articleMeta.image) elements.push(og("og:image", articleMeta.image));
-	const ld = {
-		"@context": "https://schema.org",
-		"@type": "Article",
-		headline: articleMeta.title
-	};
-	if (articleMeta.description) ld.description = articleMeta.description;
-	if (articleMeta.author) ld.author = articleMeta.author;
-	if (articleMeta.published) ld.datePublished = articleMeta.published;
-	if (articleMeta.modified) ld.dateModified = articleMeta.modified;
-	if (articleMeta.image) ld.image = articleMeta.image;
-	elements.push(jsonLd(ld));
+	elements.push(jsonLd(buildArticleJsonLd(articleMeta)));
 	return elements;
 }
 //#endregion
@@ -2072,7 +2296,30 @@ function applyTemplate(title, template) {
 * @example resolveImage("/og.png", site) // "https://blog.dev/og.png"
 */
 function resolveImage(image, site) {
-	return image.startsWith("http") ? image : site.canonical(image);
+	return /^https?:\/\//.test(image) || image.startsWith("//") ? image : site.canonical(image);
+}
+/**
+* Build the per-locale `hreflang` alternates for a route, plus the `x-default`
+* fallback (the route's URL with no `lang` override). Each alternate URL is the
+* route's canonical URL for that locale, absolutized against the site base URL.
+*
+* @param locales - The supported locale codes (drives the alternate set).
+* @param route - The resolved route descriptor (provides `name` + `params`).
+* @param router - The router slice used to build each locale's URL.
+* @param site - The site slice used to absolutize each locale's URL.
+* @returns The ordered `hreflang` element set: one per locale, then `x-default`.
+* @example buildHreflangAlternates(["en", "fr"], route, router, site)
+*/
+function buildHreflangAlternates(locales, route, router, site) {
+	const alternates = locales.map((locale) => {
+		return hreflang(locale, site.canonical(router.toUrl(route.name, {
+			...route.params,
+			lang: locale
+		})));
+	});
+	const xDefaultHref = site.canonical(router.toUrl(route.name, { ...route.params }));
+	alternates.push(hreflang(X_DEFAULT, xDefaultHref));
+	return alternates;
 }
 /**
 * Build the canonical, og, twitter, and hreflang elements for the route from
@@ -2089,7 +2336,6 @@ function resolveImage(image, site) {
 function buildBaseElements(input, resolved) {
 	const { route, defaults, site, i18n, router } = input;
 	const head = route.head ?? {};
-	const image = head.image ?? defaults.defaultOgImage;
 	const elements = [
 		{
 			tag: "title",
@@ -2104,6 +2350,7 @@ function buildBaseElements(input, resolved) {
 		twitter("twitter:title", head.title ?? resolved.title),
 		twitter("twitter:description", resolved.description)
 	];
+	const image = head.image ?? defaults.defaultOgImage;
 	if (image) {
 		const abs = resolveImage(image, site);
 		elements.push(og("og:image", abs), twitter("twitter:image", abs));
@@ -2111,16 +2358,7 @@ function buildBaseElements(input, resolved) {
 	if (defaults.twitterHandle) elements.push(twitter("twitter:site", defaults.twitterHandle));
 	const ogLocale = route.locale ? i18n.ogLocale(route.locale) : void 0;
 	if (ogLocale) elements.push(og("og:locale", ogLocale));
-	elements.push(canonical(resolved.canonicalUrl));
-	for (const locale of i18n.locales()) {
-		const href = site.canonical(router.toUrl(route.name, {
-			...route.params,
-			lang: locale
-		}));
-		elements.push(hreflang(locale, href));
-	}
-	const xDefaultHref = site.canonical(router.toUrl(route.name, { ...route.params }));
-	elements.push(hreflang(X_DEFAULT, xDefaultHref));
+	elements.push(canonical(resolved.canonicalUrl), ...buildHreflangAlternates(i18n.locales(), route, router, site));
 	return elements;
 }
 /**
@@ -2174,6 +2412,17 @@ function escapeHtml(raw) {
 	return raw.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
 }
 /**
+* Serialize an element's attribute map to a space-joined `name="value"` string,
+* HTML-escaping each value. Returns `""` when there are no attributes.
+*
+* @param attributes - The element's attribute map (may be `undefined`).
+* @returns The serialized attribute string (no leading/trailing space).
+* @example serializeAttrs({ name: "robots", content: "index" }) // 'name="robots" content="index"'
+*/
+function serializeAttributes(attributes) {
+	return Object.entries(attributes ?? {}).map(([name, value]) => `${name}="${escapeHtml(value)}"`).join(" ");
+}
+/**
 * Serialize a single `HeadElement` to its HTML string form. Attribute values are
 * HTML-escaped; `script` children are emitted verbatim (already unicode-escaped by
 * `jsonLd`); `title` text is HTML-escaped.
@@ -2183,11 +2432,10 @@ function escapeHtml(raw) {
 * @example serializeElement(meta("robots", "index"))
 */
 function serializeElement(element) {
-	const attributes = Object.entries(element.attrs ?? {}).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ");
-	const open = attributes.length === 0 ? element.tag : `${element.tag} ${attributes}`;
+	const attributes = serializeAttributes(element.attrs);
 	if (element.tag === "script") return `<script ${attributes}>${element.children ?? ""}<\/script>`;
 	if (element.tag === "title") return `<title>${escapeHtml(element.children ?? "")}</title>`;
-	return `<${open}>`;
+	return `<${attributes.length === 0 ? element.tag : `${element.tag} ${attributes}`}>`;
 }
 /**
 * Serialize a `HeadElement[]` to `<head>` inner HTML. All attribute values are
@@ -2210,7 +2458,7 @@ function serializeHead(elements) {
 * it to a string. It holds no resource and caches no subscription.
 */
 /** Error prefix for head API invariant failures. */
-const ERROR_PREFIX$4 = "[head]";
+const ERROR_PREFIX$4 = "[web] head";
 /**
 * Read the normalized defaults, asserting the post-`onInit` invariant (the slot is
 * `null` only before `onInit` assigns it, which cannot occur at render time).
@@ -2267,7 +2515,7 @@ render(route, data) {
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
-const ERROR_PREFIX$3 = "[head] config:";
+const ERROR_PREFIX$3 = "[web] head";
 /** The allowed `twitterCard` literals (also the runtime guard set). */
 const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 /**
@@ -2283,7 +2531,7 @@ const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 const defaultConfig = { twitterCard: "summary_large_image" };
 /**
 * Structurally validate the resolved head config (no I/O). Throws a standard
-* `[head] config: …` error when `titleTemplate` is provided without the `%s`
+* `[web] head: …` error when `titleTemplate` is provided without the `%s`
 * token, or when `twitterCard` is present but not one of the two allowed literals.
 *
 * @param config - The resolved head {@link Config} to validate.
@@ -2294,8 +2542,8 @@ const defaultConfig = { twitterCard: "summary_large_image" };
 * ```
 */
 function validateHeadConfig(config) {
-	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$3} titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
-	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$3} twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
+	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$3}: titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
+	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$3}: twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
 }
 /**
 * Validate then build the frozen, normalized {@link HeadDefaults} snapshot read by
@@ -2445,35 +2693,287 @@ function createApi(ctx) {
 		*
 		* @returns The current pathname + search.
 		* @example
-		* app.spa.current();
+		* app.spa.current();
+		*/
+		current() {
+			return ctx.state.currentUrl;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/spa/events.ts
+/**
+* Declares the spa plugin's events. Extracted from index.ts to keep the wiring
+* file under the line budget.
+*
+* @param register - The event registration function supplied by the kernel.
+* @returns The map of spa event descriptors.
+* @example
+* const events = spaEvents(register);
+*/
+function spaEvents(register) {
+	return {
+		"spa:navigate": register("A navigation has been intercepted and is starting."),
+		"spa:navigated": register("The swap completed and the new URL is active."),
+		"spa:component-mount": register("A component instance attached to an element."),
+		"spa:component-unmount": register("A component instance detached from an element.")
+	};
+}
+//#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.at(path)` uses it, and consumers read through `app.data.at(path)`.
+*
+* 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.at`)
+* 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/hello/index.json")
+* // Node:    read "dist/_data/en/hello/index.json"
+* const article = await loadJson<Article>("/_data/en/hello/index.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).
+*/
+/**
+* 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`, which the route uses directly as `ctx.data`
+		* (no route `.parse()`); returns `null` if the fetch or JSON 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}${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 import("./writer-Dc_lx22j.mjs");
+			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}${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"
+		* ```
 		*/
-		current() {
-			return ctx.state.currentUrl;
+		fileFor(path) {
+			return relativeDataFile(ctx.config.outputDir, path);
 		}
 	};
 }
 //#endregion
-//#region src/plugins/spa/events.ts
+//#region src/plugins/data/config.ts
 /**
-* Declares the spa plugin's events. Extracted from index.ts to keep the wiring
-* file under the line budget.
+* 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/"`).
 *
-* @param register - The event registration function supplied by the kernel.
-* @returns The map of spa event descriptors.
 * @example
-* const events = spaEvents(register);
+* ```ts
+* createPlugin("data", { config: defaultDataConfig });
+* ```
 */
-function spaEvents(register) {
+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 {
-		"spa:navigate": register("A navigation has been intercepted and is starting."),
-		"spa:navigated": register("The swap completed and the new URL is active."),
-		"spa:component-mount": register("A component instance attached to an element."),
-		"spa:component-unmount": register("A component instance detached from an element.")
+		lastWrite: null,
+		cache: /* @__PURE__ */ new Map()
 	};
 }
 //#endregion
+//#region src/plugins/data/validate.ts
+/**
+* Reports whether a `baseUrl` value is invalid: it must be a string that is a
+* site-root-relative URL path (i.e. starting with "/").
+*
+* @param baseUrl - The candidate `baseUrl` value to check.
+* @returns `true` when `baseUrl` is not a string or does not start with "/".
+* @example
+* ```ts
+* isInvalidBaseUrl("/_data/"); // false
+* isInvalidBaseUrl("_data"); // true
+* ```
+*/
+function isInvalidBaseUrl(baseUrl) {
+	return typeof baseUrl !== "string" || !baseUrl.startsWith("/");
+}
+/**
+* Validates the resolved data config: the browser `baseUrl` must be a non-empty,
+* site-root-relative URL path.
+*
+* @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 (isInvalidBaseUrl(config.baseUrl)) 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 uses directly as `ctx.data` in `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". Compose the plugin + set the global render mode:
+* import * as routes from "./routes";
+* const app = createApp({
+*   plugins: [dataPlugin, contentPlugin, buildPlugin],
+*   config: { mode: "hybrid" },
+*   pluginConfigs: { content: { providers: [fileSystemContent({ contentDir: "./content" })] }, router: { routes } }
+* });
+* await app.build.run();   // writes HTML + per-page data sidecars (routes compiled at init)
+*
+* // 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/spa/types.ts
-var types_exports$5 = /* @__PURE__ */ __exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
+var types_exports$6 = /* @__PURE__ */ __exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
 /** Allowed hook names — single source of truth for fail-fast validation. */
 const COMPONENT_HOOK_NAMES = [
 	"onCreate",
@@ -3162,15 +3662,6 @@ function createState(_ctx) {
 /** Error prefix for spa kernel failures (spec/11 Part-3). */
 const ERROR_PREFIX = "[web]";
 /**
-* Module-scope holder for the active SPA kernel. `onStop` receives the minimal
-* teardown context (no `state`/`require`), so the kernel built during `onInit`
-* is parked here for disposal. Single-app-per-process by design (spec/08 §4).
-*
-* @example
-* kernelRef.current = createSpaKernel(state, config, emit, deps);
-*/
-const kernelRef = {};
-/**
 * Registers a component definition into state (last-registered-wins).
 *
 * @param state - The plugin state holding registeredComponents.
@@ -3271,51 +3762,101 @@ function createSpaKernel(state, config, emit, deps) {
 		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.
+	* Phase 1 of the client DATA path (no side effects): match `pathname`, fetch the
+	* page's PERSISTED data via the `data` reader, build the {@link RouteContext}, run
+	* the route's OWN `render` (the same component the build used for SSG), and locate
+	* the live swap region. The fetched JSON is used DIRECTLY as `ctx.data` (no
+	* validation step — `route.parse` was removed). Returns `false` (committing
+	* nothing) on no-`data`-reader / no-match / no-render / no-region / fetch-miss,
+	* so the caller falls back to HTML-over-fetch.
 	*
 	* @param pathname - The destination pathname (search stripped for matching).
-	* @returns `true` if the route was rendered from validated data, else `false`.
+	* @returns The resolved render inputs, or `false` when the DATA path cannot run.
 	* @example
-	* if (await tryDataRender("/en/world/")) return;
+	* const resolved = await resolveDataRender("/en/world/");
 	*/
-	const tryDataRender = async (pathname) => {
+	const resolveDataRender = 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;
+		const data = await deps.dataAt(pathname);
+		if (data === null) return false;
+		const locale = hit.params.lang ?? document.documentElement.lang ?? "";
+		const routeContext = {
+			params: hit.params,
+			data,
+			locale,
+			url: (routeName, routeParams = {}) => deps.router.toUrl(routeName, routeParams)
+		};
+		const vnode = hit.route._handlers.render(routeContext);
+		const region = document.querySelector(resolved.swapSelector);
+		if (!region) return false;
+		return {
+			route: hit.route,
+			vnode,
+			routeContext,
+			region
+		};
+	};
+	/**
+	* Phase 2 of the client DATA path (all side effects): begin the navigation,
+	* lazy-load the Preact render layer, sync the document head, unmount the
+	* outgoing page-specific islands, swap the VNode into the region, re-mount, then
+	* record the new URL and emit `spa:navigated`.
+	*
+	* @param pathname - The destination pathname (recorded as the new current URL).
+	* @param resolvedRender - The inputs produced by {@link resolveDataRender}.
+	* @example
+	* await commitDataRender("/en/world/", resolved);
+	*/
+	const commitDataRender = async (pathname, resolvedRender) => {
+		const { route, vnode, routeContext, region } = resolvedRender;
+		handleStart(pathname);
+		const { renderVNode } = await import("./render-BNe0s7fr.mjs");
+		syncDataHead(route, routeContext);
+		unmountPageSpecific(state, emit);
+		/**
+		* Render the VNode into the region and re-mount its islands in one paint — the
+		* swap body handed to `runSwap` (optionally wrapped in a View Transition).
+		*
+		* @example
+		* ```ts
+		* runSwap(renderAndMount, resolved.viewTransitions);
+		* ```
+		*/
+		const renderAndMount = () => {
+			renderVNode(vnode, region);
+			scanAndMount(state, emit, resolved.swapSelector);
+			notifyNavEnd(state);
+		};
+		runSwap(renderAndMount, resolved.viewTransitions);
+		state.currentUrl = pathname;
+		progress?.done();
+		emit("spa:navigated", { url: pathname });
+	};
+	/**
+	* The client DATA path: resolve the matched route's render inputs from the
+	* page's PERSISTED data ({@link resolveDataRender}), then commit the Preact swap
+	* ({@link commitDataRender}). The fetched JSON is used DIRECTLY as `ctx.data`
+	* (no validation step). `route.load` does NOT run on the client — the build
+	* already persisted its output. Returns `false` (touching nothing the fallback
+	* cares about) on no-match / no-render / null / throw, so the caller falls back
+	* to HTML-over-fetch.
+	*
+	* @param pathname - The destination pathname (search stripped for matching).
+	* @returns `true` if the route was rendered from its data, else `false`.
+	* @example
+	* if (await tryDataRender("/en/world/")) return;
+	*/
+	const tryDataRender = async (pathname) => {
 		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 import("./render-BNe0s7fr.mjs");
-			syncDataHead(hit.route, routeContext);
-			unmountPageSpecific(state, emit);
-			runSwap(() => {
-				renderVNode(vnode, region);
-				scanAndMount(state, emit, resolved.swapSelector);
-				notifyNavEnd(state);
-			}, resolved.viewTransitions);
-			state.currentUrl = pathname;
-			progress?.done();
-			emit("spa:navigated", { url: pathname });
+			const resolvedRender = await resolveDataRender(pathname);
+			if (resolvedRender === false) return false;
+			await commitDataRender(pathname, resolvedRender);
 			return true;
 		} catch {
+			progress?.done();
 			return false;
 		}
 	};
@@ -3406,26 +3947,12 @@ 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). Captures the OPTIONAL `data` reader when
-* the `data` plugin is composed (enabling client DATA navigation).
+* Builds the shared kernel from the plugin context, stores it on `ctx.state`,
+* and runs its init step (validate config, register config.components, seed
+* currentUrl). Captures the OPTIONAL `data` reader when the `data` plugin is
+* composed (enabling client DATA navigation) — resolved by instance via
+* `ctx.require(dataPlugin)`, guarded by `ctx.has("data")` so `data` stays optional
+* (`spa`'s `depends` is `[router, head]`).
 *
 * @param ctx - The plugin context (state/config/emit/require/has/log).
 * @example
@@ -3437,12 +3964,11 @@ function initSpa(ctx) {
 		head: ctx.require(headPlugin)
 	};
 	if (ctx.has("data")) {
-		const reader = ctx.require(dataPluginHandle);
+		const reader = ctx.require(dataPlugin);
 		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();
 }
 //#endregion
@@ -3452,353 +3978,598 @@ let teardown;
 /** Captured log ref — onStop has no `ctx.log` (spec/08 §4). */
 let logRef;
 /**
-* Dispose the active kernel (captured as the teardown closure during onStart).
-*
-* @example
-* disposeKernel();
-*/
-function disposeKernel() {
-	kernelRef.current?.dispose();
-}
-/**
 * Capture the teardown + log handles during `onStart` (no-op without a DOM —
-* the SSR/build guard, so onStop has nothing to release). The kernel itself is
-* booted by index.ts after this capture.
+* the SSR/build guard, so onStop has nothing to release). The kernel built in
+* `onInit` lives on `ctx.state`; its `dispose` is captured into the teardown
+* closure here. The kernel itself is booted by index.ts after this capture.
 *
-* @param ctx - The plugin context (used for `log` capture).
+* @param ctx - The plugin context (used for `state.kernel` + `log` capture).
 * @example
 * captureTeardown(ctx);
 */
 function captureTeardown(ctx) {
 	if (typeof document === "undefined") return;
 	logRef = ctx.log;
-	teardown = disposeKernel;
+	const kernel = ctx.state.kernel;
+	teardown = () => kernel?.dispose();
+}
+/**
+* Release everything `captureTeardown`/`onStart` acquired: run teardown in
+* try/catch (logging via the captured ref), then clear both handles. Idempotent —
+* a second call is a no-op (spec/11 §4.2) and mirrors `onStart` (§4.1).
+*
+* @example
+* disposeSpa();
+*/
+function disposeSpa() {
+	try {
+		teardown?.();
+	} catch (error) {
+		logRef?.error("spa:teardown-failed", {}, error);
+	} finally {
+		teardown = void 0;
+		logRef = void 0;
+	}
+}
+//#endregion
+//#region src/plugins/spa/index.ts
+/**
+* @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
+* domain files (kernel/router/head/progress/components/lifecycle); index wires.
+*
+* Depends: router, head.
+* 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,
+	createState,
+	events: spaEvents,
+	onInit: initSpa,
+	api: createApi,
+	onStart(ctx) {
+		captureTeardown(ctx);
+		ctx.state.kernel?.boot();
+	},
+	onStop: disposeSpa
+});
+//#endregion
+//#region src/plugins/content/api.ts
+/** Actionable error when the content plugin is composed without any provider. */
+const NO_PROVIDER = "[web] content: no provider composed.\n  Add fileSystemContent(...) to pluginConfigs.content.providers.";
+/** Zero-pad width for the per-locale ordinal in a `contentId` (e.g. `0001`). */
+const ID_PADDING = 4;
+/** Path segment offset of the article slug — the parent directory of the source file. */
+const PATH_SLUG_INDEX = -2;
+/**
+* Collapse the ordered provider list into a single {@link ContentProvider} facade:
+* `slugs()` are unioned, `readArticle`/`render` use first-match, `invalidate` fans out.
+* A single-provider list returns that provider directly (the common case).
+*
+* @param providers - The ordered content providers from config.
+* @returns One provider facade over the list.
+* @example
+* ```ts
+* const provider = mergeProviders(ctx.config.providers);
+* ```
+*/
+function mergeProviders(providers) {
+	const [first] = providers;
+	if (providers.length === 1 && first !== void 0) return first;
+	return {
+		name: providers.map((provider) => provider.name).join("+") || "content:empty",
+		contentDir: first?.contentDir ?? "",
+		/**
+		* Union of every provider's slugs, sorted.
+		*
+		* @returns The merged slug list.
+		* @example
+		* ```ts
+		* await provider.slugs();
+		* ```
+		*/
+		async slugs() {
+			const lists = await Promise.all(providers.map((provider) => provider.slugs()));
+			return [...new Set(lists.flat())].toSorted();
+		},
+		/**
+		* First provider to supply the article wins.
+		*
+		* @param slug - Article directory name.
+		* @param fileLocale - Locale whose source file is read.
+		* @param outLocale - Locale the resulting Article represents.
+		* @param isFallback - Whether this used the default-locale fallback.
+		* @returns The first non-null Article, or `null`.
+		* @example
+		* ```ts
+		* await provider.readArticle("intro", "en", "en", false);
+		* ```
+		*/
+		async readArticle(slug, fileLocale, outLocale, isFallback) {
+			return (await Promise.all(providers.map((provider) => provider.readArticle(slug, fileLocale, outLocale, isFallback)))).find((article) => article !== null) ?? null;
+		},
+		/**
+		* Render via the first provider.
+		*
+		* @param markdown - Raw Markdown source.
+		* @returns The rendered HTML.
+		* @throws {Error} If no provider is composed.
+		* @example
+		* ```ts
+		* await provider.render("# Hi");
+		* ```
+		*/
+		async render(markdown) {
+			if (first === void 0) throw new Error(NO_PROVIDER);
+			return first.render(markdown);
+		},
+		/**
+		* Fan invalidation out to every provider.
+		*
+		* @param paths - Stale file paths.
+		* @example
+		* ```ts
+		* provider.invalidate(["content/intro/en.md"]);
+		* ```
+		*/
+		invalidate(paths) {
+			for (const provider of providers) provider.invalidate?.(paths);
+		}
+	};
+}
+/**
+* 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.`);
 }
 /**
-* Release everything `captureTeardown`/`onStart` acquired: run teardown in
-* try/catch (logging via the captured ref), then clear both handles. Idempotent —
-* a second call is a no-op (spec/11 §4.2) and mirrors `onStart` (§4.1).
+* Plugin `api` factory: resolves i18n via `ctx.require`, merges `config.providers` into
+* one source, assembles the kernel-free {@link ContentApiContext}, and delegates to
+* {@link createContentApi}. Referenced directly as the plugin's `api` so index.ts stays
+* wiring-only. Imports no node code (the provider owns it).
 *
+* @param ctx - Plugin context (state, config, global, emit, require).
+* @returns The constructed content plugin API surface.
 * @example
-* disposeSpa();
+* ```ts
+* const api = contentApi(ctx);
+* ```
 */
-function disposeSpa() {
-	try {
-		teardown?.();
-	} catch (error) {
-		logRef?.error("spa:teardown-failed", {}, error);
-	} finally {
-		teardown = void 0;
-		logRef = void 0;
+function contentApi(ctx) {
+	const i18nApi = ctx.require(i18nPlugin);
+	/**
+	* Active locale codes from i18n.
+	*
+	* @returns The configured locale list.
+	* @example
+	* ```ts
+	* locales(); // ["en"]
+	* ```
+	*/
+	function locales() {
+		return i18nApi.locales();
+	}
+	/**
+	* Default locale code from i18n (fallback source).
+	*
+	* @returns The configured default locale.
+	* @example
+	* ```ts
+	* defaultLocale(); // "en"
+	* ```
+	*/
+	function defaultLocale() {
+		return i18nApi.defaultLocale();
 	}
+	return createContentApi({
+		state: ctx.state,
+		global: ctx.global,
+		emit: ctx.emit,
+		locales,
+		defaultLocale,
+		provider: mergeProviders(ctx.config.providers)
+	});
 }
-//#endregion
-//#region src/plugins/spa/index.ts
 /**
-* @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
-* domain files (kernel/router/head/progress/components/lifecycle); index wires.
+* Resolve one article for `(slug, locale)` with locale fallback via the provider: the
+* native `{locale}` file is preferred (`isFallback: false`); when absent, the
+* default-locale file is used (`isFallback: true`, requested locale retained).
+* Returns `null` when neither exists.
 *
-* Depends: router, head.
-* Emits: spa:navigate, spa:navigated, spa:component-mount, spa:component-unmount.
-* @see README.md
+* @param ctx - Kernel-free domain context.
+* @param slug - Article directory name.
+* @param locale - Requested locale code.
+* @returns The resolved Article, or `null` when nothing matches.
+* @example
+* ```ts
+* const article = await resolveArticle(ctx, "intro", "uk");
+* ```
 */
+async function resolveArticle(ctx, slug, locale) {
+	const native = await ctx.provider.readArticle(slug, locale, locale, false);
+	if (native !== null) return native;
+	const fallbackLocale = ctx.defaultLocale();
+	if (fallbackLocale === locale) return null;
+	return ctx.provider.readArticle(slug, fallbackLocale, locale, true);
+}
 /**
-* 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`.
+* Comparator sorting articles by frontmatter date descending (newest first),
+* breaking ties by slug for deterministic ordering.
 *
-* @example Enable view transitions and a custom swap region
+* @param a - First article.
+* @param b - Second article.
+* @returns Negative when `a` is newer, positive when older, 0 when equal.
+* @example
 * ```ts
-* const app = createApp({
-*   pluginConfigs: {
-*     spa: {
-*       swapSelector: "main > section",
-*       viewTransitions: true,
-*       progressBar: true
-*     }
-*   }
-* });
+* articles.toSorted(byDateDescending);
 * ```
 */
-const spaPlugin = createPlugin$1("spa", {
-	depends: [routerPlugin, headPlugin],
-	config: defaultSpaConfig,
-	createState,
-	events: spaEvents,
-	onInit: initSpa,
-	api: createApi,
-	onStart(ctx) {
-		captureTeardown(ctx);
-		kernelRef.current?.boot();
-	},
-	onStop: disposeSpa
-});
-//#endregion
-//#region src/plugins/data/load-json.ts
+function byDateDescending(a, b) {
+	const byDate = b.frontmatter.date.localeCompare(a.frontmatter.date);
+	return byDate === 0 ? a.computed.slug.localeCompare(b.computed.slug) : byDate;
+}
 /**
-* @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.
+* Project a full Article to a lightweight ArticleCard (no rendered HTML).
 *
-* 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).
+* @param article - The source article.
+* @returns The card projection.
+* @example
+* ```ts
+* const card = toCard(article);
+* ```
 */
+function toCard(article) {
+	return {
+		contentId: article.computed.contentId,
+		status: article.computed.status,
+		title: article.frontmatter.title,
+		date: article.frontmatter.date,
+		description: article.frontmatter.description,
+		tags: article.frontmatter.tags,
+		readingTime: article.computed.readingTime,
+		url: article.url
+	};
+}
 /**
-* 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.
+* Whether an article belongs in a locale collection: every article is published
+* outside production, and in production all non-`draft` articles are published.
 *
-* @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.
+* @param article - The candidate article.
+* @param isProduction - Whether the deployment stage is production.
+* @returns `true` when the article should be included.
 * @example
 * ```ts
-* // Browser: fetch("/_data/en/articles.json")
-* // Node:    read "dist/_data/en/articles.json"
-* const articles = await loadJson<Article[]>("/_data/en/articles.json");
+* isPublished(article, true); // false for a draft in production
 * ```
 */
-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();
+function isPublished(article, isProduction) {
+	return !isProduction || article.computed.status !== "draft";
 }
-//#endregion
-//#region src/plugins/data/api.ts
 /**
-* @file data plugin — API factory (the agnostic data provider surface).
+* Resolve every slug for one locale, then narrow to the articles that belong in the
+* locale collection: existing files only, drafts dropped in production, sorted
+* date-descending. The single load+filter+sort step behind {@link createContentApi.loadAll}.
 *
-* 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).
+* @param ctx - Kernel-free domain context (provider + i18n helpers + stage).
+* @param slugs - Every known article slug from the provider.
+* @param locale - The locale to resolve and collect.
+* @returns The published (date-descending) articles for this locale.
+* @example
+* ```ts
+* const present = await loadAndFilterArticles(ctx, slugs, "en");
+* ```
 */
+async function loadAndFilterArticles(ctx, slugs, locale) {
+	const isProduction = ctx.global.stage === "production";
+	return (await Promise.all(slugs.map((slug) => resolveArticle(ctx, slug, locale)))).filter((article) => article !== null).filter((article) => isPublished(article, isProduction)).toSorted(byDateDescending);
+}
 /**
-* Trim a single trailing slash from a config dir so `fileFor` joins cleanly.
+* Derive the article slug from a source file path — the parent directory name
+* (`content/intro/en.md` → `intro`). Returns `undefined` when the path has no
+* parent segment.
 *
-* @param dir - The configured output dir (e.g. `"_data"` or `"_data/"`).
-* @returns The dir without a trailing slash.
+* @param filePath - The (possibly stale) source file path.
+* @returns The slug segment, or `undefined` when none exists.
 * @example
 * ```ts
-* trimTrailingSlash("_data/"); // "_data"
+* extractSlugFromPath("content/intro/en.md"); // "intro"
 * ```
 */
-function trimTrailingSlash(dir) {
-	return dir.endsWith("/") ? dir.slice(0, -1) : dir;
+function extractSlugFromPath(filePath) {
+	return filePath.split(/[/\\]/).at(PATH_SLUG_INDEX);
 }
 /**
-* 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).
+* Creates the content plugin API surface (loadAll, load, renderMarkdown, invalidate,
+* articleToCard, contentDir) over the kernel-free domain context. Delegates all source
+* reads to `ctx.provider`; drafts are excluded only in production; `loadAll` emits
+* `content:ready` and `invalidate` emits `content:invalidated`.
 *
-* @param ctx - The data plugin context.
-* @returns The {@link DataProvider} mounted at `app.data`.
+* @param ctx - Kernel-free domain context (state, global, emit, i18n helpers, provider).
+* @returns The content plugin {@link Api} surface.
 * @example
 * ```ts
-* const api = dataApi(ctx);
-* await api.write([{ path: "/en/hello/", data: article }]); // Node build
-* await api.at("/en/hello/");                               // browser
+* const api = createContentApi(apiContext);
+* const byLocale = await api.loadAll();
 * ```
 */
-function dataApi(ctx) {
+function createContentApi(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).
+		* Load every article across every active locale (locale fallback, production
+		* draft exclusion, date sort, `contentId` after sort), cache them, emit `content:ready`.
 		*
-		* @param path - The page URL path (e.g. `/en/hello/`).
-		* @returns The page's raw data, or `null` on failure.
+		* @returns A locale-keyed map of date-descending articles.
 		* @example
 		* ```ts
-		* const raw = await api.at("/en/hello/");
+		* const byLocale = await api.loadAll();
 		* ```
 		*/
-		async at(path) {
-			if (ctx.state.cache.has(path)) return ctx.state.cache.get(path);
-			try {
-				const data = await loadJson(`${ctx.config.baseUrl}${dataSuffix(path)}`);
-				ctx.state.cache.set(path, data);
-				return data;
-			} catch {
-				return null;
+		async loadAll() {
+			const slugs = await ctx.provider.slugs();
+			const locales = ctx.locales();
+			const result = /* @__PURE__ */ new Map();
+			let total = 0;
+			for (const locale of locales) {
+				const present = await loadAndFilterArticles(ctx, slugs, locale);
+				const cache = /* @__PURE__ */ new Map();
+				let index = 0;
+				for (const article of present) {
+					article.computed.contentId = `${locale}:${String(index).padStart(ID_PADDING, "0")}:${article.computed.slug}`;
+					cache.set(article.computed.slug, article);
+					index += 1;
+				}
+				ctx.state.articles.set(locale, cache);
+				result.set(locale, present);
+				total += present.length;
 			}
+			ctx.emit("content:ready", {
+				locales,
+				articleCount: total
+			});
+			return result;
 		},
 		/**
-		* 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).
+		* Resolve and render a single article for one locale with locale fallback. Throws a
+		* `[web] content` not-found error when no file matches; in production a `draft` is
+		* suppressed and throws the SAME not-found error (drafts indistinguishable from
+		* missing); in development and test drafts load normally.
 		*
-		* @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.
+		* @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.stage === "production"`.
 		* @example
 		* ```ts
-		* await api.write([{ path: "/en/hello/", data: article }], { outDir: "dist" });
+		* const article = await api.load("intro", "uk");
 		* ```
 		*/
-		async write(entries, options) {
-			const { writeData } = await import("./writer-BcWqa_7I.mjs");
-			return writeData(ctx, entries, options);
+		async load(slug, locale) {
+			const article = await resolveArticle(ctx, slug, locale);
+			if (article === null) throw articleNotFound(slug, locale);
+			if (ctx.global.stage === "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);
+			return article;
 		},
 		/**
-		* PURE — the browser fetch URL for a page path.
+		* Render a raw Markdown string to HTML through the provider's pipeline.
 		*
-		* @param path - The page URL path.
-		* @returns The site-root-relative data URL.
+		* @param md - Raw Markdown source.
+		* @returns The rendered HTML string.
 		* @example
 		* ```ts
-		* api.urlFor("/en/hello/"); // "/_data/en/hello/index.json"
+		* const html = await api.renderMarkdown("# Hi");
 		* ```
 		*/
-		urlFor(path) {
-			return `${ctx.config.baseUrl}${dataSuffix(path)}`;
+		async renderMarkdown(md) {
+			return ctx.provider.render(md);
 		},
 		/**
-		* PURE — the `outDir`-relative file path for a page path.
+		* Mark file paths stale for incremental dev rebuilds: fan invalidation to the
+		* provider and drop the derived slug cache entries so the next `loadAll()` re-reads
+		* only those files. Empty/whitespace paths are ignored. Emits `content:invalidated`.
 		*
-		* @param path - The page URL path.
-		* @returns The output-relative file path.
+		* @param paths - File paths to invalidate.
 		* @example
 		* ```ts
-		* api.fileFor("/en/hello/"); // "_data/en/hello/index.json"
+		* api.invalidate(["src/content/intro/en.md"]);
 		* ```
 		*/
-		fileFor(path) {
-			return `${trimTrailingSlash(ctx.config.outputDir)}/${dataSuffix(path)}`;
+		invalidate(paths) {
+			const accepted = paths.filter((filePath) => filePath.trim() !== "");
+			ctx.provider.invalidate?.(accepted);
+			for (const filePath of accepted) {
+				const slug = extractSlugFromPath(filePath);
+				if (slug === void 0) continue;
+				for (const cache of ctx.state.articles.values()) cache.delete(slug);
+			}
+			ctx.emit("content:invalidated", { paths: accepted });
+		},
+		/**
+		* Project a full Article to a lightweight ArticleCard for list/grid rendering.
+		*
+		* @param article - The source article.
+		* @returns The card projection.
+		* @example
+		* ```ts
+		* const card = api.articleToCard(article);
+		* ```
+		*/
+		articleToCard(article) {
+			return toCard(article);
+		},
+		/**
+		* The configured content source directory (from the first provider).
+		*
+		* @returns The content directory path.
+		* @example
+		* ```ts
+		* api.contentDir(); // "./content"
+		* ```
+		*/
+		contentDir() {
+			return ctx.provider.contentDir;
 		}
 	};
 }
 //#endregion
-//#region src/plugins/data/config.ts
+//#region src/plugins/content/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/"`).
+* Typed default content config (R6: no inline `as`). The provider list defaults to
+* `[]`; a build MUST compose at least one (e.g. `fileSystemContent(...)`), enforced at
+* `onInit`. Source + pipeline options now live on the provider, not here.
 *
 * @example
 * ```ts
-* createPlugin("data", { config: defaultDataConfig });
+* createPlugin("content", { config: defaultContentConfig });
 * ```
 */
-const defaultDataConfig = {
-	outputDir: "_data",
-	baseUrl: "/_data/"
-};
+const defaultContentConfig = { providers: [] };
 //#endregion
-//#region src/plugins/data/state.ts
+//#region src/plugins/content/events.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).
+* Registers the content plugin's notification-only events (`content:ready`,
+* `content:invalidated`) with their typed payloads. Referenced as the plugin's
+* `events` callback so index.ts stays wiring-only.
+*
+* @param register - Kernel-provided typed event registrar.
+* @returns The content event descriptor map.
+* @example
+* ```ts
+* createPlugin("content", { events: contentEvents });
+* ```
+*/
+const contentEvents = (register) => ({
+	"content:ready": register("All articles loaded across locales"),
+	"content:invalidated": register("Article paths marked stale for dev rebuild")
+});
+//#endregion
+//#region src/plugins/content/state.ts
+/**
+* Creates initial content plugin shell state — an empty article cache. The lazy
+* unified processor + discovery caches live in the provider, not here.
 *
 * @param _ctx - Minimal context with global and config.
-* @param _ctx.global - Global framework configuration.
+* @param _ctx.global - Global plugin registry.
 * @param _ctx.config - Resolved plugin configuration.
-* @returns Fresh data state with no recorded write and an empty per-path cache.
+* @returns Fresh content shell state: an empty article cache.
 * @example
 * ```ts
-* const state = createDataState({ global: {}, config });
+* const state = createContentState({ global: {}, config: { providers: [] } });
 * ```
 */
-function createDataState(_ctx) {
-	return {
-		lastWrite: null,
-		cache: /* @__PURE__ */ new Map()
-	};
+function createContentState(_ctx) {
+	return { articles: /* @__PURE__ */ new Map() };
 }
 //#endregion
-//#region src/plugins/data/validate.ts
+//#region src/plugins/content/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.
+* Validates the resolved content config (fail-fast at `createApp`). Throws when no
+* content provider is composed — content is useless without a source. Errors use the
+* `[web]` prefix. (Per-provider options like `contentDir` are validated by the provider.)
 *
-* @param config - The resolved plugin configuration.
-* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @param config - Resolved content plugin configuration.
+* @throws {Error} If `providers` is empty.
 * @example
 * ```ts
-* validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
+* validateContentConfig(config);
 * ```
 */
-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/").`);
+function validateContentConfig(config) {
+	if (!Array.isArray(config.providers) || config.providers.length === 0) throw new Error("[web] content: no provider composed.\n  Add fileSystemContent(...) to pluginConfigs.content.providers.");
 }
 //#endregion
-//#region src/plugins/data/index.ts
+//#region src/plugins/content/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).
+* @file content — Complex Plugin skeleton (wiring-only).
 *
-* **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`.
+* Markdown pipeline: discover, parse frontmatter, render to sanitized HTML, and
+* expose a locale-keyed Article model. Depends on i18n. Emits `content:ready`
+* and `content:invalidated`.
 * @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`.
+* Content plugin (shell) — provider-driven locale-keyed Article model. Orchestration
+* (locale fallback, draft filtering, sort, caching, events) lives here; source I/O +
+* the Markdown pipeline live in a {@link ContentProvider} you compose (like `env`
+* providers). The shell imports zero node code, so `contentPlugin` is browser-safe.
+* Depends on i18n; emits `content:ready` and `content:invalidated`.
 *
-* @example
+* @example Compose the node filesystem provider with a content dir + Shiki theme
 * ```ts
-* // Node build: `build` calls app.data.write(...) during its pages phase when
-* // router.mode !== "ssg". Just compose the plugin:
+* import { contentPlugin, fileSystemContent } from "@moku-labs/web";
 * const app = createApp({
-*   plugins: [dataPlugin, contentPlugin, buildPlugin],
-*   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+*   plugins: [contentPlugin],
+*   pluginConfigs: {
+*     content: {
+*       providers: [fileSystemContent({ contentDir: "./content", shikiTheme: "github-dark", defaultAuthor: "Ada" })]
+*     }
+*   }
 * });
-* 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
+const contentPlugin = createPlugin$1("content", {
+	depends: [i18nPlugin],
+	events: contentEvents,
+	config: defaultContentConfig,
+	createState: createContentState,
+	onInit: (ctx) => validateContentConfig(ctx.config),
+	api: contentApi
 });
 //#endregion
-//#region src/plugins/data/types.ts
+//#region src/plugins/content/types.ts
 var types_exports = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/env/types.ts
+//#region src/plugins/data/types.ts
 var types_exports$1 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/head/types.ts
+//#region src/plugins/env/types.ts
 var types_exports$2 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/log/types.ts
+//#region src/plugins/head/types.ts
 var types_exports$3 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/router/types.ts
+//#region src/plugins/log/types.ts
 var types_exports$4 = /* @__PURE__ */ __exportAll({});
 //#endregion
+//#region src/plugins/router/types.ts
+var types_exports$5 = /* @__PURE__ */ __exportAll({});
+//#endregion
 //#region src/browser.ts
 /**
 * @file `@moku-labs/web/browser` — the browser-safe entry point.
@@ -3842,20 +4613,16 @@ const core = createCore(coreConfig, {
 *
 * @param options - Optional configuration:
 *  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
-*  - `config` — global framework config (e.g. `{ mode: "development" }`).
+*  - `config` — global framework config (e.g. `{ mode: "spa" }`).
 *  - `plugins` — extra plugins (e.g. `dataPlugin` 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
 * // Client SPA — env works with no wiring (browserEnv is the default provider):
-* const app = createApp({
-*   plugins: [dataPlugin],
-*   pluginConfigs: {
-*     router: { mode: "spa", routes: defineRoutes({ home: route("/"), post: route("/blog/{slug}/") }) }
-*   }
-* });
-* await app.start();
+* import * as routes from "./routes";
+* const app = createApp({ config: { mode: "spa" }, pluginConfigs: { router: { routes } } });
+* await app.start();             // routes compiled at init from config
 * app.env.get("PUBLIC_API_URL"); // resolved from import.meta.env
 * ```
 */
@@ -3877,4 +4644,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Data, types_exports$1 as Env, types_exports$2 as Head, types_exports$3 as Log, types_exports$4 as Router, types_exports$5 as Spa, browserEnv, buildArticleHead, canonical, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };