@moku-labs/web 0.4.2 → 0.5.1

package/dist/browser.mjs

@@ -0,0 +1,3866 @@
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { t as dataSuffix } from "./convention-X3zLTlJ8.mjs";
+import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
+//#region src/plugins/env/api.ts
+/** Error prefix for all env API failures. */
+const ERROR_PREFIX$10 = "[web]";
+/**
+* Creates the env plugin API surface mounted at `ctx.env`. Closes over
+* `ctx.state` ({@link EnvState}) and reads the frozen `resolved` / `publicMap`
+* maps; closures never return a raw `ctx.state` reference.
+*
+* @param ctx - Core plugin context carrying the frozen env state.
+* @param ctx.state - The resolved + public {@link EnvState} maps.
+* @returns The {@link EnvApi} accessor surface mounted at `ctx.env`.
+* @example
+* ```ts
+* const api = createEnvApi(ctx);
+* api.get("PUBLIC_API_URL");
+* ```
+*/
+function createEnvApi(ctx) {
+	const { resolved, publicMap } = ctx.state;
+	return {
+		/**
+		* Reads a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns The value, or `undefined` if not present.
+		* @example
+		* ```ts
+		* api.get("PUBLIC_API_URL");
+		* ```
+		*/
+		get(key) {
+			return resolved.get(key);
+		},
+		/**
+		* Reads a variable that must exist.
+		*
+		* @param key - Variable name.
+		* @returns The value.
+		* @throws {Error} If the variable is undefined.
+		* @example
+		* ```ts
+		* api.require("DEPLOY_TOKEN");
+		* ```
+		*/
+		require(key) {
+			const value = resolved.get(key);
+			if (value === void 0) throw new Error(`${ERROR_PREFIX$10} env: required variable "${key}" is not defined.`);
+			return value;
+		},
+		/**
+		* Tests presence of a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns `true` if a value is present.
+		* @example
+		* ```ts
+		* api.has("PUBLIC_API_URL");
+		* ```
+		*/
+		has(key) {
+			return resolved.has(key);
+		},
+		/**
+		* Returns all public variables as a frozen plain object — a fresh copy,
+		* never the raw state map.
+		*
+		* @returns A frozen `Record` of public variable names to values.
+		* @example
+		* ```ts
+		* const payload = { ...api.getPublic() };
+		* ```
+		*/
+		getPublic() {
+			return Object.freeze(Object.fromEntries(publicMap));
+		},
+		/**
+		* Returns the already-frozen map of public variables.
+		*
+		* @returns The frozen public map.
+		* @example
+		* ```ts
+		* [...api.getPublicMap()];
+		* ```
+		*/
+		getPublicMap() {
+			return publicMap;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/env/state.ts
+/**
+* Creates initial env plugin state: two empty, mutable maps that are populated
+* and frozen by `validateSchema` (the `onInit`) at `createApp` time.
+*
+* @returns A fresh `EnvState` with empty `resolved` and `publicMap` maps.
+* @example
+* ```ts
+* const state = createEnvState();
+* state.resolved.size; // 0
+* ```
+*/
+function createEnvState() {
+	return {
+		resolved: /* @__PURE__ */ new Map(),
+		publicMap: /* @__PURE__ */ new Map()
+	};
+}
+//#endregion
+//#region src/plugins/env/validate.ts
+/** Error message thrown by every frozen-map mutator. */
+const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
+/** Error prefix for all resolution-pipeline failures. */
+const ERROR_PREFIX$9 = "[web]";
+/**
+* Throws the canonical frozen-map error; installed as a map's `set`/`clear`/`delete`.
+*
+* @throws {TypeError} Always, signalling the map is frozen.
+* @example
+* ```ts
+* frozenThrower(); // throws TypeError
+* ```
+*/
+function frozenThrower() {
+	throw new TypeError(FROZEN_MESSAGE);
+}
+/**
+* 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.
+*
+* @param config - The resolved env config carrying the ordered providers.
+* @returns A flat record of the first defined value found per key.
+* @example
+* ```ts
+* mergeProviders({ providers: [a, b], schema: {}, publicPrefix: "PUBLIC_" });
+* ```
+*/
+function mergeProviders(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;
+		}
+	}
+	return merged;
+}
+/**
+* Bidirectionally enforces the `PUBLIC_` naming convention against each schema
+* entry's `public` flag. Throws on either violation direction.
+*
+* @param config - The resolved env config carrying `schema` + `publicPrefix`.
+* @throws {Error} If a public var lacks the prefix, or a prefixed var is not public.
+* @example
+* ```ts
+* crossCheckPublicPrefix(config); // throws if PUBLIC_X is not public:true
+* ```
+*/
+function crossCheckPublicPrefix(config) {
+	const { schema, publicPrefix } = config;
+	for (const [key, spec] of Object.entries(schema)) {
+		const hasPrefix = key.startsWith(publicPrefix);
+		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$9} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
+		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$9} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
+	}
+}
+/**
+* Seals a map so `set`, `clear`, and `delete` throw, then `Object.freeze`s it
+* for defense in depth. Closes the `Object.freeze`-on-`Map` mutability hole by
+* redefining the mutators as non-writable, non-configurable throwers.
+*
+* @param map - The map to freeze in place.
+* @example
+* ```ts
+* freezeMap(state.resolved); // resolved.set(...) now throws
+* ```
+*/
+function freezeMap(map) {
+	for (const method of [
+		"set",
+		"clear",
+		"delete"
+	]) Object.defineProperty(map, method, {
+		value: frozenThrower,
+		writable: false,
+		configurable: false,
+		enumerable: false
+	});
+	Object.freeze(map);
+}
+/**
+* Resolves, validates, and freezes the environment table at `onInit`.
+*
+* Pipeline order: merge providers (with empty-string → undefined coercion) →
+* `PUBLIC_` bidirectional cross-check → apply defaults → assert required →
+* populate `state.resolved` / `state.publicMap` → freeze both via
+* {@link freezeMap}. Fail-fast: any violation throws at `createApp` time.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @param ctx.config - The resolved {@link EnvConfig}.
+* @param ctx.state - The mutable {@link EnvState} to populate and freeze.
+* @throws {Error} On a `PUBLIC_` cross-check violation or a missing required variable.
+* @example
+* ```ts
+* validateSchema(ctx); // throws on missing required / PUBLIC_ violation
+* ```
+*/
+function validateSchema(ctx) {
+	const { config, state } = ctx;
+	const { schema } = config;
+	const merged = mergeProviders(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);
+	freezeMap(state.resolved);
+	freezeMap(state.publicMap);
+}
+//#endregion
+//#region src/plugins/env/providers.browser.ts
+/** Default `globalThis` property holding a runtime-injected public-env snapshot. */
+const DEFAULT_GLOBAL_KEY = "__ENV__";
+/**
+* A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+* `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+* Contains zero `node:*` imports, so it is safe to include in the client bundle.
+* Never throws on missing sources — each absent source resolves to `{}`.
+*
+* @param options - Optional settings.
+* @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+* @returns An {@link EnvProvider} named `browser-env`.
+* @example
+* ```ts
+* const provider = browserEnv();
+* provider.load(); // { PUBLIC_API_URL: "/api", ... }
+* ```
+*/
+function browserEnv(options) {
+	const globalKey = options?.globalKey ?? DEFAULT_GLOBAL_KEY;
+	return {
+		name: "browser-env",
+		/**
+		* Merges `import.meta.env` with `globalThis[globalKey]`, the runtime global
+		* winning. Each absent source resolves to `{}`; never throws.
+		*
+		* @returns The merged environment record.
+		* @example
+		* ```ts
+		* browserEnv().load();
+		* ```
+		*/
+		load() {
+			const importEnv = import.meta.env ?? {};
+			const globalObject = globalThis[globalKey] ?? {};
+			return {
+				...importEnv,
+				...globalObject
+			};
+		}
+	};
+}
+/**
+* Core plugin that resolves, validates, and freezes the environment at `onInit`,
+* exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
+*
+* @example
+* ```ts
+* createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
+* ```
+*/
+const envPlugin = createCorePlugin("env", {
+	config: {
+		schema: {},
+		providers: [],
+		publicPrefix: "PUBLIC_"
+	},
+	createState: createEnvState,
+	api: createEnvApi,
+	onInit: validateSchema
+});
+//#endregion
+//#region src/plugins/log/expect.ts
+/**
+* Named error thrown by `expect()` assertions when a trace condition fails.
+*
+* @example
+* ```ts
+* throw new LogExpectAssertionError("missing event build:complete");
+* ```
+*/
+var LogExpectAssertionError = class extends Error {
+	/**
+	* Construct a new assertion error with a descriptive failure message.
+	*
+	* @param message - Descriptive failure message (event name, partial, index).
+	* @example
+	* ```ts
+	* throw new LogExpectAssertionError("missing event build:complete");
+	* ```
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "LogExpectAssertionError";
+	}
+};
+/**
+* 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);
+}
+/**
+* Subset-equality matcher: is `partial` a recursive subset of `actual`?
+*
+* Fast path via `Object.is` (covers identical primitives/references and
+* `null`/`NaN`); primitives compare with `Object.is`; arrays match element-wise
+* with equal length; plain objects require every `partial` key to recursively
+* match (extra `actual` keys ignored).
+*
+* @param actual - The value to test against (typically `entry.data`).
+* @param partial - The expected partial shape.
+* @returns `true` when `partial` is a recursive subset of `actual`.
+* @example
+* ```ts
+* matchesPartial({ a: 1, b: 2 }, { a: 1 }); // true
+* matchesPartial([1, 2], [1]); // false (length mismatch)
+* ```
+*/
+function matchesPartial(actual, partial) {
+	if (Object.is(actual, partial)) return true;
+	if (Array.isArray(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;
+		return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
+	}
+	return false;
+}
+/**
+* Tests whether an entry matches `event` and (when provided) `partial`.
+*
+* @param entry - The candidate trace entry.
+* @param event - Required event name.
+* @param partial - Optional partial data shape (subset-matched against `entry.data`).
+* @returns `true` when the entry matches the event and optional partial.
+* @example
+* ```ts
+* entryMatches({ level: "info", event: "a", data: { x: 1 }, ts: 0 }, "a", { x: 1 }); // true
+* ```
+*/
+function entryMatches(entry, event, partial) {
+	if (entry.event !== event) return false;
+	return partial === void 0 ? true : matchesPartial(entry.data, partial);
+}
+/**
+* Render a `partial` for an error message, prefixed with a space when present.
+*
+* @param partial - Optional partial data shape.
+* @returns A ` matching <json>` suffix, or an empty string when absent.
+* @example
+* ```ts
+* describePartial({ ok: true }); // ' matching {"ok":true}'
+* ```
+*/
+function describePartial(partial) {
+	return partial === void 0 ? "" : ` matching ${JSON.stringify(partial)}`;
+}
+/**
+* Create a fluent assertion chain bound to the live `entries` array. Each method
+* reads `entries` at call time, so assertions reflect later logging.
+*
+* @param entries - The live trace array (read on each assertion call).
+* @returns A fresh {@link ExpectChain} backed by `entries`.
+* @example
+* ```ts
+* createExpectChain(state.entries).toHaveEvent("build:complete");
+* ```
+*/
+function createExpectChain(entries) {
+	const chain = {
+		/**
+		* Assert at least one entry has `event`, optionally matching `partial`.
+		*
+		* @param event - Event name to find.
+		* @param partial - Optional partial data shape (subset-matched).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When no matching entry exists.
+		* @example
+		* ```ts
+		* chain.toHaveEvent("build:phase", { status: "start" });
+		* ```
+		*/
+		toHaveEvent(event, partial) {
+			if (!entries.some((entry) => entryMatches(entry, event, partial))) throw new LogExpectAssertionError(`Expected trace to contain event "${event}"${describePartial(partial)}, but none was found.`);
+			return chain;
+		},
+		/**
+		* Assert all of `events` appear in the trace in the given relative order.
+		*
+		* @param events - Ordered list of event names (gaps allowed).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When the ordering cannot be satisfied.
+		* @example
+		* ```ts
+		* chain.toHaveEventInOrder(["build:phase", "build:complete"]);
+		* ```
+		*/
+		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;
+			}
+			return chain;
+		},
+		/**
+		* Assert NO entry has `event` (optionally narrowed by `partial`).
+		*
+		* @param event - Event name that must be absent.
+		* @param partial - Optional partial data shape; only matching entries violate.
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When a matching entry exists.
+		* @example
+		* ```ts
+		* chain.toNotHaveEvent("deploy:failed");
+		* ```
+		*/
+		toNotHaveEvent(event, partial) {
+			const offending = entries.findIndex((entry) => entryMatches(entry, event, partial));
+			if (offending !== -1) throw new LogExpectAssertionError(`Expected trace to NOT contain event "${event}"${describePartial(partial)}, but found one at index ${offending}.`);
+			return chain;
+		}
+	};
+	return chain;
+}
+//#endregion
+//#region src/plugins/log/api.ts
+/**
+* @file log plugin — API factory.
+*
+* Builds the `LogApi` over the plugin's `{ config, state }` core context:
+* the leveled loggers (via a shared `append`), the frozen `trace()` snapshot,
+* the live `expect()` chain, `addSink`, and `reset`.
+*/
+/**
+* Append a new entry to the trace and fan it out to every sink in order.
+*
+* @param state - The mutable log state to append to.
+* @param level - Severity level for the entry.
+* @param event - Event identifier.
+* @param data - Optional structured payload.
+* @example
+* ```ts
+* append(state, "info", "content:ready", { count: 12 });
+* ```
+*/
+function append(state, level, event, data) {
+	const entry = {
+		level,
+		event,
+		data,
+		ts: Date.now()
+	};
+	state.entries.push(entry);
+	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.
+*
+* @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.
+* @example
+* ```ts
+* mergeError({ target: "cf" }, new Error("boom"));
+* // { target: "cf", error: { message: "boom", stack: "..." } }
+* ```
+*/
+function mergeError(data, error) {
+	return {
+		...typeof data === "object" && data !== null && !Array.isArray(data) ? data : {},
+		error: {
+			message: error.message,
+			stack: error.stack
+		}
+	};
+}
+/**
+* Create the log plugin API surface injected as `ctx.log` / `app.log`.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @returns The {@link LogApi} bound to `ctx.state`.
+* @example
+* ```ts
+* const log = createLogApi(ctx);
+* log.info("content:ready", { articleCount: 12 });
+* ```
+*/
+function createLogApi(ctx) {
+	const { state } = ctx;
+	return {
+		/**
+		* Append an `info` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.info("content:ready", { count: 12 });
+		* ```
+		*/
+		info(event, data) {
+			append(state, "info", event, data);
+		},
+		/**
+		* Append a `debug` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.debug("router:match", { path: "/blog/" });
+		* ```
+		*/
+		debug(event, data) {
+			append(state, "debug", event, data);
+		},
+		/**
+		* Append a `warn` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.warn("build:skip", { reason: "no sitemap" });
+		* ```
+		*/
+		warn(event, data) {
+			append(state, "warn", event, data);
+		},
+		/**
+		* Append an `error` entry. When `error` is provided, its `message`/`stack`
+		* are merged into `data` under an `error` key (existing keys preserved);
+		* otherwise `data` is recorded as-is.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @param error - Optional originating Error to merge into `data`.
+		* @example
+		* ```ts
+		* log.error("deploy:failed", { target: "cf" }, err);
+		* ```
+		*/
+		error(event, data, error) {
+			append(state, "error", event, error === void 0 ? data : mergeError(data, error));
+		},
+		/**
+		* Return a frozen snapshot (fresh copy) of the entries recorded so far.
+		*
+		* @returns A readonly, frozen copy of the recorded entries.
+		* @example
+		* ```ts
+		* const entries = log.trace();
+		* ```
+		*/
+		trace() {
+			return Object.freeze([...state.entries]);
+		},
+		/**
+		* Return a fluent assertion chain bound to the live entries array.
+		*
+		* @returns A fresh {@link ExpectChain} reading `state.entries` live.
+		* @example
+		* ```ts
+		* log.expect().toHaveEvent("build:complete");
+		* ```
+		*/
+		expect() {
+			return createExpectChain(state.entries);
+		},
+		/**
+		* Register an additional output sink at runtime.
+		*
+		* @param sink - The sink to add to the fan-out list.
+		* @example
+		* ```ts
+		* log.addSink({ write: (e) => stream.write(JSON.stringify(e)) });
+		* ```
+		*/
+		addSink(sink) {
+			state.sinks.push(sink);
+		},
+		/**
+		* Clear all recorded entries while keeping registered sinks.
+		*
+		* @example
+		* ```ts
+		* log.reset();
+		* ```
+		*/
+		reset() {
+			state.entries.length = 0;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/log/sinks.ts
+/**
+* Build the console sink: routes entries by channel — `error` → `console.error`,
+* `warn` → `console.warn`, and `debug`/`info` → `console.log`. The full entry
+* object is forwarded so the console serializes its `event` and `data`.
+*
+* @returns A {@link LogSink} that writes to the matching `console` channel.
+* @example
+* ```ts
+* state.sinks.push(consoleSink());
+* ```
+*/
+function consoleSink() {
+	return { 
+	/**
+	* Route a single entry to the console channel matching its level.
+	*
+	* @param entry - The entry to emit.
+	* @example
+	* ```ts
+	* sink.write({ level: "warn", event: "build:skip", ts: Date.now() });
+	* ```
+	*/
+write(entry) {
+		if (entry.level === "error") console.error(entry);
+		else if (entry.level === "warn") console.warn(entry);
+		else console.log(entry);
+	} };
+}
+/**
+* Install mode-selected default sinks at onInit. The in-memory trace is always
+* on (`state.entries`); the console sink is added only in dev/production.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @param ctx.config - Resolved log config (`{ mode }`).
+* @param ctx.state - Mutable log state (`{ entries, sinks }`).
+* @example
+* ```ts
+* // mode "dev" -> state.sinks === [consoleSink()]; mode "test" -> state.sinks === []
+* ```
+*/
+function installDefaultSinks(ctx) {
+	if (ctx.config.mode === "dev" || ctx.config.mode === "production") ctx.state.sinks.push(consoleSink());
+}
+//#endregion
+//#region src/plugins/log/state.ts
+/**
+* Create fresh log state: an empty append-only trace and an empty sink list.
+* No module-level singletons — guarantees per-`createApp` isolation (two
+* `createApp` calls never share `entries` or `sinks`).
+*
+* @param _ctx - Core plugin context (`{ config }`); unused at construction.
+* @returns A fresh `LogState` with empty `entries` and `sinks` arrays.
+* @example
+* ```ts
+* const state = createLogState({ config: { mode: "test" } }); // { entries: [], sinks: [] }
+* ```
+*/
+function createLogState(_ctx) {
+	return {
+		entries: [],
+		sinks: []
+	};
+}
+/**
+* Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
+* API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
+* No depends / events / hooks (core plugin per spec/03 §5).
+*
+* @see README.md
+*/
+const logPlugin = createCorePlugin("log", {
+	config: { mode: "production" },
+	createState: createLogState,
+	api: createLogApi,
+	onInit: installDefaultSinks
+});
+//#endregion
+//#region src/config.ts
+/**
+* @file Framework configuration — Config + Events types, core plugin registration.
+* @see README.md
+*/
+const coreConfig = createCoreConfig("web", {
+	config: { mode: "production" },
+	plugins: [logPlugin, envPlugin],
+	pluginConfigs: { log: { mode: "production" } }
+});
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and the core
+* plugin APIs (`log`, `env`). Plugin types are fully inferred from the spec
+* object — never write them explicitly. This is the binding every built-in
+* plugin is wired with, and the one consumer plugins should use too.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+* ```
+*/
+const createPlugin$1 = coreConfig.createPlugin;
+/**
+* Step 2 of the factory chain — captures the framework's default plugin set and
+* returns the consumer entry points ({@link createApp} + a re-exported
+* `createPlugin`). Wired once in `src/index.ts`; consumers don't call it directly.
+*/
+const createCore = coreConfig.createCore;
+//#endregion
+//#region src/plugins/i18n/api.ts
+/** Error prefix for all i18n lifecycle failures. */
+const ERROR_PREFIX$8 = "[web]";
+/**
+* Validates the resolved i18n config (fail-fast at `createApp`). Throws when
+* `locales` is empty or when `defaultLocale` is not a member of `locales`.
+* Errors use the `[web]` prefix with an actionable remediation line.
+*
+* @param ctx - Plugin context carrying the resolved {@link Config}.
+* @param ctx.config - The resolved i18n {@link Config}.
+* @throws {Error} If `locales` is empty or `defaultLocale` is not in `locales`.
+* @example
+* ```ts
+* validateI18nConfig({ config: { locales: ["en"], defaultLocale: "en" } });
+* ```
+*/
+function validateI18nConfig(ctx) {
+	const { locales, defaultLocale } = ctx.config;
+	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$8} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
+	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$8} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
+}
+/**
+* Creates the i18n plugin API surface — locale registry accessors plus the
+* `t()` translator with default-locale fallback. Every method is a pure read
+* of `ctx.config`; none mutate, and `t()` always returns a string.
+*
+* @param ctx - Plugin context carrying the resolved {@link Config}.
+* @param ctx.config - The resolved i18n {@link Config}.
+* @returns The {@link Api} accessor surface mounted at `app.i18n`.
+* @example
+* ```ts
+* const api = createI18nApi({ config: { locales: ["en"], defaultLocale: "en" } });
+* api.t("en", "nav.home");
+* ```
+*/
+function createI18nApi(ctx) {
+	const { config } = ctx;
+	return {
+		/**
+		* Returns the configured supported locales in declared order.
+		*
+		* @returns The configured `locales` list (priority/display order).
+		* @example
+		* ```ts
+		* api.locales(); // ["en", "uk"]
+		* ```
+		*/
+		locales() {
+			return config.locales;
+		},
+		/**
+		* Returns the fallback locale used when a requested locale is absent.
+		*
+		* @returns The configured `defaultLocale`.
+		* @example
+		* ```ts
+		* api.defaultLocale(); // "en"
+		* ```
+		*/
+		defaultLocale() {
+			return config.defaultLocale;
+		},
+		/**
+		* Membership guard: whether `x` is one of the supported locales
+		* (case-sensitive).
+		*
+		* @param x - Candidate locale code.
+		* @returns `true` if `x ∈ locales`, else `false`.
+		* @example
+		* ```ts
+		* api.isLocale("uk"); // true
+		* ```
+		*/
+		isLocale(x) {
+			return config.locales.includes(x);
+		},
+		/**
+		* Human-readable display name for a locale.
+		*
+		* @param locale - Locale code to look up.
+		* @returns The display name, or `undefined` if unmapped.
+		* @example
+		* ```ts
+		* api.localeName("uk"); // "Українська"
+		* ```
+		*/
+		localeName(locale) {
+			return config.localeNames?.[locale];
+		},
+		/**
+		* Open Graph `og:locale` value for a locale.
+		*
+		* @param locale - Locale code to look up.
+		* @returns The `og:locale` value (e.g. `"en_US"`), or `undefined` if unmapped.
+		* @example
+		* ```ts
+		* api.ogLocale("en"); // "en_US"
+		* ```
+		*/
+		ogLocale(locale) {
+			return config.ogLocaleMap?.[locale];
+		},
+		/**
+		* Translate `key` for `locale` with a deterministic fallback chain
+		* (requested locale → default locale → the key itself). The default-locale
+		* lookup is skipped when `locale === defaultLocale`.
+		*
+		* @param locale - Requested locale code.
+		* @param key - Translation key (e.g. `"nav.home"`).
+		* @returns The translated value, the default-locale value, or `key`.
+		* @example
+		* ```ts
+		* api.t("uk", "nav.home"); // "Головна"
+		* ```
+		*/
+		t(locale, key) {
+			const exact = config.translations?.[locale]?.[key];
+			if (exact !== void 0) return exact;
+			if (locale !== config.defaultLocale) {
+				const fallback = config.translations?.[config.defaultLocale]?.[key];
+				if (fallback !== void 0) return fallback;
+			}
+			return key;
+		}
+	};
+}
+/**
+* Internationalization plugin — locale registry plus a flat translation helper
+* with default-locale fallback. Pure config-as-data (no state or events);
+* consumed read-only by content, router, head, and build.
+*
+* @example Register locales and translations
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     i18n: {
+*       locales: ["en", "uk"],
+*       defaultLocale: "en",
+*       localeNames: { en: "English", uk: "Українська" },
+*       translations: { uk: { "nav.home": "Головна" } }
+*     }
+*   }
+* });
+* ```
+*/
+const i18nPlugin = createPlugin$1("i18n", {
+	config: {
+		locales: ["en"],
+		defaultLocale: "en",
+		localeNames: {},
+		ogLocaleMap: {},
+		translations: {}
+	},
+	onInit: validateI18nConfig,
+	api: createI18nApi
+});
+//#endregion
+//#region src/plugins/site/api.ts
+/** Error prefix for all site lifecycle/validation failures. */
+const ERROR_PREFIX$7 = "[web]";
+/**
+* Joins a relative path against an absolute base URL, normalizing the slash
+* boundary to exactly one "/". Returns the base unchanged for an empty or
+* root ("/") path; the supplied path's own trailing slash is preserved.
+*
+* @param base - Absolute base URL from config (may have trailing slash).
+* @param path - Relative path to join (may have leading slash).
+* @returns The joined absolute URL with no double slash at the boundary.
+* @example
+* ```ts
+* joinCanonical("https://blog.dev/", "/about/"); // "https://blog.dev/about/"
+* ```
+*/
+function joinCanonical(base, path) {
+	let trimmedBase = base;
+	while (trimmedBase.endsWith("/")) trimmedBase = trimmedBase.slice(0, -1);
+	if (path === "" || path === "/") return trimmedBase;
+	let trimmedPath = path;
+	while (trimmedPath.startsWith("/")) trimmedPath = trimmedPath.slice(1);
+	return `${trimmedBase}/${trimmedPath}`;
+}
+/**
+* Validates that a string is a non-empty trimmed value.
+*
+* @param value - The value to test.
+* @returns `true` if the value is a non-empty (trimmed) string.
+* @example
+* ```ts
+* isNonEmpty("  "); // false
+* ```
+*/
+function isNonEmpty(value) {
+	return value.trim().length > 0;
+}
+/**
+* Validates that a string is a parseable absolute http/https URL.
+*
+* @param value - The candidate URL string.
+* @returns `true` if `value` is an absolute http/https URL.
+* @example
+* ```ts
+* isAbsoluteUrl("https://blog.dev"); // true
+* ```
+*/
+function isAbsoluteUrl(value) {
+	try {
+		const parsed = new URL(value);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates the resolved config (fail-fast at `createApp`, synchronous). Throws
+* if `config.name` is empty/whitespace-only, or if `config.url` is not a valid
+* absolute http/https URL. On success, returns without side effects (the plugin
+* manages no resource). Errors use the `[web] site.<field> ...` format.
+*
+* @param ctx - Plugin context.
+* @param ctx.config - The resolved {@link Config} to validate.
+* @throws {Error} If `name` is blank or `url` is not an absolute http/https URL.
+* @example
+* ```ts
+* validateSiteConfig({ config }); // throws on blank name / bad url
+* ```
+*/
+function validateSiteConfig(ctx) {
+	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$7} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
+	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$7} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
+}
+/**
+* Creates the site plugin API surface — read-only accessors over frozen config
+* plus the `canonical` helper. Closures read directly from `ctx.config`; none
+* mutate or emit, and they return primitives, never internal references.
+*
+* @param ctx - Plugin context.
+* @param ctx.config - The frozen {@link Config} read by every accessor.
+* @returns The {@link Api} accessor surface mounted at `ctx.site`.
+* @example
+* ```ts
+* const api = createSiteApi({ config });
+* api.canonical("/about/"); // "https://blog.dev/about/"
+* ```
+*/
+function createSiteApi(ctx) {
+	const { config } = ctx;
+	return {
+		/**
+		* Returns the configured site name.
+		*
+		* @returns The human-readable site name from `config.name`.
+		* @example
+		* ```ts
+		* api.name(); // "My Blog"
+		* ```
+		*/
+		name() {
+			return config.name;
+		},
+		/**
+		* Returns the configured absolute base URL of the site.
+		*
+		* @returns The base URL from `config.url`.
+		* @example
+		* ```ts
+		* api.url(); // "https://blog.dev"
+		* ```
+		*/
+		url() {
+			return config.url;
+		},
+		/**
+		* Returns the configured site author/byline.
+		*
+		* @returns The author from `config.author`.
+		* @example
+		* ```ts
+		* api.author(); // "Alex"
+		* ```
+		*/
+		author() {
+			return config.author;
+		},
+		/**
+		* Returns the configured site description.
+		*
+		* @returns The description from `config.description`.
+		* @example
+		* ```ts
+		* api.description(); // "A personal blog about web frameworks."
+		* ```
+		*/
+		description() {
+			return config.description;
+		},
+		/**
+		* Joins a path against the configured base `url` to produce an absolute
+		* canonical URL. An empty path (or "/") returns the base URL unchanged.
+		*
+		* @param path - Relative path for the page, e.g. "/about/".
+		* @returns The absolute canonical URL.
+		* @example
+		* ```ts
+		* api.canonical("/about/"); // "https://blog.dev/about/"
+		* ```
+		*/
+		canonical(path) {
+			return joinCanonical(config.url, path);
+		}
+	};
+}
+/**
+* Site plugin — holds global, frozen site metadata (name, url, author,
+* description) and builds canonical URLs. Consumed by router, head, and build.
+* `name` and `url` must be non-empty (validated at `onInit`).
+*
+* @example Set your site identity
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: {
+*       name: "My Blog",
+*       url: "https://blog.dev",
+*       author: "Ada Lovelace",
+*       description: "Notes on computing"
+*     }
+*   }
+* });
+* ```
+*/
+const sitePlugin = createPlugin$1("site", {
+	config: {
+		name: "",
+		url: "",
+		author: "",
+		description: ""
+	},
+	onInit: validateSiteConfig,
+	api: createSiteApi
+});
+//#endregion
+//#region src/plugins/router/builders/match.ts
+/**
+* Extract named groups from a `URLPattern` match result, stripping numeric/regex
+* group keys so only declared param names remain.
+*
+* @param groups - The `URLPatternResult.pathname.groups` object.
+* @returns A clean record of named params (numeric keys + undefined values dropped).
+* @example
+* ```ts
+* extractParams({ slug: "hello", "0": "x" }); // { slug: "hello" }
+* ```
+*/
+function extractParams(groups) {
+	const params = {};
+	for (const [key, value] of Object.entries(groups)) {
+		if (/^\d+$/.test(key)) continue;
+		if (value !== void 0) params[key] = value;
+	}
+	return params;
+}
+/**
+* Build a pathname matcher for a single route: tries the `withLang` URLPattern,
+* then the `bare` pattern injecting `defaultLocale` on miss.
+*
+* @param matchers - The pre-built `withLang` and `bare` URLPattern pair.
+* @param matchers.withLang - The locale-aware URLPattern variant.
+* @param matchers.bare - The bare URLPattern variant (no leading locale segment).
+* @param defaultLocale - Locale injected when the bare fallback matches.
+* @returns A function resolving a pathname into params, or `null` on no match.
+* @example
+* ```ts
+* const matchFn = createMatchFunction(matchers, "en");
+* ```
+*/
+function createMatchFunction(matchers, defaultLocale) {
+	return (pathname) => {
+		const withLang = matchers.withLang.exec({ pathname });
+		if (withLang) return extractParams(withLang.pathname.groups);
+		const bare = matchers.bare.exec({ pathname });
+		if (bare) {
+			const params = extractParams(bare.pathname.groups);
+			params.lang = defaultLocale;
+			return params;
+		}
+		return null;
+	};
+}
+/**
+* Scan the specificity-sorted compiled routes and return the first match.
+*
+* @param compiled - The compiled routes, sorted by specificity (most specific first).
+* @param pathname - The pathname to match.
+* @returns `{ params, route }` for the first matching route, or `null`.
+* @example
+* ```ts
+* matchRoute(compiled, "/en/hello/");
+* ```
+*/
+function matchRoute(compiled, pathname) {
+	for (const entry of compiled) {
+		const params = entry.matchFn(pathname);
+		if (params) return {
+			params,
+			route: entry.definition
+		};
+	}
+	return null;
+}
+//#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$6 = "[web] router";
+/**
+* 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$6}: matcher table accessed before onInit compiled it.`);
+	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$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("/") });
+* ```
+*/
+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.`);
+	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}").`);
+	}
+}
+/**
+* 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).
+*
+* @param pattern - The user pattern, e.g. `/{lang:?}/{slug}/`.
+* @param variant - `"withLang"` (locale regex injected) or `"bare"`.
+* @param langRegex - Locale alternation regex, e.g. `(en|uk)`.
+* @returns A URLPattern-compatible pathname string.
+* @example
+* ```ts
+* patternToUrlPattern("/{slug}/", "bare", "(en|uk)");
+* ```
+*/
+function patternToUrlPattern(pattern, variant, langRegex) {
+	const out = [];
+	for (const segment of pattern.split("/")) {
+		const placeholder = parsePlaceholder(segment);
+		if (!placeholder) {
+			out.push(segment);
+			continue;
+		}
+		if (placeholder.name === "lang" && placeholder.optional) {
+			if (variant === "withLang") out.push(`:lang${langRegex}`);
+			continue;
+		}
+		out.push(`:${placeholder.name}`);
+	}
+	return out.join("/");
+}
+/**
+* Build a URL from a pattern and params (substitutes `{param}` / `{param:?}`).
+* Walks segment-by-segment (no backtracking regex).
+*
+* @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");
+* ```
+*/
+function buildUrl(pattern, params, _baseUrl) {
+	const out = [];
+	for (const segment of pattern.split("/")) {
+		const placeholder = parsePlaceholder(segment);
+		out.push(placeholder ? params[placeholder.name] ?? "" : segment);
+	}
+	return out.join("/");
+}
+/**
+* Build an output file path from a pattern and params (always `…/index.html`).
+*
+* @param pattern - The route pattern.
+* @param params - Param values to substitute.
+* @returns The output file path, e.g. `hello/index.html`.
+* @example
+* ```ts
+* buildFilePath("/{slug}/", { slug: "hello" });
+* ```
+*/
+function buildFilePath(pattern, params) {
+	const cleanPath = buildUrl(pattern, params, "").replace(/^\//, "").replace(/\/$/, "");
+	return cleanPath === "" ? "index.html" : `${cleanPath}/index.html`;
+}
+/**
+* Compile a single route definition into its `CompiledRoute` entry.
+*
+* @param name - The route name key.
+* @param definition - The (opaque) route definition carrier.
+* @param input - Resolved compile data (locales, defaultLocale, baseUrl, …).
+* @returns The compiled route entry with matchers + URL utilities.
+* @example
+* ```ts
+* compileRoute("home", routeDef, input);
+* ```
+*/
+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) })
+	};
+	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);
+		},
+		definition,
+		meta: { ...definition._meta }
+	};
+}
+/**
+* Compile the route map into a specificity-sorted, immutable `MatcherTable`.
+* Builds both URLPattern variants per route, the `matchFn`, the `toUrl`/`toFile`
+* closures, and the `byName` index, then sorts ascending by dynamic-segment count
+* (stable, preserving declaration order among equal-specificity routes).
+*
+* @param input - Resolved DATA (routes, mode, baseUrl, locales, defaultLocale).
+* @returns The compiled, immutable matcher table.
+* @example
+* ```ts
+* compileRoutes({ routes: { home: route("/") }, mode: "hybrid", baseUrl: "https://blog.dev", locales: ["en"], defaultLocale: "en" });
+* ```
+*/
+function compileRoutes(input) {
+	const byName = /* @__PURE__ */ new Map();
+	const declarationOrder = [];
+	for (const [name, definition] of Object.entries(input.routes)) {
+		const entry = compileRoute(name, definition, input);
+		declarationOrder.push(entry);
+		byName.set(name, entry);
+	}
+	return {
+		compiled: declarationOrder.toSorted(bySpecificity),
+		byName
+	};
+}
+/**
+* onInit orchestrator (data-only seam, keeps `index.ts` wiring-only). Validates
+* the route map then compiles the matcher table from resolved dependency data.
+*
+* @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`.
+* @example
+* ```ts
+* ctx.state.table = buildRouterTable(ctx.config, site.url(), i18n.locales(), i18n.defaultLocale());
+* ```
+*/
+function buildRouterTable(config, baseUrl, locales, defaultLocale) {
+	validateRoutes(config.routes);
+	return compileRoutes({
+		routes: config.routes,
+		mode: config.mode ?? "hybrid",
+		baseUrl,
+		locales,
+		defaultLocale
+	});
+}
+//#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.
+*
+* @param pattern - URL pattern with `{param}` / `{param:?}` placeholders.
+* @returns A `RouteBuilder<RouteState<P>>` carrying the typed fluent chain.
+* @example
+* ```ts
+* route("/{lang:?}/{slug}/")
+*   .load(({ slug }) => loadArticle(slug))
+*   .render((ctx) => <Article a={ctx.data} />)
+*   .head((ctx) => ({ title: ctx.data.title }));
+* ```
+*/
+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,
+		/**
+		* Attach a data loader; widens the data generic for downstream handlers.
+		*
+		* @param loader - The loader producing this route's data.
+		* @returns The same builder, with the data generic widened.
+		* @example
+		* ```ts
+		* route("/{slug}/").load(({ slug }) => ({ slug }));
+		* ```
+		*/
+		load(loader) {
+			return set("load", loader);
+		},
+		/**
+		* Attach a ctx-aware layout wrapper that frames the page in persistent chrome.
+		* The wrapper receives the route's `LayoutContext` (render context + `.meta()`
+		* bag) and the page children. Applied in the SSG render path only — client
+		* navigation keeps the chrome and swaps just the inner region.
+		*
+		* @param component - The layout component `(ctx, children) => VNode`.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/")
+		*   .meta({ activeTab: "home" })
+		*   .layout((ctx, children) => (
+		*     <Shell locale={ctx.locale} active={ctx.meta.activeTab}>{children}</Shell>
+		*   ));
+		* ```
+		*/
+		layout(component) {
+			return set("layout", component);
+		},
+		/**
+		* Attach the page render handler.
+		*
+		* @param handler - The render handler.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").render(() => null);
+		* ```
+		*/
+		render(handler) {
+			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.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").head(() => ({ title: "Home" }));
+		* ```
+		*/
+		head(handler) {
+			return set("head", handler);
+		},
+		/**
+		* Attach a static-generation param producer.
+		*
+		* @param handler - The param producer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/{slug}/").generate(() => [{ slug: "x" }]);
+		* ```
+		*/
+		generate(handler) {
+			return set("generate", handler);
+		},
+		/**
+		* Merge an arbitrary metadata bag into the route's `_meta`. The bag MUST be
+		* JSON-serializable — it is projected verbatim into `clientManifest()` and
+		* shipped to the browser, so functions/symbols/class instances are unsupported.
+		*
+		* @param meta - JSON-serializable metadata to merge.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").meta({ activeTab: "home" });
+		* ```
+		*/
+		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;
+}
+/**
+* Typed identity helper for route maps. Preserves the precise literal type of the
+* route object for IntelliSense at the consumer call site (before config erasure).
+*
+* @param routes - The route map object.
+* @returns The same object, with its precise type preserved.
+* @example
+* ```ts
+* const routes = defineRoutes({ home: route("/"), article: route("/{slug}/") });
+* ```
+*/
+function defineRoutes(routes) {
+	return routes;
+}
+//#endregion
+//#region src/plugins/router/state.ts
+/**
+* Creates initial router plugin state — a holder whose `table` is `null` until
+* `onInit` compiles and assigns the matcher table.
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global plugin registry.
+* @param _ctx.config - Resolved router configuration.
+* @returns The initial router state holder.
+* @example
+* ```ts
+* const state = createState({ global: {}, config: { routes: {} } });
+* ```
+*/
+function createState$2(_ctx) {
+	return {
+		table: null,
+		mode: _ctx.config.mode ?? "hybrid"
+	};
+}
+/**
+* Router plugin — typed, named route definitions with locale-aware URL generation
+* and matching. Author routes with {@link route} + {@link defineRoutes}. Depends
+* on site (base URL) and i18n (locales).
+*
+* @example Define routes and choose a render mode
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     router: {
+*       routes: defineRoutes({
+*         home: route("/"),
+*         article: route("/blog/{slug}/")
+*       }),
+*       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
+*     }
+*   }
+* });
+* ```
+*/
+const routerPlugin = createPlugin$1("router", {
+	depends: [sitePlugin, i18nPlugin],
+	helpers: {
+		route,
+		defineRoutes
+	},
+	config: {
+		routes: {},
+		mode: "hybrid"
+	},
+	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());
+	}
+});
+//#endregion
+//#region src/plugins/head/primitives.ts
+/** OG/Twitter article-meta property prefixes (factored to satisfy no-duplicate-string). */
+const ARTICLE_PREFIX = "article:";
+/**
+* Build a `<meta name=… content=…>` descriptor.
+*
+* @param name - The meta `name` attribute (e.g. `"description"`, `"robots"`).
+* @param content - The meta `content` value.
+* @returns A serializable head element keyed `meta:<name>`.
+* @example meta("description", "A web framework built on @moku-labs/core")
+*/
+function meta(name, content) {
+	return {
+		tag: "meta",
+		attrs: {
+			name,
+			content
+		},
+		key: `meta:${name}`
+	};
+}
+/**
+* Build an Open Graph `<meta property=… content=…>` descriptor.
+*
+* @param property - The OG property, used verbatim (e.g. `"og:title"`, `"og:image"`).
+* @param content - The property value.
+* @returns A serializable head element keyed `meta:<property>`.
+* @example og("og:title", "Home")
+*/
+function og(property, content) {
+	return {
+		tag: "meta",
+		attrs: {
+			property,
+			content
+		},
+		key: `meta:${property}`
+	};
+}
+/**
+* Build a Twitter-card `<meta name=… content=…>` descriptor.
+*
+* @param name - The Twitter meta name, used verbatim (e.g. `"twitter:title"`).
+* @param content - The value.
+* @returns A serializable head element keyed `meta:<name>`.
+* @example twitter("twitter:card", "summary_large_image")
+*/
+function twitter(name, content) {
+	return {
+		tag: "meta",
+		attrs: {
+			name,
+			content
+		},
+		key: `meta:${name}`
+	};
+}
+/**
+* Build a JSON-LD `<script type="application/ld+json">` descriptor.
+*
+* XSS-SAFE: the serialized JSON has `<`, `>`, and `&` unicode-escaped (`<`,
+* `>`, `&`) so the payload can never break out of the `<script>` element
+* or inject markup, while still round-tripping via `JSON.parse`.
+*
+* @param data - Any JSON-serializable structured-data object.
+* @returns A serializable head element carrying the escaped JSON-LD script.
+* @example jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })
+*/
+function jsonLd(data) {
+	return {
+		tag: "script",
+		attrs: { type: "application/ld+json" },
+		children: JSON.stringify(data).replaceAll("<", String.raw`\u003c`).replaceAll(">", String.raw`\u003e`).replaceAll("&", String.raw`\u0026`)
+	};
+}
+/**
+* Build a canonical `<link rel="canonical" href=…>` descriptor.
+*
+* @param url - The canonical absolute URL.
+* @returns A serializable head element keyed `link:canonical`.
+* @example canonical("https://example.com/post")
+*/
+function canonical(url) {
+	return {
+		tag: "link",
+		attrs: {
+			rel: "canonical",
+			href: url
+		},
+		key: "link:canonical"
+	};
+}
+/**
+* Build an alternate-language `<link rel="alternate" hreflang=… href=…>` descriptor.
+*
+* @param locale - The BCP-47 locale tag (e.g. `"en"`, `"uk"`, `"x-default"`).
+* @param url - The absolute URL of the localized page.
+* @returns A serializable head element keyed `link:alternate:<locale>`.
+* @example hreflang("uk", "https://example.com/uk/post")
+*/
+function hreflang(locale, url) {
+	return {
+		tag: "link",
+		attrs: {
+			rel: "alternate",
+			hreflang: locale,
+			href: url
+		},
+		key: `link:alternate:${locale}`
+	};
+}
+/**
+* Build a feed `<link rel="alternate" type=… title=… href=…>` descriptor.
+*
+* @param title - Human-readable feed title.
+* @param url - The feed URL.
+* @param type - The feed MIME type. Defaults to `"application/rss+xml"`.
+* @returns A serializable head element keyed `link:feed:<url>`.
+* @example feedLink("My Blog", "/feed.xml", "application/atom+xml")
+*/
+function feedLink(title, url, type = "application/rss+xml") {
+	return {
+		tag: "link",
+		attrs: {
+			rel: "alternate",
+			type,
+			title,
+			href: url
+		},
+		key: `link:feed:${url}`
+	};
+}
+/**
+* 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…).
+* @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")
+*/
+function buildArticleHead(articleMeta, canonicalUrl) {
+	const elements = [canonical(canonicalUrl), og("og:type", "article")];
+	if (articleMeta.published) elements.push(og(`${ARTICLE_PREFIX}published_time`, articleMeta.published));
+	if (articleMeta.modified) elements.push(og(`${ARTICLE_PREFIX}modified_time`, articleMeta.modified));
+	if (articleMeta.author) elements.push(og(`${ARTICLE_PREFIX}author`, articleMeta.author));
+	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));
+	return elements;
+}
+//#endregion
+//#region src/plugins/head/compose.ts
+/**
+* @file head plugin — shared pure composition module (reused by `spa` in Increment B)
+*
+* The pure composition logic — `(HeadConfig, defaults, locales, urls) → HeadElement[]` —
+* lives here so `spa` can import it without making `head` depend on `spa`. Dependency
+* direction is strictly `spa → head`; `head` must never import `spa`.
+*/
+/** The `x-default` hreflang sentinel locale. */
+const X_DEFAULT = "x-default";
+/**
+* Apply a `%s` title template to a resolved title (or return the title verbatim when
+* no template is configured).
+*
+* @param title - The resolved page title.
+* @param template - The configured title template (may be `undefined`).
+* @returns The templated title string.
+* @example applyTemplate("Home", "%s — Site") // "Home — Site"
+*/
+function applyTemplate(title, template) {
+	return template === void 0 ? title : template.replaceAll("%s", title);
+}
+/**
+* Resolve a possibly-relative image URL against the site base URL.
+*
+* @param image - The image URL (relative or absolute).
+* @param site - The site slice used to absolutize relative paths.
+* @returns The absolute image URL.
+* @example resolveImage("/og.png", site) // "https://blog.dev/og.png"
+*/
+function resolveImage(image, site) {
+	return image.startsWith("http") ? image : site.canonical(image);
+}
+/**
+* Build the canonical, og, twitter, and hreflang elements for the route from
+* the resolved title/description, defaults, and dependency slices.
+*
+* @param input - The gathered composition inputs.
+* @param resolved - The resolved title/description/canonical URL.
+* @param resolved.title - The templated page title.
+* @param resolved.description - The resolved description.
+* @param resolved.canonicalUrl - The resolved absolute canonical URL.
+* @returns The ordered base element set (excluding route-supplied extras).
+* @example buildBaseElements(input, { title, description, canonicalUrl })
+*/
+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",
+			children: resolved.title,
+			key: "title"
+		},
+		meta("description", resolved.description),
+		og("og:title", head.title ?? resolved.title),
+		og("og:description", resolved.description),
+		og("og:url", resolved.canonicalUrl),
+		twitter("twitter:card", defaults.twitterCard),
+		twitter("twitter:title", head.title ?? resolved.title),
+		twitter("twitter:description", resolved.description)
+	];
+	if (image) {
+		const abs = resolveImage(image, site);
+		elements.push(og("og:image", abs), twitter("twitter:image", abs));
+	}
+	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));
+	return elements;
+}
+/**
+* De-duplicate elements by `key`, keeping the LAST occurrence (route-supplied
+* overrides win over generated defaults). Keyless elements are always retained.
+*
+* @param elements - The full ordered element list.
+* @returns The de-duplicated list in first-seen position with last-wins content.
+* @example dedupeByKey([meta("description", "a"), meta("description", "b")])
+*/
+function dedupeByKey(elements) {
+	const byKey = /* @__PURE__ */ new Map();
+	const order = [];
+	const keyless = [];
+	for (const element of elements) {
+		if (element.key === void 0) {
+			keyless.push(element);
+			continue;
+		}
+		if (!byKey.has(element.key)) order.push(element.key);
+		byKey.set(element.key, element);
+	}
+	return [...order.map((k) => byKey.get(k)), ...keyless];
+}
+/**
+* Compose the ordered, de-duplicated `HeadElement[]` for a route from site defaults,
+* i18n hreflang alternates, and the route's head config.
+*
+* @param input - The gathered composition inputs.
+* @returns The ordered, de-duplicated head element set.
+* @example composeHead({ route, data, defaults, site, i18n, router })
+*/
+function composeHead(input) {
+	const { route, defaults, site, router } = input;
+	const head = route.head ?? {};
+	return dedupeByKey([...buildBaseElements(input, {
+		title: applyTemplate(head.title ?? site.name(), defaults.titleTemplate),
+		description: head.description ?? site.description(),
+		canonicalUrl: head.canonical ?? site.canonical(router.toUrl(route.name, { ...route.params }))
+	}), ...head.elements ?? []]);
+}
+/**
+* HTML-escape a value for safe insertion into an attribute or text node. `&` is
+* escaped first so already-escaped entities are not double-escaped.
+*
+* @param raw - The unsafe string.
+* @returns The HTML-escaped string.
+* @example escapeHtml('a & "b" <c>') // "a &amp; &quot;b&quot; &lt;c&gt;"
+*/
+function escapeHtml(raw) {
+	return raw.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/**
+* 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.
+*
+* @param element - The element to serialize.
+* @returns A single line of HTML.
+* @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}`;
+	if (element.tag === "script") return `<script ${attributes}>${element.children ?? ""}<\/script>`;
+	if (element.tag === "title") return `<title>${escapeHtml(element.children ?? "")}</title>`;
+	return `<${open}>`;
+}
+/**
+* Serialize a `HeadElement[]` to `<head>` inner HTML. All attribute values are
+* HTML-attribute-escaped; JSON-LD payloads are already unicode-escaped by `jsonLd`.
+*
+* @param elements - The composed head elements.
+* @returns The serialized inner HTML of `<head>` (no surrounding `<head>` tags).
+* @example serializeHead(composeHead(input))
+*/
+function serializeHead(elements) {
+	return elements.map((element) => serializeElement(element)).join("");
+}
+//#endregion
+//#region src/plugins/head/api.ts
+/**
+* @file head plugin — API factory.
+*
+* The `render` method pulls `site`/`i18n`/`router` via `ctx.require` at call time,
+* composes the head element set via the shared `compose.ts` module, and serializes
+* it to a string. It holds no resource and caches no subscription.
+*/
+/** Error prefix for head API invariant failures. */
+const ERROR_PREFIX$4 = "[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).
+*
+* @param state - The head plugin state holder.
+* @returns The non-null normalized defaults snapshot.
+* @throws {Error} If `render` is reached before `onInit` populated the defaults.
+* @example
+* ```ts
+* const defaults = readDefaults(ctx.state);
+* ```
+*/
+function readDefaults(state) {
+	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$4}: defaults accessed before onInit normalized them.`);
+	return state.defaults;
+}
+/**
+* Creates the head plugin API surface. The single `render` method resolves
+* `site`/`i18n`/`router` via `ctx.require`, composes the route's head elements,
+* and serializes them to `<head>` inner HTML.
+*
+* @param ctx - Plugin context exposing `state` and `require`.
+* @returns The {@link Api} surface mounted at `app.head`.
+* @example
+* ```ts
+* const api = createApi(ctx);
+* api.render(route, data);
+* ```
+*/
+function createApi$1(ctx) {
+	return { 
+	/**
+	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
+	*
+	* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+	* @param data - The page data object passed to the route's loader/render.
+	* @returns The serialized inner HTML of `<head>`.
+	* @example
+	* ```ts
+	* api.render(route, { title: "Post" });
+	* ```
+	*/
+render(route, data) {
+		return serializeHead(composeHead({
+			route,
+			data,
+			defaults: readDefaults(ctx.state),
+			site: ctx.require(sitePlugin),
+			i18n: ctx.require(i18nPlugin),
+			router: ctx.require(routerPlugin)
+		}));
+	} };
+}
+//#endregion
+//#region src/plugins/head/config.ts
+/** Error prefix for all head config-validation failures. */
+const ERROR_PREFIX$3 = "[head] config:";
+/** The allowed `twitterCard` literals (also the runtime guard set). */
+const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
+/**
+* Framework default head config. Consumers override via `pluginConfigs.head`.
+* `twitterCard` defaults to the large-image card; all other fields are absent
+* (the optional fields are left `undefined` per `exactOptionalPropertyTypes`).
+*
+* @example
+* ```ts
+* createPlugin("head", { config: defaultConfig });
+* ```
+*/
+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`
+* token, or when `twitterCard` is present but not one of the two allowed literals.
+*
+* @param config - The resolved head {@link Config} to validate.
+* @throws {Error} If `titleTemplate` lacks `%s`, or `twitterCard` is invalid.
+* @example
+* ```ts
+* validateHeadConfig({ titleTemplate: "%s — Site" });
+* ```
+*/
+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)}.`);
+}
+/**
+* Validate then build the frozen, normalized {@link HeadDefaults} snapshot read by
+* `render`. `twitterCard` is defaulted to `"summary_large_image"`; optional fields
+* are copied through only when present (preserving `exactOptionalPropertyTypes`).
+*
+* @param config - The resolved head {@link Config}.
+* @returns A frozen normalized defaults snapshot.
+* @throws {Error} If the config fails {@link validateHeadConfig}.
+* @example
+* ```ts
+* normalizeHeadConfig({ titleTemplate: "%s — Site" });
+* ```
+*/
+function normalizeHeadConfig(config) {
+	validateHeadConfig(config);
+	const defaults = { twitterCard: config.twitterCard ?? "summary_large_image" };
+	if (config.titleTemplate !== void 0) defaults.titleTemplate = config.titleTemplate;
+	if (config.defaultOgImage !== void 0) defaults.defaultOgImage = config.defaultOgImage;
+	if (config.twitterHandle !== void 0) defaults.twitterHandle = config.twitterHandle;
+	return Object.freeze(defaults);
+}
+//#endregion
+//#region src/plugins/head/helpers.ts
+/**
+* @file head plugin — SEO primitive helper bundle for plugin registration.
+*
+* Aggregates the pure SEO primitive helpers into a single record consumed by the
+* plugin's `helpers` slot in `index.ts` (kept here so `index.ts` stays wiring-only
+* and within its line budget). These same helpers are re-exported at the framework
+* index for direct consumer use.
+*/
+/**
+* The SEO primitive helper bundle registered on the `head` plugin.
+*
+* @example
+* ```ts
+* createPlugin("head", { helpers: headHelpers });
+* ```
+*/
+const headHelpers = {
+	meta,
+	og,
+	twitter,
+	jsonLd,
+	canonical,
+	hreflang,
+	feedLink,
+	buildArticleHead
+};
+//#endregion
+//#region src/plugins/head/state.ts
+/**
+* Creates initial head plugin state.
+*
+* Initializes the single `defaults` slot to `null`; `onInit` assigns the normalized
+* snapshot exactly once.
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global plugin registry.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns The initial head state with a null `defaults` slot.
+* @example
+* ```ts
+* const state = createState({ global: {}, config: {} });
+* ```
+*/
+function createState$1(_ctx) {
+	return { defaults: null };
+}
+//#endregion
+//#region src/plugins/head/index.ts
+/**
+* @file head — Standard Plugin wiring harness (logic in primitives/compose/api/config).
+* @see README.md
+*/
+/**
+* Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
+* Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
+* ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
+* Depends on site, i18n, and router.
+*
+* @example Set global head defaults
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     head: {
+*       titleTemplate: "%s — My Blog",
+*       twitterCard: "summary_large_image",
+*       twitterHandle: "@moku_labs"
+*     }
+*   }
+* });
+* ```
+*/
+const headPlugin = createPlugin$1("head", {
+	depends: [
+		sitePlugin,
+		i18nPlugin,
+		routerPlugin
+	],
+	helpers: headHelpers,
+	config: defaultConfig,
+	createState: createState$1,
+	api: createApi$1,
+	onInit(ctx) {
+		ctx.state.defaults = normalizeHeadConfig(ctx.config);
+	}
+});
+//#endregion
+//#region src/plugins/spa/api.ts
+/**
+* Creates the spa plugin API surface (registration / control). All methods
+* delegate to the single shared kernel stored in `ctx.state.kernel`.
+*
+* @param ctx - Plugin context exposing `state` (kernel) and `log`.
+* @returns The {@link SpaApi} surface mounted at `app.spa`.
+* @example
+* const api = createApi(ctx);
+* api.register(counter);
+*/
+function createApi(ctx) {
+	return {
+		/**
+		* Register a component definition (last-registered-wins); warns on collision.
+		*
+		* @param component - The component definition created via `createComponent`.
+		* @example
+		* app.spa.register(counter);
+		*/
+		register(component) {
+			if (ctx.state.registeredComponents.has(component.name)) ctx.log.warn("spa:component-collision", { name: component.name });
+			ctx.state.kernel?.register(component);
+		},
+		/**
+		* Programmatically navigate to a path (client runtime; no-op without a DOM).
+		*
+		* @param path - Target path (pathname, optionally with search/hash).
+		* @example
+		* app.spa.navigate("/about");
+		*/
+		navigate(path) {
+			ctx.state.kernel?.processNav(path);
+		},
+		/**
+		* Read the current resolved URL.
+		*
+		* @returns The current pathname + search.
+		* @example
+		* 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/spa/types.ts
+var types_exports$5 = /* @__PURE__ */ __exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
+/** Allowed hook names — single source of truth for fail-fast validation. */
+const COMPONENT_HOOK_NAMES = [
+	"onCreate",
+	"onMount",
+	"onNavStart",
+	"onNavEnd",
+	"onUnMount",
+	"onDestroy"
+];
+//#endregion
+//#region src/plugins/spa/components.ts
+/** Error prefix for spa fail-fast failures (spec/11 Part-3). */
+const ERROR_PREFIX$2 = "[web]";
+/** The set of legal hook names, frozen for O(1) membership checks. */
+const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
+/**
+* Create a validated component definition. Validates hook names at registration
+* for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+* each provided hook is a function.
+*
+* @param name - Unique component name.
+* @param hooks - Lifecycle hook implementations.
+* @returns A `ComponentDef` ready to `register`.
+* @throws {Error} If `name` is empty, any hook key is not in
+*   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+* @example
+* const counter = createComponent("counter", {
+*   onMount({ el }) { el.textContent = "0"; }
+* });
+*/
+function createComponent(name, hooks) {
+	if (name.trim() === "") throw new Error(`${ERROR_PREFIX$2} component name must be a non-empty string\n  → pass a unique name to createComponent("name", hooks)`);
+	for (const key of Object.keys(hooks)) {
+		if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${name}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
+		if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${name}" must be a function\n  → provide a function or omit the hook`);
+	}
+	return {
+		name,
+		hooks
+	};
+}
+/**
+* Extracts the page data payload from the inline `script#__DATA__` element.
+* Returns an empty object when the script is absent, empty, or invalid JSON.
+*
+* @param doc - The document to read the data script from.
+* @returns The parsed page data, or `{}` when unavailable.
+* @example
+* const data = extractPageData(document);
+*/
+function extractPageData(doc) {
+	const text = doc.querySelector("script#__DATA__")?.textContent;
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return {};
+	}
+}
+/**
+* Builds a live component instance bound to an element.
+*
+* @param definition - The component definition.
+* @param element - The element the instance binds to.
+* @param persistent - Whether the instance survives navigation.
+* @returns The constructed (not-yet-mounted) instance.
+* @example
+* const inst = createInstance(definition, element, false);
+*/
+function createInstance(definition, element, persistent) {
+	return {
+		def: definition,
+		el: element,
+		persistent
+	};
+}
+/**
+* Invokes a single lifecycle hook on an instance with its component context.
+* Missing hooks are skipped silently.
+*
+* @param instance - The instance whose hook to run.
+* @param hook - The hook name to invoke.
+* @param ctx - The component context passed to the hook.
+* @example
+* runHook(instance, "onMount", ctx);
+*/
+function runHook(instance, hook, ctx) {
+	instance.def.hooks[hook]?.(ctx);
+}
+/**
+* Builds the component context handed to a hook (the bound element + page data).
+*
+* @param element - The element the instance is bound to.
+* @param data - The current page data payload.
+* @returns The hook context.
+* @example
+* const ctx = makeContext(element, data);
+*/
+function makeContext(element, data) {
+	return {
+		el: element,
+		data
+	};
+}
+/**
+* Scans the swap region, mounts components for matching `data-component`
+* elements, classifies persistent (outside swap area) vs page-specific (inside),
+* fires `onCreate` then `onMount`, and emits `spa:component-mount` per instance.
+* Already-mounted elements are skipped.
+*
+* @param state - The plugin state (registeredComponents + instances).
+* @param emit - The event emitter for spa:component-mount.
+* @param swapSelector - CSS selector bounding page-specific components.
+* @example
+* scanAndMount(state, emit, "main > section");
+*/
+function scanAndMount(state, emit, swapSelector) {
+	if (typeof document === "undefined") return;
+	const swapArea = document.querySelector(swapSelector);
+	const data = extractPageData(document);
+	for (const element of document.querySelectorAll("[data-component]")) {
+		if (state.instances.has(element)) continue;
+		const name = element.dataset.component;
+		if (!name) continue;
+		const definition = state.registeredComponents.get(name);
+		if (!definition) continue;
+		const instance = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
+		const ctx = makeContext(element, data);
+		runHook(instance, "onCreate", ctx);
+		runHook(instance, "onMount", ctx);
+		state.instances.set(element, instance);
+		emit("spa:component-mount", {
+			name: definition.name,
+			el: element
+		});
+	}
+}
+/**
+* Unmounts page-specific instances inside the swap region (runs `onUnMount`
+* then `onDestroy`), removes them from state, and emits `spa:component-unmount`.
+* Persistent instances (outside the swap area) are left in place.
+*
+* @param state - The plugin state holding live instances.
+* @param emit - The event emitter for spa:component-unmount.
+* @example
+* unmountPageSpecific(state, emit);
+*/
+function unmountPageSpecific(state, emit) {
+	const data = typeof document === "undefined" ? {} : extractPageData(document);
+	for (const [element, instance] of state.instances) {
+		if (instance.persistent) continue;
+		const ctx = makeContext(element, data);
+		runHook(instance, "onUnMount", ctx);
+		runHook(instance, "onDestroy", ctx);
+		state.instances.delete(element);
+		emit("spa:component-unmount", {
+			name: instance.def.name,
+			el: element
+		});
+	}
+}
+/**
+* Disposes ALL live instances (persistent and page-specific) on teardown:
+* runs `onUnMount` then `onDestroy`, emits `spa:component-unmount`, and clears
+* the instance map. Used by the kernel's `dispose` on plugin stop.
+*
+* @param state - The plugin state holding live instances.
+* @param emit - The event emitter for spa:component-unmount.
+* @example
+* unmountAll(state, emit);
+*/
+function unmountAll(state, emit) {
+	const data = typeof document === "undefined" ? {} : extractPageData(document);
+	for (const [element, instance] of state.instances) {
+		const ctx = makeContext(element, data);
+		runHook(instance, "onUnMount", ctx);
+		runHook(instance, "onDestroy", ctx);
+		emit("spa:component-unmount", {
+			name: instance.def.name,
+			el: element
+		});
+	}
+	state.instances.clear();
+}
+/**
+* Fires `onNavStart` on every currently-mounted instance (persistent instances
+* receive it across navigations; page-specific ones receive it before unmount).
+*
+* @param state - The plugin state holding live instances.
+* @example
+* notifyNavStart(state);
+*/
+function notifyNavStart(state) {
+	const data = typeof document === "undefined" ? {} : extractPageData(document);
+	for (const [element, instance] of state.instances) runHook(instance, "onNavStart", makeContext(element, data));
+}
+/**
+* Fires `onNavEnd` on persistent instances that survived the swap (page-specific
+* instances were already destroyed and re-created by the swap).
+*
+* @param state - The plugin state holding live instances.
+* @example
+* notifyNavEnd(state);
+*/
+function notifyNavEnd(state) {
+	const data = typeof document === "undefined" ? {} : extractPageData(document);
+	for (const [element, instance] of state.instances) if (instance.persistent) runHook(instance, "onNavEnd", makeContext(element, data));
+}
+//#endregion
+//#region src/plugins/spa/head.ts
+/** Single-element head selectors synced by replace/append/remove on navigation. */
+const META_SELECTORS = [
+	"meta[name=\"description\"]",
+	"meta[property=\"og:title\"]",
+	"meta[property=\"og:description\"]",
+	"meta[property=\"og:url\"]",
+	"meta[property=\"og:image\"]",
+	"meta[property=\"og:type\"]",
+	"meta[property=\"og:locale\"]",
+	"meta[name=\"twitter:card\"]",
+	"meta[name=\"twitter:title\"]",
+	"meta[name=\"twitter:description\"]",
+	"meta[name=\"twitter:image\"]",
+	"meta[name=\"twitter:site\"]",
+	"link[rel=\"canonical\"]"
+];
+/** Head element groups fully replaced (remove-all-then-clone) on navigation. */
+const REPLACE_ALL_SELECTORS = [
+	"script[type=\"application/ld+json\"]",
+	"link[rel=\"alternate\"][hreflang]",
+	"meta[property^=\"article:\"]"
+];
+/**
+* Sync a single head element by selector between the fetched and live document:
+* replace when both exist, append when only the new doc has it, remove when only
+* the live doc has it.
+*
+* @param selector - CSS selector for the head element to sync.
+* @param doc - The fetched document (DOMParser-parsed).
+* @example
+* syncElement('link[rel="canonical"]', doc);
+*/
+function syncElement(selector, doc) {
+	const newElement = doc.querySelector(selector);
+	const oldElement = document.querySelector(selector);
+	if (newElement && oldElement) oldElement.replaceWith(newElement.cloneNode(true));
+	else if (newElement) document.head.append(newElement.cloneNode(true));
+	else if (oldElement) oldElement.remove();
+}
+/**
+* Remove all live matches for a selector and re-clone the fetched document's
+* matches into the live `<head>`.
+*
+* @param selector - CSS selector for the element group to replace wholesale.
+* @param doc - The fetched document (DOMParser-parsed).
+* @example
+* replaceAllBySelector('script[type="application/ld+json"]', doc);
+*/
+function replaceAllBySelector(selector, doc) {
+	for (const element of document.querySelectorAll(selector)) element.remove();
+	for (const element of doc.querySelectorAll(selector)) document.head.append(element.cloneNode(true));
+}
+/**
+* Syncs the live document `<head>` after a navigation from the fetched document
+* (whose head was composed by the `head` plugin). Recomputes
+* title/meta/canonical/JSON-LD/hreflang/`<html lang>` once and applies them.
+* The `head` API is accepted to bind the structural dependency (spec/09 deps).
+*
+* @param _head - The head plugin API (dependency binding; composition reused via the fetched doc).
+* @param doc - The fetched document parsed from the navigated page's HTML.
+* @example
+* syncHead(headApi, parsedDoc);
+*/
+function syncHead(_head, doc) {
+	if (typeof document === "undefined") return;
+	const newTitle = doc.querySelector("title")?.textContent;
+	if (newTitle) document.title = newTitle;
+	const newLang = doc.documentElement.lang;
+	if (newLang) document.documentElement.lang = newLang;
+	for (const selector of META_SELECTORS) syncElement(selector, doc);
+	for (const selector of REPLACE_ALL_SELECTORS) replaceAllBySelector(selector, doc);
+}
+//#endregion
+//#region src/plugins/spa/progress.ts
+/** Delay before the bar appears, so fast navigations show no indicator. */
+const START_DELAY_MS = 150;
+/** Interval between trickle increments while loading. */
+const TRICKLE_MS = 300;
+/** Linger before the completed bar is reset/hidden. */
+const DONE_LINGER_MS = 200;
+/** Ceiling the bar trickles to while still loading (never reaches 100% until done). */
+const TRICKLE_CEIL = 90;
+/** No-op progress bar used when disabled or in a headless context. */
+const NOOP_BAR = {
+	start() {},
+	done() {}
+};
+/**
+* Creates the in-house progress bar (150ms delay + trickle). A no-op shell when
+* progress is disabled or no DOM is present. The progress element is created
+* once (prepended to `<body>` as `<div data-progress>`) and reused across navs.
+*
+* @param enabled - Whether the progress bar is active.
+* @returns A {@link ProgressBar} with `start`/`done`. Disabled/headless → no-ops.
+* @example
+* const bar = createProgressBar(true);
+* bar.start();
+* bar.done();
+*/
+function createProgressBar(enabled) {
+	if (!enabled || typeof document === "undefined") return NOOP_BAR;
+	const element = document.createElement("div");
+	element.dataset.progress = "";
+	document.body.prepend(element);
+	let delayTimer;
+	let trickleTimer;
+	let width = 0;
+	/**
+	* Step the trickle upward toward the ceiling and reschedule.
+	*
+	* @example
+	* trickle();
+	*/
+	const trickle = () => {
+		if (width >= TRICKLE_CEIL) return;
+		width = Math.min(TRICKLE_CEIL, width + 5 + Math.random() * 10);
+		element.style.width = `${String(width)}%`;
+		trickleTimer = setTimeout(trickle, TRICKLE_MS);
+	};
+	/**
+	* Show the bar after the start delay and begin trickling.
+	*
+	* @example
+	* start();
+	*/
+	const start = () => {
+		delayTimer = setTimeout(() => {
+			width = 15;
+			element.style.width = "15%";
+			element.dataset.active = "";
+			trickle();
+		}, START_DELAY_MS);
+	};
+	/**
+	* Complete the bar to 100%, then reset/hide it after a short linger.
+	*
+	* @example
+	* done();
+	*/
+	const done = () => {
+		clearTimeout(delayTimer);
+		clearTimeout(trickleTimer);
+		element.style.width = "100%";
+		element.dataset.active = "";
+		setTimeout(() => {
+			delete element.dataset.active;
+			element.style.width = "0%";
+			width = 0;
+		}, DONE_LINGER_MS);
+	};
+	return {
+		start,
+		done
+	};
+}
+//#endregion
+//#region src/plugins/spa/router.ts
+/**
+* Read the Navigation API global, or `undefined` when unsupported.
+*
+* @returns The `navigation` object, or `undefined` in unsupporting environments.
+* @example
+* const nav = getNavigation();
+*/
+function getNavigation() {
+	return globalThis.navigation;
+}
+/** File extensions that bypass the SPA router (treated as static assets). */
+const STATIC_ASSET_RE = /\.(xml|json|png|jpe?g|pdf|ico|svg|webp|woff2?)$/i;
+/**
+* Whether a URL is an internal page link (same origin, not a static asset).
+*
+* @param url - The URL to classify.
+* @returns True when same-origin and not a static asset.
+* @example
+* isInternalLink(new URL("https://x.dev/about", location.origin));
+*/
+function isInternalLink(url) {
+	return url.origin === location.origin && !STATIC_ASSET_RE.test(url.pathname);
+}
+/**
+* Save the current scroll position keyed by path (best-effort; ignores storage errors).
+*
+* @param path - The path to key the scroll position under.
+* @example
+* saveScrollPosition("/about");
+*/
+function saveScrollPosition(path) {
+	try {
+		sessionStorage.setItem(`spa:scroll:${path}`, String(window.scrollY));
+	} catch {}
+}
+/**
+* Restore a previously-saved scroll position for `path`, if any.
+*
+* @param path - The path whose saved scroll position to restore.
+* @example
+* restoreScrollPosition("/about");
+*/
+function restoreScrollPosition(path) {
+	try {
+		const saved = sessionStorage.getItem(`spa:scroll:${path}`);
+		if (saved) window.scrollTo(0, Number(saved));
+	} catch {}
+}
+/**
+* Fetch a page and hand its HTML to the handlers; on any error fall back to a
+* full browser navigation (`location.href = pathname`).
+*
+* @param pathname - The destination pathname.
+* @param handlers - The navigation lifecycle callbacks.
+* @returns A promise that resolves once the swap (or fallback) is dispatched.
+* @example
+* await performNavigation("/about", handlers);
+*/
+async function performNavigation(pathname, handlers) {
+	handlers.onStart(pathname);
+	try {
+		const response = await fetch(pathname);
+		if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
+		handlers.onEnd(await response.text(), pathname);
+	} catch {
+		handlers.onError();
+		location.href = pathname;
+	}
+}
+/**
+* Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
+* enabled and supported (instant swap otherwise — never throws).
+*
+* @param doSwap - The synchronous DOM mutation to perform.
+* @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @example
+* runSwap(() => current.replaceWith(next), true);
+*/
+function runSwap(doSwap, viewTransitions) {
+	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+	const docWithVt = document;
+	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	else doSwap();
+}
+/**
+* Replace the `swapSelector` region of the live document with the matching
+* region of `doc`, wrapped per `viewTransitions`. The `onSwapped` callback runs
+* inside the same transition frame (after the DOM mutation) so component
+* re-mounting is captured by the transition snapshot.
+*
+* @param doc - The fetched document (DOMParser-parsed) holding the new region.
+* @param swapSelector - CSS selector for the region to replace.
+* @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @example
+* swapRegion(doc, "main > section", false, () => mountNew());
+*/
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+	const newContent = doc.querySelector(swapSelector);
+	const currentContent = document.querySelector(swapSelector);
+	if (!newContent || !currentContent) return;
+	runSwap(() => {
+		currentContent.replaceWith(newContent);
+		onSwapped();
+	}, viewTransitions);
+}
+/**
+* Resolve a navigable internal URL from a click event, or `undefined` when the
+* click should not be intercepted (modifier keys, non-anchor, external, new-tab).
+*
+* @param event - The click event to inspect.
+* @returns The internal URL to navigate to, or `undefined`.
+* @example
+* const url = resolveClickTarget(event);
+*/
+function resolveClickTarget(event) {
+	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return void 0;
+	if (event.defaultPrevented) return void 0;
+	const anchor = event.target?.closest("a");
+	if (!anchor || anchor.target === "_blank") return void 0;
+	let url;
+	try {
+		url = new URL(anchor.href, location.origin);
+	} catch {
+		return;
+	}
+	return isInternalLink(url) ? url : void 0;
+}
+/**
+* Attach the History-API click/popstate interception path (used when the
+* Navigation API is unavailable).
+*
+* @param handlers - The navigation lifecycle callbacks.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @returns A teardown that removes the attached listeners.
+* @example
+* const dispose = attachHistoryFallback(handlers);
+*/
+function attachHistoryFallback(handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
+	/**
+	* Intercept an internal-link click and run a History-API navigation.
+	*
+	* @param event - The click event.
+	* @example
+	* document.addEventListener("click", onClick);
+	*/
+	const onClick = (event) => {
+		const url = resolveClickTarget(event);
+		if (!url) return;
+		event.preventDefault();
+		if (url.pathname === location.pathname) {
+			window.scrollTo({
+				top: 0,
+				behavior: "smooth"
+			});
+			return;
+		}
+		saveScrollPosition(location.pathname);
+		history.pushState({ scrollY: 0 }, "", url.pathname);
+		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+	};
+	/**
+	* Re-run navigation on back/forward, restoring the saved scroll position.
+	*
+	* @example
+	* globalThis.addEventListener("popstate", onPopState);
+	*/
+	const onPopState = () => {
+		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+	};
+	document.addEventListener("click", onClick);
+	globalThis.addEventListener("popstate", onPopState);
+	return () => {
+		document.removeEventListener("click", onClick);
+		globalThis.removeEventListener("popstate", onPopState);
+	};
+}
+/**
+* Attach the Navigation-API interception path (the primary path when supported).
+*
+* @param navigation - The Navigation API object to attach the listener to.
+* @param handlers - The navigation lifecycle callbacks.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @returns A teardown that removes the `navigate` listener.
+* @example
+* const dispose = attachNavigationApi(navigation, handlers);
+*/
+function attachNavigationApi(navigation, handlers, navigate = (pathname) => performNavigation(pathname, handlers)) {
+	/**
+	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
+	*
+	* @param navEvent - The Navigation API navigate event.
+	* @example
+	* navigation.addEventListener("navigate", onNavigate);
+	*/
+	const onNavigate = (navEvent) => {
+		const url = new URL(navEvent.destination.url);
+		if (!navEvent.canIntercept || navEvent.hashChange || navEvent.downloadRequest) return;
+		if (!isInternalLink(url)) return;
+		if (url.pathname === location.pathname) {
+			navEvent.intercept({ handler: () => {
+				window.scrollTo({
+					top: 0,
+					behavior: "smooth"
+				});
+				return Promise.resolve();
+			} });
+			return;
+		}
+		navEvent.intercept({
+			scroll: "manual",
+			handler: async () => {
+				await navigate(url.pathname);
+				if (navEvent.navigationType === "traverse") navEvent.scroll();
+				else window.scrollTo(0, 0);
+			}
+		});
+	};
+	navigation.addEventListener("navigate", onNavigate);
+	return () => navigation.removeEventListener("navigate", onNavigate);
+}
+/**
+* Attach navigation interception: Navigation API (primary) with a History API
+* fallback. Returns a teardown removing every listener it attached.
+*
+* @param handlers - The navigation lifecycle callbacks the kernel supplies.
+* @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @returns A teardown removing all attached listeners.
+* @example
+* const dispose = attachRouter(handlers, navigate);
+*/
+function attachRouter(handlers, navigate) {
+	const navigation = getNavigation();
+	return navigation ? attachNavigationApi(navigation, handlers, navigate) : attachHistoryFallback(handlers, navigate);
+}
+//#endregion
+//#region src/plugins/spa/state.ts
+/** Error prefix for spa config-validation failures (spec/11 Part-3). */
+const ERROR_PREFIX$1 = "[web]";
+/** Default SPA config (declared as a value — no inline assertion). */
+const defaultSpaConfig = {
+	swapSelector: "main > section",
+	viewTransitions: false,
+	progressBar: true,
+	components: []
+};
+/**
+* Whether a selector is syntactically valid (parseable by the DOM). Falls back
+* to a permissive `true` in headless contexts without `document`.
+*
+* @param selector - The CSS selector to validate.
+* @returns True when the selector parses (or no DOM is available to check).
+* @example
+* isValidSelector("main > section"); // true
+*/
+function isValidSelector(selector) {
+	if (typeof document === "undefined") return true;
+	try {
+		document.querySelector(selector);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates the spa config and applies defaults (Part-3 errors on an empty or
+* syntactically-invalid `swapSelector`). Component-hook validation runs later in
+* `createComponent` when the components are registered.
+*
+* @param config - The raw spa config to validate.
+* @returns The fully-resolved config with defaults applied.
+* @throws {Error} When `swapSelector` is empty or not a valid CSS selector.
+* @example
+* const resolved = resolveSpaConfig({ swapSelector: "main > section" });
+*/
+function resolveSpaConfig(config) {
+	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? "main > section";
+	if (swapSelector.trim() === "") throw new Error(`${ERROR_PREFIX$1} spa.swapSelector must be a non-empty string.\n  Set a CSS selector for the page region to swap (e.g. "main > section").`);
+	if (!isValidSelector(swapSelector)) throw new Error(`${ERROR_PREFIX$1} spa.swapSelector is not a valid CSS selector: "${swapSelector}".\n  Provide a syntactically valid selector.`);
+	return {
+		swapSelector,
+		viewTransitions: config.viewTransitions ?? false,
+		progressBar: config.progressBar ?? true,
+		components: config.components ?? []
+	};
+}
+/**
+* Creates initial spa plugin state. All kernel state lives here — never module
+* scope. The kernel itself is built in onInit and stored as `kernel`, so
+* api/onStart/onStop all reuse the single shared instance.
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global plugin registry.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns The initial SPA state with an empty kernel slot.
+* @example
+* const state = createState({ global: {}, config: defaultSpaConfig });
+*/
+function createState(_ctx) {
+	return {
+		registeredComponents: /* @__PURE__ */ new Map(),
+		instances: /* @__PURE__ */ new Map(),
+		currentUrl: "",
+		destroyRouter: null,
+		started: false,
+		kernel: null
+	};
+}
+//#endregion
+//#region src/plugins/spa/kernel.ts
+/**
+* @file spa plugin — pure SPA kernel factory + onInit wiring helper.
+*
+* `createSpaKernel(state, config, emit, deps)` is a PURE factory: it closes over
+* the injected state/config/emit/deps only — never the Moku ctx, never module
+* singletons. It is unit-testable with a mock state object and a spy emit.
+* @see README.md
+*/
+/** 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.
+* @param component - The component definition to register.
+* @example
+* registerComponent(state, counter);
+*/
+function registerComponent(state, component) {
+	state.registeredComponents.set(component.name, component);
+}
+/**
+* Resolve the current document URL (pathname + search), or `""` when headless.
+*
+* @returns The current URL string.
+* @example
+* const url = currentLocationUrl();
+*/
+function currentLocationUrl() {
+	if (typeof document === "undefined") return "";
+	return location.pathname + location.search;
+}
+/**
+* Apply the matched route's `head` config to the live document (minimal client
+* head-sync for the DATA path: title only — the full meta sync runs on the
+* HTML-over-fetch path from the fetched `<head>`).
+*
+* @param route - The matched route definition.
+* @param routeContext - The render context (params/data/locale).
+* @example
+* syncDataHead(hit.route, { params, data, locale });
+*/
+function syncDataHead(route, routeContext) {
+	const title = route._handlers.head?.(routeContext)?.title;
+	if (title !== void 0 && title !== "") document.title = title;
+}
+/**
+* Builds the single shared SPA kernel — a pure factory over state/config/emit.
+* Unit-testable with a mock state object and a spy emit; no Moku ctx involved.
+*
+* @param state - The plugin state (all kernel data lives here).
+* @param config - The raw spa config (defaults resolved internally on init).
+* @param emit - The event emitter for spa lifecycle events.
+* @param deps - Resolved router + head APIs reused by the kernel.
+* @returns The single shared {@link SpaKernel}.
+* @example
+* const kernel = createSpaKernel(state, config, emit, { router, head });
+*/
+function createSpaKernel(state, config, emit, deps) {
+	const resolved = resolveSpaConfig(config);
+	let progress;
+	/**
+	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
+	*
+	* @param html - The fetched page HTML.
+	* @param pathname - The destination pathname.
+	* @example
+	* handleEnd("<html>…</html>", "/about");
+	*/
+	const handleEnd = (html, pathname) => {
+		const doc = new DOMParser().parseFromString(html, "text/html");
+		syncHead(deps.head, doc);
+		unmountPageSpecific(state, emit);
+		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
+			scanAndMount(state, emit, resolved.swapSelector);
+			notifyNavEnd(state);
+		});
+		state.currentUrl = pathname;
+		progress?.done();
+		emit("spa:navigated", { url: pathname });
+	};
+	/**
+	* Begin a navigation: start progress, notify components, emit navigate.
+	*
+	* @param pathname - The destination pathname.
+	* @example
+	* handleStart("/about");
+	*/
+	const handleStart = (pathname) => {
+		progress?.start();
+		notifyNavStart(state);
+		emit("spa:navigate", {
+			from: state.currentUrl,
+			to: pathname
+		});
+	};
+	/**
+	* Finish the progress bar after a failed navigation (full-reload fallback).
+	*
+	* @example
+	* handleError();
+	*/
+	const handleError = () => {
+		progress?.done();
+	};
+	const handlers = {
+		onStart: handleStart,
+		onEnd: handleEnd,
+		onError: handleError
+	};
+	/**
+	* The client DATA path: match `pathname`, fetch the page's PERSISTED data via the
+	* `data` reader, VALIDATE it through the route's `parse` gate, then run the
+	* route's OWN `render` (the same component the build used for SSG) and
+	* Preact-render the VNode into the swap region. Returns `false` (touching nothing
+	* the fallback cares about) on no-match / no-render / no-data / fetch-miss /
+	* parse-throw, so the caller falls back to HTML-over-fetch. `route.load` does NOT
+	* run on the client — the build already persisted its output.
+	*
+	* @param pathname - The destination pathname (search stripped for matching).
+	* @returns `true` if the route was rendered from validated data, else `false`.
+	* @example
+	* if (await tryDataRender("/en/world/")) return;
+	*/
+	const tryDataRender = async (pathname) => {
+		if (!deps.dataAt) return false;
+		const matchPath = pathname.split("?")[0] ?? pathname;
+		const hit = deps.router.match(matchPath);
+		if (!hit?.route._handlers.render) return false;
+		try {
+			const raw = await deps.dataAt(pathname);
+			if (raw === null) return false;
+			const data = hit.route._handlers.parse ? hit.route._handlers.parse(raw) : raw;
+			const locale = hit.params.lang ?? document.documentElement.lang ?? "";
+			const routeContext = {
+				params: hit.params,
+				data,
+				locale
+			};
+			const vnode = hit.route._handlers.render(routeContext);
+			const region = document.querySelector(resolved.swapSelector);
+			if (!region) return false;
+			handleStart(pathname);
+			const { renderVNode } = await import("./render-BL9Fv6G6.mjs");
+			syncDataHead(hit.route, routeContext);
+			unmountPageSpecific(state, emit);
+			runSwap(() => {
+				region.replaceChildren();
+				renderVNode(vnode, region);
+				scanAndMount(state, emit, resolved.swapSelector);
+				notifyNavEnd(state);
+			}, resolved.viewTransitions);
+			state.currentUrl = pathname;
+			progress?.done();
+			emit("spa:navigated", { url: pathname });
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	/**
+	* Unified navigation: try the client DATA path first (only when the `data`
+	* plugin is composed), then fall back to HTML-over-fetch (which itself falls
+	* back to a full `location.href` reload). Injected into the router so every
+	* navigation entry point (Navigation API, History, programmatic) goes through it.
+	*
+	* @param pathname - The destination pathname.
+	* @returns A promise resolving once the swap (or fallback) is dispatched.
+	* @example
+	* await navigate("/en/world/");
+	*/
+	const navigate = async (pathname) => {
+		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
+		await performNavigation(pathname, handlers);
+	};
+	return {
+		/**
+		* Register config components and seed currentUrl from the document.
+		*
+		* @example
+		* kernel.init();
+		*/
+		init() {
+			for (const component of resolved.components) registerComponent(state, component);
+			state.currentUrl = currentLocationUrl();
+		},
+		/**
+		* Boot navigation interception + initial scan (throws if already started).
+		*
+		* @example
+		* kernel.boot();
+		*/
+		boot() {
+			if (typeof document === "undefined") return;
+			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
+			progress = createProgressBar(resolved.progressBar);
+			state.currentUrl = currentLocationUrl();
+			state.destroyRouter = attachRouter(handlers, navigate);
+			scanAndMount(state, emit, resolved.swapSelector);
+			state.started = true;
+		},
+		/**
+		* Register a component definition (last-registered-wins).
+		*
+		* @param component - The component definition to register.
+		* @example
+		* kernel.register(counter);
+		*/
+		register(component) {
+			registerComponent(state, component);
+		},
+		/**
+		* Process a navigation to `path` (fetch then swap; full reload on error).
+		*
+		* @param path - The target path to navigate to.
+		* @example
+		* kernel.processNav("/about");
+		*/
+		processNav(path) {
+			if (typeof document === "undefined") return;
+			navigate(path).catch(() => {});
+		},
+		/**
+		* Scan the swap region and mount components for matching elements.
+		*
+		* @example
+		* kernel.scan();
+		*/
+		scan() {
+			scanAndMount(state, emit, resolved.swapSelector);
+		},
+		/**
+		* Tear down router listeners, dispose all instances, reset boot state.
+		*
+		* @example
+		* kernel.dispose();
+		*/
+		dispose() {
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			unmountAll(state, emit);
+			progress = void 0;
+			state.started = false;
+		}
+	};
+}
+/**
+* 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).
+*
+* @param ctx - The plugin context (state/config/emit/require/has/log).
+* @example
+* initSpa(ctx);
+*/
+function initSpa(ctx) {
+	const deps = {
+		router: ctx.require(routerPlugin),
+		head: ctx.require(headPlugin)
+	};
+	if (ctx.has("data")) {
+		const reader = ctx.require(dataPluginHandle);
+		deps.dataAt = (path) => reader.at(path);
+	}
+	const kernel = createSpaKernel(ctx.state, ctx.config, ctx.emit, deps);
+	ctx.state.kernel = kernel;
+	kernelRef.current = kernel;
+	kernel.init();
+}
+//#endregion
+//#region src/plugins/spa/lifecycle.ts
+/** Router/instance teardown captured during onStart (undefined when stopped). */
+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.
+*
+* @param ctx - The plugin context (used for `log` capture).
+* @example
+* captureTeardown(ctx);
+*/
+function captureTeardown(ctx) {
+	if (typeof document === "undefined") return;
+	logRef = ctx.log;
+	teardown = disposeKernel;
+}
+/**
+* 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);
+		kernelRef.current?.boot();
+	},
+	onStop: disposeSpa
+});
+//#endregion
+//#region src/plugins/data/load-json.ts
+/**
+* @file `loadJson` — the data plugin's isomorphic JSON read primitive (the
+* SSG↔SPA seam). Internal to the `data` plugin (NOT a framework-root export):
+* `data.load(locale)` uses it, and consumers read through `app.data.load(locale)`.
+*
+* A read runs in BOTH worlds: on Node it reads the emitted data file from disk;
+* on the client (browser) it fetches the same data over HTTP. `loadJson` is the
+* single point where those two worlds differ — everything above it (the route's
+* `load`/`render`) is shared, so SSR/client parity is structural, not hoped-for.
+*
+* The browser path uses the `fetch` global. The Node path lazy-imports
+* `node:fs/promises` via `await import(...)`, so a browser bundle that includes
+* `loadJson` never statically pulls `node:*` (the bundler splits the Node branch
+* into its own chunk that the browser never loads).
+*/
+/**
+* Read + parse a JSON resource, isomorphically. In a browser (`document`
+* defined) it `fetch`es `pathOrUrl`; on Node it reads the file from disk. Throws
+* on a failed fetch or unreadable file so the caller (`route.load`/`data.load`)
+* can decide whether to fall back.
+*
+* @template T - The expected shape of the parsed JSON.
+* @param pathOrUrl - A site-root URL (browser) or filesystem path (Node).
+* @returns The parsed JSON, typed as `T`.
+* @throws {Error} If the browser fetch is not OK, or the Node file read fails.
+* @example
+* ```ts
+* // Browser: fetch("/_data/en/articles.json")
+* // Node:    read "dist/_data/en/articles.json"
+* const articles = await loadJson<Article[]>("/_data/en/articles.json");
+* ```
+*/
+async function loadJson(pathOrUrl) {
+	if (typeof document === "undefined") {
+		const { readFile } = await import("node:fs/promises");
+		return JSON.parse(await readFile(pathOrUrl, "utf8"));
+	}
+	const response = await fetch(pathOrUrl);
+	if (!response.ok) throw new Error(`[web] loadJson: failed to fetch ${pathOrUrl} (${String(response.status)}).`);
+	return response.json();
+}
+//#endregion
+//#region src/plugins/data/api.ts
+/**
+* @file data plugin — API factory (the agnostic data provider surface).
+*
+* Node-free by construction: this module statically imports only types + the pure
+* convention. The Node write side (`write()`) reaches its `node:fs` writer through
+* a lazy `await import("./writer")` at call time, so a browser bundle that composes
+* `data` for the read side never pulls `node:*`. The read side (`at()`) uses only
+* the isomorphic `loadJson` (whose Node branch is itself lazy).
+*/
+/**
+* Trim a single trailing slash from a config dir so `fileFor` joins cleanly.
+*
+* @param dir - The configured output dir (e.g. `"_data"` or `"_data/"`).
+* @returns The dir without a trailing slash.
+* @example
+* ```ts
+* trimTrailingSlash("_data/"); // "_data"
+* ```
+*/
+function trimTrailingSlash(dir) {
+	return dir.endsWith("/") ? dir.slice(0, -1) : dir;
+}
+/**
+* Builds the data provider — the agnostic bridge. `write()` is the Node persist
+* side; `at()` is the browser read side; `urlFor`/`fileFor` are the pure
+* convention. No `onStart`/`onStop` (holds no long-lived resource).
+*
+* @param ctx - The data plugin context.
+* @returns The {@link DataProvider} mounted at `app.data`.
+* @example
+* ```ts
+* const api = dataApi(ctx);
+* await api.write([{ path: "/en/hello/", data: article }]); // Node build
+* await api.at("/en/hello/");                               // browser
+* ```
+*/
+function dataApi(ctx) {
+	return {
+		/**
+		* READ (browser) — fetch (and cache) the persisted data for a page path.
+		* Returns the raw JSON as `unknown` (the caller's `route.parse` validates it),
+		* or `null` if the fetch/parse fails (so `spa` can fall back to HTML).
+		*
+		* @param path - The page URL path (e.g. `/en/hello/`).
+		* @returns The page's raw data, or `null` on failure.
+		* @example
+		* ```ts
+		* const raw = await api.at("/en/hello/");
+		* ```
+		*/
+		async at(path) {
+			if (ctx.state.cache.has(path)) return ctx.state.cache.get(path);
+			try {
+				const data = await loadJson(`${ctx.config.baseUrl}${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-BcWqa_7I.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"
+		* ```
+		*/
+		fileFor(path) {
+			return `${trimTrailingSlash(ctx.config.outputDir)}/${dataSuffix(path)}`;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/data/config.ts
+/**
+* Typed default data config (R6: no inline `as`). `outputDir` is the WRITE path
+* (filesystem, relative to the build `outDir`); `baseUrl` is the matching READ URL
+* (site-root-relative) the browser fetches from — the defaults agree
+* (`"_data"` ↔ `"/_data/"`).
+*
+* @example
+* ```ts
+* createPlugin("data", { config: defaultDataConfig });
+* ```
+*/
+const defaultDataConfig = {
+	outputDir: "_data",
+	baseUrl: "/_data/"
+};
+//#endregion
+//#region src/plugins/data/state.ts
+/**
+* Creates initial data state: a null `lastWrite` slot (populated by the Node
+* `write()` side) and an empty `cache` (populated lazily by the browser `at(path)`
+* side on first fetch).
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global framework configuration.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns Fresh data state with no recorded write and an empty per-path cache.
+* @example
+* ```ts
+* const state = createDataState({ global: {}, config });
+* ```
+*/
+function createDataState(_ctx) {
+	return {
+		lastWrite: null,
+		cache: /* @__PURE__ */ new Map()
+	};
+}
+//#endregion
+//#region src/plugins/data/validate.ts
+/**
+* Validates the resolved data config: the browser `baseUrl` must be a non-empty,
+* site-root-relative URL path. The emit/read pipelines are wired in build waves 3/4.
+*
+* @param config - The resolved plugin configuration.
+* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @example
+* ```ts
+* validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
+* ```
+*/
+function validateDataConfig(config) {
+	if (typeof config.baseUrl !== "string" || !config.baseUrl.startsWith("/")) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
+}
+//#endregion
+//#region src/plugins/data/index.ts
+/**
+* @file data — Standard tier plugin (wiring-only). The AGNOSTIC data provider for
+* the SSG→DATA→SPA pattern.
+*
+* Owns ONE contract — `page path → persisted JSON file` — and nothing about what
+* the data is: `write(entries)` persists per-page JSON on Node (build supplies the
+* entries it already expanded); `at(path)` fetches + caches it in the browser as
+* `unknown`, which the route's `parse` validates before `render`. NOT a framework
+* default — the consumer composes it where needed (Node build AND/OR browser app).
+*
+* **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
+* a lazy `import()` inside `write()`. Build ordering is a call-site contract: build
+* writes data during its pages phase (after its Phase-0 clean), via `app.data.write`.
+* No `onStart`/`onStop`.
+* @see README.md
+*/
+/**
+* Data plugin — the agnostic data provider. Mounts `write(entries)` (Node persist),
+* `at(path)` (browser read), and the pure `urlFor`/`fileFor` convention at `app.data`.
+*
+* @example
+* ```ts
+* // Node build: `build` calls app.data.write(...) during its pages phase when
+* // router.mode !== "ssg". Just compose the plugin:
+* const app = createApp({
+*   plugins: [dataPlugin, contentPlugin, buildPlugin],
+*   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+* });
+* await app.start();
+* await app.build.run();   // writes HTML + per-page data sidecars
+*
+* // Browser app: compose `dataPlugin` too; spa fetches via app.data.at(path) on nav.
+* ```
+*/
+const dataPlugin = createPlugin$1("data", {
+	config: defaultDataConfig,
+	createState: createDataState,
+	onInit: (ctx) => validateDataConfig(ctx.config),
+	api: dataApi
+});
+//#endregion
+//#region src/plugins/data/types.ts
+var types_exports = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/plugins/env/types.ts
+var types_exports$1 = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/plugins/head/types.ts
+var types_exports$2 = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/plugins/log/types.ts
+var types_exports$3 = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/plugins/router/types.ts
+var types_exports$4 = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/browser.ts
+/**
+* @file `@moku-labs/web/browser` — the browser-safe entry point.
+*
+* A node-excluded view of the main `@moku-labs/web` entry: the SAME `createApp`
+* over the SAME isomorphic plugin set (`site`, `i18n`, `router`, `head`, `spa`,
+* plus the `log`/`env` core), but with **zero** node/native code in its static
+* import graph. Where the main entry re-exports the node-only plugins
+* (`content`/`build`/`deploy`) and the node env providers (`dotenv`/`processEnv`/
+* `cloudflareBindings`, which import `node:fs`), this entry omits them entirely —
+* so importing it can never drag the Node graph into a client bundle, regardless
+* of the consumer's bundler or tree-shaking. Built as its own ESM-only pass so the
+* graph never even references the node-only modules (see `tsdown.config.ts`).
+*
+* It also pre-wires `browserEnv()` as the default `env` provider, so env (and
+* `import.meta.env`-based dev/prod/test detection) works with zero consumer config.
+*
+* The optional `data` plugin is exported (its read-half is browser-safe) but, like
+* in the main entry, is consumer-composed for `router.mode("spa"|"hybrid")`.
+* @see src/index.ts — the full (Node-capable) entry.
+*/
+const core = createCore(coreConfig, {
+	plugins: [
+		sitePlugin,
+		i18nPlugin,
+		routerPlugin,
+		headPlugin,
+		spaPlugin
+	],
+	pluginConfigs: { env: { providers: [browserEnv()] } }
+});
+/**
+* Create and initialize a browser-safe `@moku-labs/web` application — the Layer-3
+* entry point for client bundles. Identical to the main entry's `createApp`, but
+* this module's import graph contains zero node/native code, and `env` defaults to
+* the `browserEnv()` provider (reads `import.meta.env` / `globalThis.__ENV__`).
+*
+* The defaults are the isomorphic plugin set (`site`, `i18n`, `router`, `head`,
+* `spa` + `log`/`env` core). For client-data navigation (`router.mode("spa"|"hybrid")`)
+* compose the `data` plugin — its consume-half (`at()`) is browser-safe.
+*
+* @param options - Optional configuration:
+*  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
+*  - `config` — global framework config (e.g. `{ mode: "development" }`).
+*  - `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();
+* app.env.get("PUBLIC_API_URL"); // resolved from import.meta.env
+* ```
+*/
+const createApp = core.createApp;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and core
+* APIs. Plugin types are inferred from the spec object — never written explicitly.
+* Pass the result to {@link createApp} via `plugins`.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+*
+* const app = createApp({ plugins: [analytics] });
+* ```
+*/
+const createPlugin = 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 };