@moku-labs/web 0.1.0-alpha.1

package/dist/factory-CixCpR9C.cjs

@@ -0,0 +1,1710 @@
+const require_project = require('./project-C1vtMxE8.cjs');
+const require_primitives = require('./primitives-BYUp6kae.cjs');
+const require_plugins_head_build = require('./plugins/head/build.cjs');
+let _moku_labs_core = require("@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 = (0, _moku_labs_core.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 = (0, _moku_labs_core.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 = (0, _moku_labs_core.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(require_primitives.canonical(renderCtx.url)));
+		return parts.join("\n");
+	};
+	return {
+		render,
+		primitives: {
+			meta: require_primitives.meta,
+			og: require_primitives.og,
+			jsonLd: require_primitives.jsonLd,
+			canonical: require_primitives.canonical,
+			hreflang: require_primitives.hreflang,
+			twitter: require_primitives.twitter,
+			feedLink: require_primitives.feedLink
+		},
+		buildArticleHead: require_plugins_head_build.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
+Object.defineProperty(exports, 'coreConfig', {
+  enumerable: true,
+  get: function () {
+    return coreConfig;
+  }
+});
+Object.defineProperty(exports, 'createClientRuntime', {
+  enumerable: true,
+  get: function () {
+    return createClientRuntime;
+  }
+});
+Object.defineProperty(exports, 'createComponent', {
+  enumerable: true,
+  get: function () {
+    return createComponent;
+  }
+});
+Object.defineProperty(exports, 'createCore', {
+  enumerable: true,
+  get: function () {
+    return createCore;
+  }
+});
+Object.defineProperty(exports, 'createEnvApi', {
+  enumerable: true,
+  get: function () {
+    return createEnvApi;
+  }
+});
+Object.defineProperty(exports, 'createEnvState', {
+  enumerable: true,
+  get: function () {
+    return createEnvState;
+  }
+});
+Object.defineProperty(exports, 'createLogApi', {
+  enumerable: true,
+  get: function () {
+    return createLogApi;
+  }
+});
+Object.defineProperty(exports, 'createLogState', {
+  enumerable: true,
+  get: function () {
+    return createLogState;
+  }
+});
+Object.defineProperty(exports, 'createPlugin', {
+  enumerable: true,
+  get: function () {
+    return createPlugin;
+  }
+});
+Object.defineProperty(exports, 'createSpaApi', {
+  enumerable: true,
+  get: function () {
+    return createSpaApi;
+  }
+});
+Object.defineProperty(exports, 'createSpaState', {
+  enumerable: true,
+  get: function () {
+    return createSpaState;
+  }
+});
+Object.defineProperty(exports, 'head', {
+  enumerable: true,
+  get: function () {
+    return head;
+  }
+});
+Object.defineProperty(exports, 'i18n', {
+  enumerable: true,
+  get: function () {
+    return i18n;
+  }
+});
+Object.defineProperty(exports, 'registerSpaEvents', {
+  enumerable: true,
+  get: function () {
+    return registerSpaEvents;
+  }
+});
+Object.defineProperty(exports, 'route', {
+  enumerable: true,
+  get: function () {
+    return route;
+  }
+});
+Object.defineProperty(exports, 'router', {
+  enumerable: true,
+  get: function () {
+    return router;
+  }
+});
+Object.defineProperty(exports, 'site', {
+  enumerable: true,
+  get: function () {
+    return site;
+  }
+});
+Object.defineProperty(exports, 'validateSchema', {
+  enumerable: true,
+  get: function () {
+    return validateSchema;
+  }
+});