@moku-labs/web 0.1.0-alpha.1

package/dist/factory-DwpBwjDk.mjs

@@ -0,0 +1,1602 @@
+import { a as meta, i as jsonLd, n as feedLink, o as og, r as hreflang, s as twitter, t as canonical } from "./primitives-gO5i1tD8.mjs";
+import { buildArticleHead } from "./plugins/head/build.mjs";
+import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
+
+//#region src/plugins/env/api.ts
+/**
+* Build the env plugin's public API surface over the resolved state.
+*
+* Reads from `ctx.state.resolved` (all validated values) and `ctx.state.publicMap`
+* (subset where `schema[key].public === true`). State Maps are frozen at `onInit`
+* by `validateSchema`, so the API is effectively read-only.
+*
+* @param ctx - The env plugin context ({ state, config }).
+* @returns An EnvApi with `get`, `has`, `require`, `getPublic`, `getPublicMap`.
+* @example
+* const api = createEnvApi({ state, config })
+* api.get('PUBLIC_SITE_URL')        // 'https://example.com' | undefined
+* api.require('API_SECRET')         // 'sekret' or throws
+* api.getPublic()                   // Readonly<Record<string, string>>
+* api.getPublicMap()                // ReadonlyMap<string, string>
+*/
+const createEnvApi = (ctx) => ({
+	get: (key) => ctx.state.resolved.get(key),
+	require: (key) => {
+		const v = ctx.state.resolved.get(key);
+		if (v === void 0) throw new Error(`env: required key "${key}" missing`);
+		return v;
+	},
+	getPublic: () => Object.freeze(Object.fromEntries(ctx.state.publicMap)),
+	getPublicMap: () => ctx.state.publicMap,
+	has: (key) => ctx.state.resolved.has(key)
+});
+
+//#endregion
+//#region src/plugins/env/state.ts
+const createEnvState = () => ({
+	resolved: /* @__PURE__ */ new Map(),
+	publicMap: /* @__PURE__ */ new Map()
+});
+
+//#endregion
+//#region src/plugins/env/validate.ts
+/**
+* Deep-freeze a Map: forbid `set`, `clear`, `delete` mutations after sealing.
+*
+* `Object.freeze(map)` only freezes the binding — it does NOT block `map.set()`.
+* We override the mutator methods with a non-configurable, non-writable property
+* that throws on call, then freeze the binding for defense in depth.
+*
+* @param m - The Map to seal.
+* @returns The same Map instance, now immutable.
+* @example
+* const m = freezeMap(new Map([['a', '1']]))
+* m.get('a') // '1'
+* m.set('b', '2') // throws TypeError
+*/
+const freezeMap = (m) => {
+	const throwFrozen = () => {
+		throw new TypeError("env: map is frozen and cannot be mutated");
+	};
+	Object.defineProperty(m, "set", {
+		value: throwFrozen,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(m, "clear", {
+		value: throwFrozen,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(m, "delete", {
+		value: throwFrozen,
+		writable: false,
+		configurable: false
+	});
+	Object.freeze(m);
+	return m;
+};
+/**
+* Walk providers in declaration order; first non-undefined wins per key.
+* Empty strings are coerced to undefined unconditionally before precedence.
+*
+* @param providers - The provider list from EnvConfig.
+* @returns A merged record of resolved values.
+*/
+const mergeProviders = (providers) => {
+	const merged = {};
+	for (const provider of providers) {
+		const loaded = provider.load();
+		for (const key of Object.keys(loaded)) {
+			const raw = loaded[key];
+			const value = raw === "" ? void 0 : raw;
+			if (merged[key] === void 0 && value !== void 0) merged[key] = value;
+		}
+	}
+	return merged;
+};
+/**
+* Enforce the PUBLIC_ prefix cross-check in both directions over schema keys.
+*
+* @param schema - The env schema.
+* @param publicPrefix - The configured prefix (default `PUBLIC_`).
+* @throws Error when a schema key violates the cross-check.
+*/
+const assertPublicPrefix = (schema, publicPrefix) => {
+	for (const key of Object.keys(schema)) {
+		const spec = schema[key];
+		if (!spec) continue;
+		const hasPrefix = key.startsWith(publicPrefix);
+		if (spec.public && !hasPrefix) throw new Error(`env: schema key "${key}" is public:true but does not start with prefix "${publicPrefix}"`);
+		if (!spec.public && hasPrefix) throw new Error(`env: schema key "${key}" starts with prefix "${publicPrefix}" but is public:false`);
+	}
+};
+/**
+* Apply schema-declared defaults for keys still unresolved after provider merge.
+*
+* @param merged - The merged provider record (mutated in place).
+* @param schema - The env schema.
+*/
+const applyDefaults = (merged, schema) => {
+	for (const key of Object.keys(schema)) {
+		const spec = schema[key];
+		if (!spec) continue;
+		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
+	}
+};
+/**
+* Enforce that every `required: true` schema key has a resolved value.
+*
+* @param merged - The merged provider record (post-defaults).
+* @param schema - The env schema.
+* @throws Error including the missing key name.
+*/
+const assertRequired = (merged, schema) => {
+	for (const key of Object.keys(schema)) {
+		if (!schema[key]?.required) continue;
+		if (merged[key] === void 0) throw new Error(`env: required key "${key}" is missing (unresolved after providers + default)`);
+	}
+};
+/**
+* Populate the `resolved` and `publicMap` state Maps from a validated merge.
+*
+* @param state - The env state to populate.
+* @param merged - The validated merged record.
+* @param schema - The env schema (drives publicMap subset selection).
+*/
+const populateState = (state, merged, schema) => {
+	for (const key of Object.keys(merged)) {
+		const value = merged[key];
+		if (value !== void 0) state.resolved.set(key, value);
+	}
+	for (const key of Object.keys(schema)) {
+		if (!schema[key]?.public) continue;
+		const value = state.resolved.get(key);
+		if (value !== void 0) state.publicMap.set(key, value);
+	}
+};
+/**
+* Validate the env schema, resolve values from providers, and populate state.
+*
+* Walks providers in order (first non-undefined wins per key), coerces empty
+* strings to undefined UNCONDITIONALLY, enforces the PUBLIC_ prefix cross-check
+* in both directions, applies defaults, enforces required keys, and freezes
+* both `resolved` and `publicMap` state Maps.
+*
+* This MUST be called from the env plugin's `onInit` so failures surface at
+* `createApp()` time — never on first `.get()`.
+*
+* @param ctx - The env plugin context ({ state, config }).
+* @throws Error when PUBLIC_ prefix cross-check fails (in either direction).
+* @throws Error when a required key resolves to undefined.
+* @example
+* validateSchema({ state, config: { schema, providers, publicPrefix: 'PUBLIC_' } })
+*/
+const validateSchema = (ctx) => {
+	const { schema, providers, publicPrefix } = ctx.config;
+	const merged = mergeProviders(providers);
+	assertPublicPrefix(schema, publicPrefix);
+	applyDefaults(merged, schema);
+	assertRequired(merged, schema);
+	populateState(ctx.state, merged, schema);
+	freezeMap(ctx.state.resolved);
+	freezeMap(ctx.state.publicMap);
+};
+
+//#endregion
+//#region src/plugins/env/index.ts
+/** @file Core plugin: universal env injection with schema + providers + PUBLIC_ cross-validation at onInit. */
+const env = createCorePlugin("env", {
+	config: {
+		schema: {},
+		providers: [],
+		publicPrefix: "PUBLIC_"
+	},
+	createState: createEnvState,
+	api: createEnvApi,
+	onInit: (ctx) => {
+		validateSchema(ctx);
+	}
+});
+
+//#endregion
+//#region src/plugins/log/expect.ts
+/**
+* Dedicated assertion error for the log expect DSL — keeps stack traces clean
+* and lets test runners distinguish framework assertions from generic Errors.
+*/
+var LogExpectAssertionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LogExpectAssertionError";
+	}
+};
+/** Element-wise array match — same length AND each pair satisfies matchesPartial. */
+const matchArrays = (actual, partial) => {
+	if (!Array.isArray(actual) || actual.length !== partial.length) return false;
+	return partial.every((v, i) => matchesPartial(actual[i], v));
+};
+/** Subset object match — every key in `partial` recursively present on `actual`. */
+const matchObjects = (actual, partial) => {
+	for (const key of Object.keys(partial)) if (!matchesPartial(actual[key], partial[key])) return false;
+	return true;
+};
+/**
+* Subset-equality matcher. Returns true when every key in `partial` exists on
+* `actual` with an equal (or recursively-matching) value.
+*
+* Semantics:
+* - Primitives compared with `Object.is`.
+* - Plain objects matched recursively via this same function.
+* - Arrays compared element-wise via this same function (length must match).
+* - `actual` must be a non-null object for any non-empty partial.
+*
+* @param actual - The candidate value (typically `entry.data`).
+* @param partial - Expected subset shape.
+* @returns Whether `actual` contains the partial shape.
+*/
+const matchesPartial = (actual, partial) => {
+	if (Object.is(actual, partial)) return true;
+	if (partial === null || typeof partial !== "object") return false;
+	if (actual === null || typeof actual !== "object") return false;
+	if (Array.isArray(partial)) return matchArrays(actual, partial);
+	if (Array.isArray(actual)) return false;
+	return matchObjects(actual, partial);
+};
+/**
+* Find the first entry index matching event name + optional partial.
+* @param entries - Array to scan.
+* @param event - Event name.
+* @param partial - Optional partial data match.
+* @param from - Start index (inclusive).
+* @returns Matching index or -1.
+*/
+const findEntry = (entries, event, partial, from = 0) => {
+	for (let i = from; i < entries.length; i++) {
+		const e = entries[i];
+		if (!e || e.event !== event) continue;
+		if (partial === void 0) return i;
+		if (matchesPartial(e.data, partial)) return i;
+	}
+	return -1;
+};
+/**
+* Create a fluent assertion chain bound to a live entries array.
+*
+* The chain reads `entries` on each call — assertions reflect the current
+* state, not a snapshot at chain creation. Returned methods always return the
+* same chain object so they can be chained.
+*
+* @param entries - Reference to the plugin state entries (live, not copied).
+* @returns An {@link ExpectChain} with toHaveEvent / toHaveEventInOrder / toNotHaveEvent.
+* @example
+* ```ts
+* createExpectChain(state.entries)
+*   .toHaveEvent('build:phase', { phase: 'content' })
+*   .toHaveEventInOrder(['build:start', 'build:complete'])
+*   .toNotHaveEvent('build:error')
+* ```
+*/
+const createExpectChain = (entries) => {
+	const chain = {
+		toHaveEvent: (event, partial) => {
+			if (findEntry(entries, event, partial) === -1) throw new LogExpectAssertionError(`Expected log to contain event "${event}"${partial ? ` matching ${JSON.stringify(partial)}` : ""}, but no matching entry was found.`);
+			return chain;
+		},
+		toHaveEventInOrder: (events) => {
+			let cursor = 0;
+			for (const name of events) {
+				const idx = findEntry(entries, name, void 0, cursor);
+				if (idx === -1) throw new LogExpectAssertionError(`Expected log to contain event "${name}" in order after index ${cursor - 1}, but it was not found. Sequence: ${JSON.stringify(events)}.`);
+				cursor = idx + 1;
+			}
+			return chain;
+		},
+		toNotHaveEvent: (event, partial) => {
+			const idx = findEntry(entries, event, partial);
+			if (idx !== -1) throw new LogExpectAssertionError(`Expected log to NOT contain event "${event}"${partial ? ` matching ${JSON.stringify(partial)}` : ""}, but entry at index ${idx} matched.`);
+			return chain;
+		}
+	};
+	return chain;
+};
+
+//#endregion
+//#region src/plugins/log/api.ts
+/** @file log plugin API factory — info/debug/warn/error append + sink fan-out, plus trace/reset/addSink/expect. */
+/**
+* Build a LogEntry and dispatch it to every registered sink.
+* @param ctx - Plugin context (state + config).
+* @param level - Severity level.
+* @param event - Event identifier.
+* @param data - Optional structured payload.
+*/
+const append = (ctx, level, event, data) => {
+	const entry = {
+		level,
+		event,
+		data,
+		ts: Date.now()
+	};
+	ctx.state.entries.push(entry);
+	for (const sink of ctx.state.sinks) sink.write(entry);
+};
+/**
+* Creates the log API bound to a plugin context.
+*
+* @param ctx - Core plugin context containing state and config.
+* @returns A {@link LogApi} suitable for injection onto regular plugin contexts.
+* @example
+* ```ts
+* const api = createLogApi({ state: createLogState(), config: { level: 'debug', mode: 'test' } })
+* api.info('hello', { x: 1 })
+* api.expect().toHaveEvent('hello', { x: 1 })
+* ```
+*/
+const createLogApi = (ctx) => ({
+	info: (event, data) => append(ctx, "info", event, data),
+	debug: (event, data) => append(ctx, "debug", event, data),
+	warn: (event, data) => append(ctx, "warn", event, data),
+	error: (event, data, err) => {
+		append(ctx, "error", event, err === void 0 ? data : {
+			...data && typeof data === "object" ? data : {},
+			error: {
+				message: err.message,
+				stack: err.stack
+			}
+		});
+	},
+	trace: () => Object.freeze([...ctx.state.entries]),
+	expect: () => createExpectChain(ctx.state.entries),
+	addSink: (sink) => {
+		ctx.state.sinks.push(sink);
+	},
+	reset: () => {
+		ctx.state.entries.length = 0;
+	}
+});
+
+//#endregion
+//#region src/plugins/log/sinks/console.ts
+const RANK = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+/**
+* Numeric rank for a level — higher = more severe.
+* @param level - Log level.
+* @returns Numeric severity.
+*/
+const levelRank = (level) => RANK[level];
+/**
+* Build a console sink that emits JSON-stringified entries to the appropriate
+* console channel (`console.log` for debug/info, `console.warn` for warn,
+* `console.error` for error). Entries below `minLevel` are dropped.
+*
+* @param minLevel - Minimum severity to emit (default `'info'`).
+* @returns A {@link LogSink}.
+* @example
+* ```ts
+* const sink = consoleSink('warn')
+* sink.write({ level: 'info', event: 'x', ts: 0 })  // dropped
+* sink.write({ level: 'error', event: 'boom', ts: 0 }) // console.error(...)
+* ```
+*/
+const consoleSink = (minLevel = "info") => {
+	const min = levelRank(minLevel);
+	return { write: (entry) => {
+		if (levelRank(entry.level) < min) return;
+		const serialized = JSON.stringify(entry);
+		if (entry.level === "error") console.error(serialized);
+		else if (entry.level === "warn") console.warn(serialized);
+		else console.log(serialized);
+	} };
+};
+
+//#endregion
+//#region src/plugins/log/sinks/json.ts
+/**
+* Build a sink that writes `JSON.stringify(entry) + '\n'` to a Node writable
+* stream. Use with `process.stderr`, a `fs.WriteStream`, or any
+* `NodeJS.WritableStream`-compatible target.
+*
+* @param stream - A writable stream that accepts string chunks.
+* @returns A {@link LogSink}.
+* @example
+* ```ts
+* import { jsonSink } from '@moku-labs/web/log/sinks/json'
+* const sink = jsonSink(process.stderr)
+* sink.write({ level: 'error', event: 'crash', ts: Date.now() })
+* ```
+*/
+const jsonSink = (stream) => ({ write: (entry) => {
+	stream.write(`${JSON.stringify(entry)}\n`);
+} });
+
+//#endregion
+//#region src/plugins/log/state.ts
+const createLogState = () => ({
+	entries: [],
+	sinks: []
+});
+
+//#endregion
+//#region src/plugins/log/index.ts
+/** @file Core plugin: in-memory trace + expect() DSL for LLM-verifiable test assertions. Sinks at onInit (not onStart). */
+const log = createCorePlugin("log", {
+	config: {
+		level: "info",
+		mode: "auto"
+	},
+	createState: createLogState,
+	api: createLogApi,
+	onInit: (ctx) => {
+		const mode = ctx.config.mode === "auto" ? resolveAutoMode() : ctx.config.mode;
+		if (mode === "test") return;
+		ctx.state.sinks.push(consoleSink(ctx.config.level));
+		if (mode === "production") ctx.state.sinks.push(jsonSink(process.stderr));
+	}
+});
+/**
+* Resolves the effective log mode when `config.mode === 'auto'`.
+*
+* Reads `process.env.NODE_ENV`: `'test'` or `'production'` flow through;
+* any other value (including undefined or non-Node runtimes) resolves to `'dev'`.
+*
+* @returns The resolved mode used to pick default sinks at `onInit`.
+*/
+function resolveAutoMode() {
+	const nodeEnv = typeof process !== "undefined" ? process.env.NODE_ENV : void 0;
+	if (nodeEnv === "test" || nodeEnv === "production") return nodeEnv;
+	return "dev";
+}
+
+//#endregion
+//#region src/config.ts
+/** @file Framework config — single createCoreConfig call. Exports createPlugin, createCore. */
+/** Bound factory chain for moku-web. */
+const coreConfig = createCoreConfig("moku-web", {
+	config: { mode: "production" },
+	plugins: [log, env]
+});
+const { createPlugin, createCore } = coreConfig;
+
+//#endregion
+//#region src/plugins/i18n/api.ts
+const createI18nApi = (ctx) => ({
+	locales: () => ctx.state.config.locales,
+	defaultLocale: () => ctx.state.config.defaultLocale,
+	localeName: (locale) => ctx.state.config.localeNames[locale],
+	ogLocale: (locale) => ctx.state.config.ogLocaleMap?.[locale] ?? locale,
+	t: (locale, key) => ctx.state.config.translations?.[locale]?.[key] ?? key
+});
+
+//#endregion
+//#region src/plugins/i18n/state.ts
+const createI18nState = (config) => ({ config });
+
+//#endregion
+//#region src/plugins/i18n/validate.ts
+/**
+* Recursively `Object.freeze` an object and all nested object/array values.
+*
+* Required because plain `Object.freeze` is shallow — nested records like
+* `localeNames` and `translations` would remain mutable otherwise.
+*
+* @param value - The value to freeze (no-op for primitives).
+*/
+const deepFreeze$1 = (value) => {
+	if (value === null || typeof value !== "object") return;
+	if (Object.isFrozen(value)) return;
+	Object.freeze(value);
+	for (const key of Object.keys(value)) deepFreeze$1(value[key]);
+};
+/**
+* Validate i18n config and replace state.config with a deeply frozen copy.
+*
+* Runs in the i18n plugin's `onInit`. Failures surface at `createApp()` time,
+* never on first API call.
+*
+* @param ctx - The i18n plugin context ({ state, config }).
+* @throws Error when `defaultLocale` is not a member of `locales`.
+* @throws Error when `locales` is empty.
+*/
+const validateAndFreeze$2 = (ctx) => {
+	const { locales, defaultLocale } = ctx.config;
+	if (locales.length === 0) throw new Error("i18n: locales must contain at least one entry");
+	if (!locales.includes(defaultLocale)) throw new Error(`i18n: defaultLocale "${defaultLocale}" must be one of locales [${locales.join(", ")}]`);
+	const frozen = { ...ctx.config };
+	deepFreeze$1(frozen);
+	ctx.state.config = frozen;
+};
+
+//#endregion
+//#region src/plugins/i18n/index.ts
+/** @file i18n plugin: locales + translations + t() helper. Standard tier. Reads ctx.env (Core). */
+const defaultConfig$2 = {
+	locales: [],
+	defaultLocale: "",
+	localeNames: {},
+	ogLocaleMap: {},
+	translations: {}
+};
+const i18n = createPlugin("i18n", {
+	config: defaultConfig$2,
+	createState: (ctx) => createI18nState(ctx.config),
+	api: createI18nApi,
+	onInit: validateAndFreeze$2
+});
+
+//#endregion
+//#region src/plugins/site/api.ts
+const createSiteApi = (ctx) => ({
+	get: () => ctx.state.config,
+	name: () => ctx.state.config.name,
+	url: () => ctx.state.config.url,
+	author: () => ctx.state.config.author,
+	description: () => ctx.state.config.description
+});
+
+//#endregion
+//#region src/plugins/site/state.ts
+const createSiteState = (config) => ({ config });
+
+//#endregion
+//#region src/plugins/site/validate.ts
+/**
+* Validate site URL: must be http(s), must not have a trailing slash.
+*
+* @param url - The URL string from SiteConfig.
+* @throws Error when URL is empty, lacks http(s) protocol, or has a trailing slash.
+*/
+const assertValidUrl = (url) => {
+	if (url === "") throw new Error("site: url is required (received empty string)");
+	if (url.endsWith("/")) throw new Error(`site: url "${url}" must not have a trailing slash`);
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`site: url "${url}" is not a valid URL`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`site: url "${url}" must use http(s) protocol (got "${parsed.protocol}")`);
+};
+/**
+* Validate site config and replace state.config with a frozen copy.
+*
+* Runs in the site plugin's `onInit`. Failures surface at `createApp()` time,
+* never on first `.get()`. After this call, `state.config` is `Object.freeze`d
+* so consumer code cannot mutate it.
+*
+* @param ctx - The site plugin context ({ state, config }).
+* @throws Error when the URL is invalid (empty, non-http(s), or trailing slash).
+*/
+const validateAndFreeze$1 = (ctx) => {
+	assertValidUrl(ctx.config.url);
+	ctx.state.config = Object.freeze({ ...ctx.config });
+};
+
+//#endregion
+//#region src/plugins/site/index.ts
+/** @file site plugin: global site metadata. Standard tier. */
+const site = createPlugin("site", {
+	config: {
+		name: "",
+		url: "",
+		author: "",
+		description: ""
+	},
+	createState: (ctx) => createSiteState(ctx.config),
+	api: createSiteApi,
+	onInit: validateAndFreeze$1
+});
+
+//#endregion
+//#region src/plugins/router/match.ts
+const PARAM_RE = /^\{([a-z_][a-z0-9_]*)(:\?)?\}$/i;
+const hasBrace = (part) => part.includes("{") || part.includes("}");
+const assertSegment = (name, pattern, part) => {
+	if (part === "") throw new Error(`router: route "${name}" pattern contains empty segment — got "${pattern}"`);
+	if (hasBrace(part) && !PARAM_RE.test(part)) throw new Error(`router: route "${name}" has malformed param segment "${part}" in pattern "${pattern}"`);
+};
+/**
+* Assert a route pattern is well-formed.
+*
+* Rules:
+*   - must start with `/`
+*   - each non-root segment is either static (no braces) or `{name}` / `{name:?}`
+*     where `name` matches `[a-z_][a-z0-9_]*` (case-insensitive)
+*
+* @param name - The route key from the routes map (for error messages).
+* @param pattern - The pattern to validate.
+* @throws Error when the pattern is malformed.
+*/
+const validatePattern = (name, pattern) => {
+	if (!pattern.startsWith("/")) throw new Error(`router: route "${name}" pattern must start with "/" — got "${pattern}"`);
+	if (pattern === "/") return;
+	const parts = (pattern.endsWith("/") ? pattern.slice(0, -1) : pattern).split("/").slice(1);
+	for (const part of parts) assertSegment(name, pattern, part);
+};
+/**
+* Classify a raw segment string into a `Segment`.
+*
+* @param part - One slash-separated portion of a pattern.
+* @returns Either a static segment or a param segment.
+*/
+const classifySegment = (part) => {
+	const m = PARAM_RE.exec(part);
+	if (m === null) return {
+		kind: "static",
+		value: part
+	};
+	return {
+		kind: "param",
+		name: m[1],
+		optional: m[2] === ":?"
+	};
+};
+/**
+* Parse a route pattern into segments + trailing-slash flag.
+*
+* @param pattern - The route pattern (must begin with `/`).
+* @returns The parsed pattern.
+*/
+const parsePattern = (pattern) => {
+	const trailingSlash = pattern.length > 1 && pattern.endsWith("/");
+	return {
+		segments: (trailingSlash ? pattern.slice(0, -1) : pattern).split("/").slice(1).filter((p) => p !== "").map(classifySegment),
+		trailingSlash
+	};
+};
+/**
+* Compute a specificity score for a pattern. Higher scores match first.
+*
+* Each static segment contributes +100; each required param -1; each optional
+* param -2. This guarantees any pure-static pattern outranks any pattern with
+* params, and required params outrank optional params at equal static counts.
+*
+* @param pattern - The route pattern.
+* @returns A specificity score (may be negative for purely dynamic patterns).
+*/
+const computeSpecificity = (pattern) => {
+	const { segments } = parsePattern(pattern);
+	let score = 0;
+	for (const s of segments) if (s.kind === "static") score += 100;
+	else score -= s.optional ? 2 : 1;
+	return score;
+};
+/**
+* Split a URL into its path segments + trailing-slash flag.
+*
+* @param url - The URL path (must begin with `/`).
+* @returns The split URL pieces.
+*/
+const splitUrl = (url) => {
+	const trailingSlash = url.length > 1 && url.endsWith("/");
+	return {
+		parts: (trailingSlash ? url.slice(0, -1) : url).split("/").slice(1).filter((p) => p !== ""),
+		trailingSlash
+	};
+};
+/**
+* Verify the trailing-slash convention matches between pattern and URL.
+*
+* @param parsed - Parsed pattern.
+* @param url - URL string.
+* @param trailingSlash - Whether the URL has a trailing slash.
+* @returns True when the trailing-slash style matches.
+*/
+const trailingSlashMatches = (parsed, url, trailingSlash) => {
+	if (url === "/") return true;
+	return parsed.trailingSlash === trailingSlash;
+};
+/**
+* Apply one segment against a URL part; mutate params or return `false` on miss.
+*
+* @param seg - The pattern segment to apply.
+* @param part - The URL part at this position.
+* @param params - Accumulator for extracted params (mutated on success).
+* @returns True when this segment matches the part.
+*/
+const applySegment = (seg, part, params) => {
+	if (seg.kind === "static") return seg.value === part;
+	params[seg.name] = part;
+	return true;
+};
+/**
+* Walk segments + URL parts, extracting param values. Optional params are
+* skipped from the left when the URL is shorter than the pattern.
+*
+* @param segments - The pattern segments.
+* @param parts - The URL parts.
+* @returns The extracted params, or `null` when the URL does not match.
+*/
+const extractParams = (segments, parts) => {
+	const requiredCount = segments.filter((s) => !(s.kind === "param" && s.optional)).length;
+	if (parts.length < requiredCount || parts.length > segments.length) return null;
+	let skipsLeft = segments.length - parts.length;
+	const params = {};
+	let i = 0;
+	for (const seg of segments) {
+		if (seg.kind === "param" && seg.optional && skipsLeft > 0) {
+			skipsLeft -= 1;
+			continue;
+		}
+		const part = parts[i];
+		if (part === void 0 || !applySegment(seg, part, params)) return null;
+		i += 1;
+	}
+	return params;
+};
+/**
+* Try to match a single pattern against a URL path; return params or null.
+*
+* @param pattern - The route pattern.
+* @param url - The URL path.
+* @returns Extracted params, or `null` when the pattern does not match.
+*/
+const tryMatch = (pattern, url) => {
+	const parsed = parsePattern(pattern);
+	const { parts, trailingSlash } = splitUrl(url);
+	if (!trailingSlashMatches(parsed, url, trailingSlash)) return null;
+	return extractParams(parsed.segments, parts);
+};
+/**
+* Walk entries in specificity order and return the first match.
+*
+* @param entries - Route entries (must be sorted by specificity descending).
+* @param url - The URL path to match.
+* @returns The matching entry and params, or `null` when nothing matches.
+*/
+const matchUrl = (entries, url) => {
+	for (const entry of entries) {
+		const params = tryMatch(entry.spec.pattern, url);
+		if (params !== null) return {
+			entry,
+			params
+		};
+	}
+	return null;
+};
+/**
+* Render one pattern segment as a URL piece, or `null` if the segment is an
+* absent optional param.
+*
+* @param seg - The pattern segment.
+* @param params - The provided param map.
+* @param pattern - The full pattern (for error messages).
+* @returns The rendered piece, or `null` to drop the segment.
+* @throws Error when a required param is missing.
+*/
+const renderSegment = (seg, params, pattern) => {
+	if (seg.kind === "static") return seg.value;
+	const value = params[seg.name];
+	if (value !== void 0) return value;
+	if (seg.optional) return null;
+	throw new Error(`router: missing required param "${seg.name}" for pattern "${pattern}"`);
+};
+/**
+* Build a URL string from a pattern by substituting params.
+*
+* Optional params absent from `params` collapse out of the URL. Required params
+* missing from `params` throw — callers should never attempt to generate an
+* incomplete URL.
+*
+* @param pattern - The route pattern.
+* @param params - Map of param name -> value.
+* @returns The generated URL.
+* @throws Error when a required param is missing.
+*/
+const generateUrl = (pattern, params) => {
+	const parsed = parsePattern(pattern);
+	const pieces = [];
+	for (const seg of parsed.segments) {
+		const rendered = renderSegment(seg, params, pattern);
+		if (rendered !== null) pieces.push(rendered);
+	}
+	const body = pieces.join("/");
+	if (body === "") return "/";
+	return `/${body}${parsed.trailingSlash ? "/" : ""}`;
+};
+
+//#endregion
+//#region src/plugins/router/api.ts
+/** @file Router API factory — routes, toUrl, match, entries. */
+/**
+* Build the router public API from plugin context.
+*
+* `match` and `entries` delegate to the precomputed sorted entries; `toUrl` looks
+* up the named route and substitutes the supplied params via `generateUrl`.
+*
+* @param ctx - Plugin execution context with `state` and `config`.
+* @returns The router API.
+*/
+const createRouterApi = (ctx) => ({
+	routes: ctx.state.routes,
+	toUrl: (name, params) => {
+		const spec = ctx.state.routes[name];
+		if (spec === void 0) throw new Error(`router: unknown route name "${String(name)}"`);
+		return generateUrl(spec.pattern, params);
+	},
+	match: (url) => matchUrl(ctx.state.entries, url),
+	entries: () => ctx.state.entries
+});
+
+//#endregion
+//#region src/plugins/router/state.ts
+/** @file Router state factory — builds sorted RouteEntry list from a routes map. */
+/**
+* Create the router's mutable state from a `routes` map.
+*
+* Each entry receives a precomputed specificity score; entries are sorted
+* descending so `matchUrl` walks the most specific patterns first. The returned
+* `entries` array is frozen to prevent external mutation.
+*
+* @param routes - Map of route name -> RouteSpec.
+* @returns A `RouterState` with `routes` (as given) and a frozen, sorted `entries` list.
+*/
+const createRouterState$1 = (routes) => {
+	const entries = Object.entries(routes).map(([name, spec]) => ({
+		name,
+		spec,
+		specificity: computeSpecificity(spec.pattern)
+	}));
+	entries.sort((a, b) => b.specificity - a.specificity);
+	return {
+		routes,
+		entries: Object.freeze(entries)
+	};
+};
+
+//#endregion
+//#region src/plugins/router/route-builder.ts
+/**
+* Build a `RouteSpec` via a fluent, non-accumulating builder.
+*
+* Methods mutate a single internal `RouteSpec` and return the same builder typed
+* as `RouteBuilder` (NOT `RouteBuilder<T>`). Type information lives on the
+* `RouteSpec` shape, not in builder generics — this keeps TS inference O(1) per
+* route and prevents the 50+ route inference collapse described in D5.
+*
+* @param pattern - URL pattern (e.g. `/about`, `/{slug}`, `/{lang:?}/{slug}/`).
+* @returns A `RouteBuilder` that mutates an internal spec.
+* @example
+* ```ts
+* const home = route('/{lang:?}/').render(({ locale }) => <Home locale={locale} />)
+* ```
+*/
+function route(pattern) {
+	const spec = { pattern };
+	const builder = {
+		load: (fn) => {
+			spec.load = fn;
+			return builder;
+		},
+		layout: (component) => {
+			spec.layout = component;
+			return builder;
+		},
+		render: (fn) => {
+			spec.render = fn;
+			return builder;
+		},
+		generate: (fn) => {
+			spec.generate = fn;
+			return builder;
+		},
+		head: (fn) => {
+			spec.head = fn;
+			return builder;
+		},
+		meta: (data) => {
+			spec.meta = data;
+			return builder;
+		},
+		toJson: (fn) => {
+			spec.toJson = fn;
+			return builder;
+		},
+		toFile: (fn) => {
+			spec.toFile = fn;
+			return builder;
+		},
+		_spec: () => spec
+	};
+	return builder;
+}
+
+//#endregion
+//#region src/plugins/router/index.ts
+/** @file router plugin: fluent route() builder + RouteSpec + matching. Standard tier. */
+const defaultConfig$1 = { routes: {} };
+const router = createPlugin("router", {
+	depends: [site, i18n],
+	config: defaultConfig$1,
+	events: (register) => ({ "router:registered": register("Routes registered at init") }),
+	createState: (ctx) => createRouterState$1(ctx.config.routes),
+	api: createRouterApi,
+	onInit: (ctx) => {
+		for (const entry of ctx.state.entries) validatePattern(entry.name, entry.spec.pattern);
+		ctx.emit("router:registered", { routeCount: ctx.state.entries.length });
+	}
+});
+
+//#endregion
+//#region src/plugins/head/api.ts
+/** @file head plugin API factory — render(), buildArticleHead, and primitives surface. */
+/**
+* HTML-escape a string for safe insertion into an attribute value or text node.
+* Order matters: `&` must be escaped first so we do not double-escape the
+* `&...;` sequences emitted by subsequent rules.
+*
+* @param raw - The unsafe string.
+* @returns Escaped string safe to interpolate between double quotes or as text.
+*/
+const escapeHtml = (raw) => raw.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/**
+* Serialize a single HeadElement to its HTML string form.
+*
+* `script` elements emit `content` verbatim — the jsonLd primitive is
+* responsible for the unicode-escape XSS hardening, so additional HTML
+* escaping here would corrupt the JSON payload. All attribute values are
+* always HTML-escaped.
+*
+* @param element - The HeadElement to serialize.
+* @returns A single line of HTML.
+*/
+const renderElement = (element) => {
+	const attributes = Object.entries(element.attrs).map(([key, value]) => `${key}="${escapeHtml(value)}"`).join(" ");
+	if (element.tag === "script") return `<script ${attributes}>${element.content ?? ""}<\/script>`;
+	if (element.tag === "title") return `<title>${escapeHtml(element.content ?? "")}</title>`;
+	return attributes.length === 0 ? `<${element.tag}>` : `<${element.tag} ${attributes}>`;
+};
+const hasCanonical = (elements) => Boolean(elements?.some((element) => element.tag === "link" && element.attrs.rel === "canonical"));
+/**
+* Factory for head plugin API. The returned `render` closes over the (post-onInit)
+* frozen plugin config so `autoCanonical` and other config flags are observed.
+*
+* @param ctx - Plugin context with `state` (HeadState) and `config` (HeadPluginConfig).
+* @returns The HeadApi surface (`render`, `primitives`, `buildArticleHead`).
+*/
+const createHeadApi = (ctx) => {
+	const render = (config, renderCtx) => {
+		const parts = [];
+		if (config.title !== void 0) parts.push(`<title>${escapeHtml(config.title)}</title>`);
+		if (config.elements) for (const element of config.elements) parts.push(renderElement(element));
+		if (ctx.state.config.autoCanonical === true && !hasCanonical(config.elements) && renderCtx.url.length > 0) parts.push(renderElement(canonical(renderCtx.url)));
+		return parts.join("\n");
+	};
+	return {
+		render,
+		primitives: {
+			meta,
+			og,
+			jsonLd,
+			canonical,
+			hreflang,
+			twitter,
+			feedLink
+		},
+		buildArticleHead
+	};
+};
+
+//#endregion
+//#region src/plugins/head/state.ts
+const createHeadState = (config) => ({
+	config,
+	ogImageDefaults: config.ogImage ?? null
+});
+
+//#endregion
+//#region src/plugins/head/validate.ts
+/**
+* Validate optional `ogImage` config — checks that each font entry has a
+* non-empty `subset` and a non-empty `weights` array.
+*
+* @param ogImage - The OG image config to validate.
+* @throws Error when any font entry is missing required fields.
+*/
+const assertValidOgImage = (ogImage) => {
+	if (!ogImage.fonts) return;
+	for (const font of ogImage.fonts) {
+		if (typeof font.subset !== "string" || font.subset.length === 0) throw new Error("head: ogImage.fonts entry requires a non-empty subset");
+		if (!Array.isArray(font.weights) || font.weights.length === 0) throw new Error("head: ogImage.fonts entry requires a non-empty weights array");
+	}
+};
+/**
+* Recursively `Object.freeze` an object and all nested object/array values.
+* Mirrors the i18n plugin pattern — plain `Object.freeze` is shallow and would
+* leave nested config records like `ogImage.fonts` mutable.
+*
+* @param value - The value to freeze (no-op for primitives or already-frozen values).
+*/
+const deepFreeze = (value) => {
+	if (value === null || typeof value !== "object") return;
+	if (Object.isFrozen(value)) return;
+	Object.freeze(value);
+	for (const key of Object.keys(value)) deepFreeze(value[key]);
+};
+/**
+* Validate head config and replace state.config with a deeply frozen copy.
+*
+* Runs in the head plugin's `onInit`. Failures surface at `createApp()` time.
+* `state.ogImageDefaults` is updated to reference the frozen ogImage (or null).
+*
+* @param ctx - The head plugin context ({ state, config }).
+* @throws Error when `ogImage.fonts` entries are missing required fields.
+*/
+const validateAndFreeze = (ctx) => {
+	if (ctx.config.ogImage) assertValidOgImage(ctx.config.ogImage);
+	const frozen = { ...ctx.config };
+	if (frozen.ogImage) {
+		frozen.ogImage = { ...frozen.ogImage };
+		if (frozen.ogImage.fonts) frozen.ogImage.fonts = frozen.ogImage.fonts.map((font) => ({
+			...font,
+			weights: [...font.weights]
+		}));
+	}
+	deepFreeze(frozen);
+	ctx.state.config = frozen;
+	ctx.state.ogImageDefaults = frozen.ogImage ?? null;
+};
+
+//#endregion
+//#region src/plugins/head/index.ts
+/** @file head plugin: SEO primitives + render. Standard tier. jsonLd unicode-escape XSS fix non-negotiable. */
+const defaultConfig = {
+	titleSeparator: " — ",
+	autoCanonical: true
+};
+const head = createPlugin("head", {
+	depends: [
+		site,
+		i18n,
+		router
+	],
+	config: defaultConfig,
+	createState: (ctx) => createHeadState(ctx.config),
+	api: createHeadApi,
+	onInit: validateAndFreeze
+});
+
+//#endregion
+//#region src/plugins/spa/components/api.ts
+const createComponentsSubApi = (ctx) => ({ register: (def) => {
+	ctx.state.components.registered.push(def);
+} });
+
+//#endregion
+//#region src/plugins/spa/head/sync.ts
+/** @file Head metadata sync on SPA navigation — title, meta name/property, link[rel=canonical]. */
+/**
+* Replace `<title>` text in the current document with the one from `doc.head`.
+*
+* @param doc - The source document whose head supplies the new title.
+*/
+const syncTitle = (doc) => {
+	const incoming = doc.head.querySelector("title")?.textContent;
+	if (incoming !== null && incoming !== void 0) document.title = incoming;
+};
+/**
+* Resolve the selector for a single incoming meta element, or `null` if it has
+* neither `name` nor `property` attribute (and is therefore unidentifiable).
+*
+* @param incoming - The meta element from the source document.
+* @returns A CSS selector string or `null`.
+*/
+const metaSelector = (incoming) => {
+	const name = incoming.getAttribute("name");
+	if (name !== null) return `meta[name="${name}"]`;
+	const property = incoming.getAttribute("property");
+	if (property !== null) return `meta[property="${property}"]`;
+	return null;
+};
+/**
+* Mirror every `<meta>` tag from src head into the current head, replacing
+* existing tags that match on either `name` or `property` attribute.
+*
+* @param doc - The source document.
+*/
+const syncMetaTags = (doc) => {
+	for (const incoming of doc.head.querySelectorAll("meta")) {
+		const selector = metaSelector(incoming);
+		if (selector === null) continue;
+		const existing = document.head.querySelector(selector);
+		const clone = incoming.cloneNode(true);
+		if (existing) existing.replaceWith(clone);
+		else document.head.append(clone);
+	}
+};
+/**
+* Replace `<link rel="canonical">` in the current head if the src doc has one.
+*
+* @param doc - The source document.
+*/
+const syncCanonical = (doc) => {
+	const incoming = doc.head.querySelector("link[rel=\"canonical\"]");
+	if (!incoming) return;
+	const existing = document.head.querySelector("link[rel=\"canonical\"]");
+	const clone = incoming.cloneNode(true);
+	if (existing) existing.replaceWith(clone);
+	else document.head.append(clone);
+};
+/**
+* Sync the SEO-relevant subset of a foreign document's head into the current
+* document — title, meta[name|property], link[rel="canonical"]. Idempotent:
+* running twice with the same source produces the same DOM.
+*
+* @param doc - The source document (typically fetched + parsed for SPA nav).
+*/
+const syncHead = (doc) => {
+	syncTitle(doc);
+	syncMetaTags(doc);
+	syncCanonical(doc);
+};
+
+//#endregion
+//#region src/plugins/spa/head/api.ts
+/**
+* Build the head sub-API.
+*
+* `update(doc)` records the incoming document on state and (when running in a
+* browser) mirrors the SEO-relevant subset of its `<head>` into the live
+* document via {@link syncHead}.
+*
+* @param ctx - SPA context with shared state.
+* @returns The head sub-API.
+*/
+const createHeadSubApi = (ctx) => ({ update: (doc) => {
+	ctx.state.head.currentDoc = doc;
+	if (typeof window !== "undefined") syncHead(doc);
+} });
+
+//#endregion
+//#region src/plugins/spa/progress/api.ts
+/**
+* Build the progress sub-API.
+*
+* `start()` and `done()` toggle `state.progress.active`; visual rendering is
+* delegated to a separate progress bar instance installed by `spa.onStart`
+* (which subscribes to the same state transitions). This keeps `api.ts` pure
+* for testing — no DOM coupling.
+*
+* @param ctx - SPA context with shared state.
+* @returns The progress sub-API.
+*/
+const createProgressSubApi = (ctx) => ({
+	start: () => {
+		ctx.state.progress.active = true;
+	},
+	done: () => {
+		ctx.state.progress.active = false;
+	}
+});
+
+//#endregion
+//#region src/plugins/spa/router/api.ts
+/**
+* Build the router sub-API.
+*
+* `current()` exposes the canonical URL stored on state; `navigate(url)` updates
+* that URL, appends to history, and emits `nav:start` (with `fromUrl`) before
+* the transition and `nav:end` after. `destroy()` is a synchronous teardown
+* hook that clears the in-memory history buffer.
+*
+* @param ctx - SPA context with shared state.
+* @returns The router sub-API.
+*/
+const createRouterSubApi = (ctx) => ({
+	current: () => ctx.state.router.currentUrl,
+	navigate: async (url) => {
+		const fromUrl = ctx.state.router.currentUrl;
+		ctx.state.eventBus.emit("nav:start", {
+			url,
+			fromUrl
+		});
+		ctx.state.router.currentUrl = url;
+		ctx.state.router.history.push(url);
+		ctx.state.eventBus.emit("nav:end", { url });
+	},
+	destroy: () => {
+		ctx.state.router.history.length = 0;
+	}
+});
+
+//#endregion
+//#region src/plugins/spa/api.ts
+/** @file spa plugin composed API factory — namespaced sub-modules sharing state. */
+const createSpaApi = (ctx) => ({
+	router: createRouterSubApi(ctx),
+	head: createHeadSubApi(ctx),
+	progress: createProgressSubApi(ctx),
+	components: createComponentsSubApi(ctx)
+});
+
+//#endregion
+//#region src/plugins/spa/components/lifecycle.ts
+/**
+* Mount a single component instance against an element.
+*
+* Calls `onCreate(element)` then `onMount(mountCtx)` in order; both hooks are
+* awaited so async setup completes before this function resolves. Emits
+* `component:create` and `component:mount` on the supplied event bus.
+*
+* @param def - The component definition produced by `createComponent`.
+* @param element - The DOM element this instance is bound to.
+* @param mountCtx - The mount context (container, optional pageData, url).
+* @param eventBus - The SPA event bus used for `component:*` notifications.
+* @returns The created `ComponentInstance` ({ def, element }).
+*/
+const mountComponent = async (def, element, mountCtx, eventBus) => {
+	if (def.hooks.onCreate) await def.hooks.onCreate(element);
+	eventBus.emit("component:create", {
+		name: def.name,
+		element
+	});
+	if (def.hooks.onMount) await def.hooks.onMount(mountCtx);
+	eventBus.emit("component:mount", {
+		name: def.name,
+		element
+	});
+	return {
+		def,
+		element
+	};
+};
+/**
+* Unmount a component instance.
+*
+* Calls `onUnMount(unmountCtx)` then `onDestroy(element)` in order; both hooks
+* are awaited. Emits `component:unmount` and `component:destroy` on the bus.
+*
+* @param instance - The instance returned by `mountComponent`.
+* @param unmountCtx - The unmount context (reason, element).
+* @param eventBus - The SPA event bus.
+*/
+const unmountComponent = async (instance, unmountCtx, eventBus) => {
+	if (instance.def.hooks.onUnMount) await instance.def.hooks.onUnMount(unmountCtx);
+	eventBus.emit("component:unmount", {
+		name: instance.def.name,
+		reason: unmountCtx.reason
+	});
+	if (instance.def.hooks.onDestroy) await instance.def.hooks.onDestroy(instance.element);
+	eventBus.emit("component:destroy", { name: instance.def.name });
+};
+
+//#endregion
+//#region src/plugins/spa/client-init.ts
+/** @file Client boot helpers — discover [data-component] islands and mount registered defs against them. */
+/**
+* Walk `document.querySelectorAll('[data-component]')` and mount any element
+* whose `data-component` attribute matches a registered `ComponentDef`.
+*
+* Idempotent — instances already present in `state.components.instances` are
+* skipped so repeat boots (e.g. HMR) do not double-mount.
+*
+* @param state - Shared SPA state (registered defs + instances map + eventBus).
+* @param url - The current URL to thread into each mount context.
+*/
+const initComponents = async (state, url) => {
+	const byName = /* @__PURE__ */ new Map();
+	for (const def of state.components.registered) byName.set(def.name, def);
+	const nodes = document.querySelectorAll("[data-component]");
+	for (const element of nodes) {
+		const name = element.getAttribute("data-component");
+		if (name === null) continue;
+		const def = byName.get(name);
+		if (def === void 0) continue;
+		if (state.components.instances.has(element)) continue;
+		const instance = await mountComponent(def, element, {
+			container: element,
+			url
+		}, state.eventBus);
+		state.components.instances.set(element, instance);
+	}
+};
+/**
+* Unmount every tracked component instance and clear the registry map.
+*
+* @param state - Shared SPA state.
+*/
+const teardownComponents = async (state) => {
+	for (const [element, instance] of state.components.instances) await unmountComponent(instance, {
+		reason: "destroy",
+		element
+	}, state.eventBus);
+	state.components.instances.clear();
+};
+
+//#endregion
+//#region src/plugins/spa/progress/nprogress.ts
+/** @file NProgress-style progress bar. Delays visible mount by 150ms to avoid flicker on fast navigations. */
+const SHOW_DELAY_MS = 150;
+const PROGRESS_ATTR = "data-moku-progress";
+/**
+* Mount the progress bar element into `document.body`.
+*
+* @returns The created DOM element.
+*/
+const mountBar = () => {
+	const bar = document.createElement("div");
+	bar.setAttribute(PROGRESS_ATTR, "");
+	bar.style.cssText = "position:fixed;top:0;left:0;right:0;height:2px;background:#3b82f6;z-index:9999;pointer-events:none;";
+	document.body.append(bar);
+	return bar;
+};
+/**
+* Unmount any existing progress bar from the DOM.
+*/
+const unmountBar = () => {
+	for (const node of document.querySelectorAll(`[${PROGRESS_ATTR}]`)) node.remove();
+};
+/**
+* Create a progress bar controller with `start()` / `done()` lifecycle.
+*
+* `start()` arms a 150ms timer; the bar is only inserted into the DOM if the
+* timer elapses without an intervening `done()` (avoids flicker on instant
+* navigations). `done()` cancels the pending show OR removes the visible bar.
+*
+* @returns Object with `start()` and `done()` methods.
+*/
+const createProgressBar = () => {
+	let timer = null;
+	return {
+		start: () => {
+			if (timer !== null) clearTimeout(timer);
+			timer = setTimeout(() => {
+				mountBar();
+				timer = null;
+			}, SHOW_DELAY_MS);
+		},
+		done: () => {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			unmountBar();
+		}
+	};
+};
+
+//#endregion
+//#region src/plugins/spa/router/navigation.ts
+/**
+* `true` if the click event carries any modifier (Ctrl/Meta/Shift/Alt) or is
+* not a primary-button click — both cases should pass through to the browser.
+*
+* @param event - The click event.
+*/
+const isModifiedClick = (event) => event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey;
+/**
+* Locate the nearest `<a>` element in the click event's composed path, if any.
+*
+* @param event - The click event.
+* @returns The anchor element or `undefined`.
+*/
+const findAnchor = (event) => {
+	return (event.composedPath ? event.composedPath() : [event.target]).find((node) => node instanceof HTMLAnchorElement || node?.tagName === "A");
+};
+/**
+* `true` if the anchor opts out of SPA navigation (foreign target, download,
+* empty/missing href, or external origin).
+*
+* @param anchor - The candidate anchor.
+* @returns Boolean opt-out.
+*/
+const shouldBypass = (anchor) => {
+	if (anchor.target !== "" && anchor.target !== "_self") return true;
+	if (anchor.hasAttribute("download")) return true;
+	const href = anchor.getAttribute("href");
+	return href === null || href === "";
+};
+/**
+* Decide whether a click event on (or inside) an anchor should be hijacked for
+* SPA navigation.
+*
+* @param event - The click MouseEvent.
+* @returns The href to navigate to, or `null` if the click should pass through.
+*/
+const resolveNavTarget = (event) => {
+	if (isModifiedClick(event)) return null;
+	const anchor = findAnchor(event);
+	if (!anchor || shouldBypass(anchor)) return null;
+	try {
+		const url = new URL(anchor.href, window.location.href);
+		if (url.origin !== window.location.origin) return null;
+		return url.href;
+	} catch {
+		return null;
+	}
+};
+/**
+* Install navigation listeners: popstate (back/forward) + delegated click on
+* anchors. The supplied `onNavigate` callback is invoked with the new URL when
+* a navigation should occur; the handler also calls `event.preventDefault()`
+* to suppress the browser's full-page load.
+*
+* Uses the Navigation API when available (`'navigation' in window`); otherwise
+* relies on the History API + popstate fallback used by happy-dom.
+*
+* @param onNavigate - Callback invoked with the destination URL.
+* @returns Handler with `destroy()` to remove all installed listeners.
+*/
+const createNavigationHandler = (onNavigate) => {
+	const onPopState = () => {
+		onNavigate(window.location.href);
+	};
+	const onClick = (event) => {
+		const href = resolveNavTarget(event);
+		if (href === null) return;
+		event.preventDefault();
+		onNavigate(href);
+	};
+	globalThis.addEventListener("popstate", onPopState);
+	document.addEventListener("click", onClick);
+	return { destroy: () => {
+		globalThis.removeEventListener("popstate", onPopState);
+		document.removeEventListener("click", onClick);
+	} };
+};
+
+//#endregion
+//#region src/plugins/spa/boot.ts
+/** @file SPA client runtime — extracted from index.ts to keep wiring ≤30 lines. */
+/** Per-state handle registry — keyed by SpaState for HMR-safe teardown. */
+const handlesByState = /* @__PURE__ */ new WeakMap();
+/**
+* Boot the SPA client: mount registered components against discovered islands,
+* install the progress bar (when enabled), and wire the navigation handler.
+*
+* @param ctx - Plugin context with shared state and config.
+*/
+const bootClient = async (ctx) => {
+	ctx.state.router.currentUrl = window.location.href;
+	await initComponents(ctx.state, ctx.state.router.currentUrl);
+	const progressBar = ctx.config.config.progressBar === true ? createProgressBar() : null;
+	const navHandler = createNavigationHandler(async (url) => {
+		progressBar?.start();
+		ctx.state.eventBus.emit("nav:start", {
+			url,
+			fromUrl: ctx.state.router.currentUrl
+		});
+		ctx.state.router.currentUrl = url;
+		ctx.state.router.history.push(url);
+		ctx.state.eventBus.emit("nav:end", { url });
+		progressBar?.done();
+	});
+	handlesByState.set(ctx.state, {
+		navHandler,
+		progressBar
+	});
+};
+/**
+* Tear down a previously-booted SPA client: destroy listeners and progress bar,
+* unmount instances, clear the handle registry.
+*
+* @param state - The SPA state whose client resources should be released.
+*/
+const teardownClient = async (state) => {
+	const handles = handlesByState.get(state);
+	handles?.navHandler?.destroy();
+	handles?.progressBar?.done();
+	handlesByState.delete(state);
+	await teardownComponents(state);
+	state.components.instances.clear();
+};
+/**
+* Build the client runtime for a single SPA plugin context.
+*
+* `start()` registers consumer components and runs the boot sequence; `stop()`
+* tears it down. Bound to the supplied context so a single call site can drive
+* the full lifecycle without re-passing state/config.
+*
+* @param ctx - Plugin context with state and config.
+* @returns A `ClientRuntime` with `start` and `stop` methods.
+*/
+const createClientRuntime = (ctx) => ({
+	start: async () => {
+		ctx.state.components.instances.clear();
+		for (const def of ctx.config.components) ctx.state.components.registered.push(def);
+		await bootClient(ctx);
+	},
+	stop: async () => {
+		ctx.state.components.instances.clear();
+		await teardownClient(ctx.state);
+	}
+});
+
+//#endregion
+//#region src/plugins/spa/events.ts
+/**
+* Register the SPA plugin's event map with the kernel's event registrar.
+*
+* @param register - The kernel-provided register function.
+* @returns The event map describing each event payload + human description.
+*/
+const registerSpaEvents = (register) => ({
+	"component:create": register("Component instance created"),
+	"component:mount": register("Component mounted"),
+	"component:unmount": register("Component unmounted"),
+	"component:destroy": register("Component destroyed"),
+	"nav:start": register("Navigation started"),
+	"nav:end": register("Navigation completed")
+});
+
+//#endregion
+//#region src/plugins/spa/components/state.ts
+const createComponentsState = () => ({
+	instances: /* @__PURE__ */ new Map(),
+	registered: []
+});
+
+//#endregion
+//#region src/plugins/spa/head/state.ts
+const createHeadSubState = () => ({ currentDoc: null });
+
+//#endregion
+//#region src/plugins/spa/progress/state.ts
+const createProgressState = () => ({
+	active: false,
+	visible: false
+});
+
+//#endregion
+//#region src/plugins/spa/router/state.ts
+const createRouterState = () => ({
+	currentUrl: "",
+	history: []
+});
+
+//#endregion
+//#region src/plugins/spa/state.ts
+/** @file spa plugin composed state factory — ALL fresh instances, no module-level singletons. Critical for Vitest worker isolation. */
+const createEventBus = () => {
+	const listeners = /* @__PURE__ */ new Map();
+	return {
+		on: (event, listener) => {
+			let set = listeners.get(event);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				listeners.set(event, set);
+			}
+			set.add(listener);
+			return () => {
+				listeners.get(event)?.delete(listener);
+			};
+		},
+		emit: (event, payload) => {
+			const set = listeners.get(event);
+			if (set) for (const listener of set) listener(payload);
+		}
+	};
+};
+const createSpaState = () => ({
+	router: createRouterState(),
+	head: createHeadSubState(),
+	progress: createProgressState(),
+	components: createComponentsState(),
+	eventBus: createEventBus()
+});
+
+//#endregion
+//#region src/plugins/spa/components/factory.ts
+const VALID_HOOKS = new Set([
+	"onCreate",
+	"onMount",
+	"onNavStart",
+	"onNavEnd",
+	"onUnMount",
+	"onDestroy"
+]);
+const createComponent = (name, hooks) => {
+	for (const key of Object.keys(hooks)) if (!VALID_HOOKS.has(key)) throw new Error(`[spa] Unknown component hook: "${key}" in component "${name}"`);
+	return {
+		name,
+		hooks
+	};
+};
+
+//#endregion
+export { createEnvState as _, createSpaApi as a, route as c, coreConfig as d, createCore as f, validateSchema as g, createLogApi as h, createClientRuntime as i, site as l, createLogState as m, createSpaState as n, head as o, createPlugin as p, registerSpaEvents as r, router as s, createComponent as t, i18n as u, createEnvApi as v };