@moku-labs/web 0.4.2 → 0.5.1

package/dist/index.cjs

@@ -37,7 +37,7 @@ let preact = require("preact");
 let preact_render_to_string = require("preact-render-to-string");
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
-const ERROR_PREFIX$13 = "[web]";
+const ERROR_PREFIX$14 = "[web]";
 /**
 * Creates the env plugin API surface mounted at `ctx.env`. Closes over
 * `ctx.state` ({@link EnvState}) and reads the frozen `resolved` / `publicMap`
@@ -81,7 +81,7 @@ function createEnvApi(ctx) {
 		*/
 		require(key) {
 			const value = resolved.get(key);
-			if (value === void 0) throw new Error(`${ERROR_PREFIX$13} env: required variable "${key}" is not defined.`);
+			if (value === void 0) throw new Error(`${ERROR_PREFIX$14} env: required variable "${key}" is not defined.`);
 			return value;
 		},
 		/**
@@ -148,7 +148,7 @@ function createEnvState() {
 /** Error message thrown by every frozen-map mutator. */
 const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
 /** Error prefix for all resolution-pipeline failures. */
-const ERROR_PREFIX$12 = "[web]";
+const ERROR_PREFIX$13 = "[web]";
 /**
 * Throws the canonical frozen-map error; installed as a map's `set`/`clear`/`delete`.
 *
@@ -199,8 +199,8 @@ function crossCheckPublicPrefix(config) {
 	const { schema, publicPrefix } = config;
 	for (const [key, spec] of Object.entries(schema)) {
 		const hasPrefix = key.startsWith(publicPrefix);
-		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$12} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
-		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$12} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
+		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$13} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
+		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$13} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
 	}
 }
 /**
@@ -251,7 +251,7 @@ function validateSchema(ctx) {
 	crossCheckPublicPrefix(config);
 	for (const [key, spec] of Object.entries(schema)) {
 		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
-		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$12} env: required variable "${key}" is not defined by any provider or default.`);
+		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$13} env: required variable "${key}" is not defined by any provider or default.`);
 	}
 	for (const [key, spec] of Object.entries(schema)) {
 		const value = merged[key];
@@ -743,6 +743,12 @@ const logPlugin = (0, _moku_labs_core.createCorePlugin)("log", {
 	api: createLogApi,
 	onInit: installDefaultSinks
 });
+//#endregion
+//#region src/config.ts
+/**
+* @file Framework configuration — Config + Events types, core plugin registration.
+* @see README.md
+*/
 const coreConfig = (0, _moku_labs_core.createCoreConfig)("web", {
 	config: { mode: "production" },
 	plugins: [logPlugin, envPlugin],
@@ -772,7 +778,7 @@ const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
-const ERROR_PREFIX$11 = "[web]";
+const ERROR_PREFIX$12 = "[web]";
 /**
 * Validates the resolved i18n config (fail-fast at `createApp`). Throws when
 * `locales` is empty or when `defaultLocale` is not a member of `locales`.
@@ -788,8 +794,8 @@ const ERROR_PREFIX$11 = "[web]";
 */
 function validateI18nConfig(ctx) {
 	const { locales, defaultLocale } = ctx.config;
-	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$11} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
-	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$11} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
+	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$12} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
+	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$12} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
 }
 /**
 * Creates the i18n plugin API surface — locale registry accessors plus the
@@ -1764,7 +1770,7 @@ const contentPlugin = createPlugin$1("content", {
 //#endregion
 //#region src/plugins/site/api.ts
 /** Error prefix for all site lifecycle/validation failures. */
-const ERROR_PREFIX$10 = "[web]";
+const ERROR_PREFIX$11 = "[web]";
 /**
 * Joins a relative path against an absolute base URL, normalizing the slash
 * boundary to exactly one "/". Returns the base unchanged for an empty or
@@ -1832,8 +1838,8 @@ function isAbsoluteUrl(value) {
 * ```
 */
 function validateSiteConfig(ctx) {
-	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$10} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
-	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$10} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
+	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$11} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
+	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$11} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
 }
 /**
 * Creates the site plugin API surface — read-only accessors over frozen config
@@ -2023,7 +2029,7 @@ function matchRoute(compiled, pathname) {
 * `manifest`. Returns values/copies, never the raw `ctx.state` reference (spec/11 §2.4).
 */
 /** Error prefix for router API failures. */
-const ERROR_PREFIX$9 = "[web] router";
+const ERROR_PREFIX$10 = "[web] router";
 /**
 * Read the compiled matcher table, throwing if `onInit` has not run yet. This
 * `null` cannot occur in practice post-`onInit`; the guard documents the invariant.
@@ -2037,7 +2043,7 @@ const ERROR_PREFIX$9 = "[web] router";
 * ```
 */
 function readTable(state) {
-	if (state.table === null) throw new Error(`${ERROR_PREFIX$9}: matcher table accessed before onInit compiled it.`);
+	if (state.table === null) throw new Error(`${ERROR_PREFIX$10}: matcher table accessed before onInit compiled it.`);
 	return state.table;
 }
 /**
@@ -2121,7 +2127,7 @@ function createApi$4(ctx) {
 		*/
 		toUrl(routeName, params) {
 			const entry = readTable(state).byName.get(routeName);
-			if (!entry) throw new Error(`${ERROR_PREFIX$9}: unknown route name "${routeName}".`);
+			if (!entry) throw new Error(`${ERROR_PREFIX$10}: unknown route name "${routeName}".`);
 			return entry.toUrl(params);
 		},
 		/**
@@ -2256,7 +2262,7 @@ function bySpecificity(a, b) {
 * only (`CompileInput`) — never the plugin ctx.
 */
 /** Shared `[web]` error prefix for router validation failures. */
-const ERROR_PREFIX$8 = "[web] router";
+const ERROR_PREFIX$9 = "[web] router";
 /**
 * Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
 * naming the offending route/pattern on any failure: empty map, a pattern not
@@ -2271,12 +2277,12 @@ const ERROR_PREFIX$8 = "[web] router";
 */
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
-	if (names.length === 0) throw new Error(`${ERROR_PREFIX$8}: route map is empty — provide at least one route via pluginConfigs.router.routes.`);
+	if (names.length === 0) throw new Error(`${ERROR_PREFIX$9}: route map is empty — provide at least one route via pluginConfigs.router.routes.`);
 	for (const name of names) {
 		const pattern = routes[name]?.pattern ?? "";
-		if (!pattern.startsWith("/")) throw new Error(`${ERROR_PREFIX$8}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-		if ((pattern.match(/\{/g) ?? []).length !== (pattern.match(/\}/g) ?? []).length) throw new Error(`${ERROR_PREFIX$8}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-		if ((pattern.match(/\{lang:\?\}/g) ?? []).length > 1) throw new Error(`${ERROR_PREFIX$8}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+		if (!pattern.startsWith("/")) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+		if ((pattern.match(/\{/g) ?? []).length !== (pattern.match(/\}/g) ?? []).length) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+		if ((pattern.match(/\{lang:\?\}/g) ?? []).length > 1) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
 	}
 }
 /**
@@ -3058,7 +3064,7 @@ function serializeHead(elements) {
 * it to a string. It holds no resource and caches no subscription.
 */
 /** Error prefix for head API invariant failures. */
-const ERROR_PREFIX$7 = "[head]";
+const ERROR_PREFIX$8 = "[head]";
 /**
 * Read the normalized defaults, asserting the post-`onInit` invariant (the slot is
 * `null` only before `onInit` assigns it, which cannot occur at render time).
@@ -3072,7 +3078,7 @@ const ERROR_PREFIX$7 = "[head]";
 * ```
 */
 function readDefaults(state) {
-	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$7}: defaults accessed before onInit normalized them.`);
+	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$8}: defaults accessed before onInit normalized them.`);
 	return state.defaults;
 }
 /**
@@ -3115,7 +3121,7 @@ render(route, data) {
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
-const ERROR_PREFIX$6 = "[head] config:";
+const ERROR_PREFIX$7 = "[head] config:";
 /** The allowed `twitterCard` literals (also the runtime guard set). */
 const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 /**
@@ -3142,8 +3148,8 @@ const defaultConfig$2 = { twitterCard: "summary_large_image" };
 * ```
 */
 function validateHeadConfig(config) {
-	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$6} titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
-	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$6} twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
+	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$7} titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
+	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$7} twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
 }
 /**
 * Validate then build the frozen, normalized {@link HeadDefaults} snapshot read by
@@ -3601,13 +3607,14 @@ async function expandRedirects(definition, entry, defaultLocale) {
 	const parameterSets = definition._handlers.generate ? await definition._handlers.generate(defaultLocale) : [{}];
 	const jobs = [];
 	for (const raw of parameterSets) {
-		const params = raw ?? {};
-		const file = entry.toFile(params);
+		const bareParams = { ...raw ?? {} };
+		delete bareParams.lang;
+		const file = entry.toFile(bareParams);
 		const target = entry.toUrl({
-			...params,
+			...bareParams,
 			lang: defaultLocale
 		});
-		if (target !== entry.toUrl(params)) jobs.push({
+		if (target !== entry.toUrl(bareParams)) jobs.push({
 			file,
 			target
 		});
@@ -3950,7 +3957,7 @@ async function generateOgImages(ctx, options = {}) {
 		try {
 			const png = await renderPng(input);
 			await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
-			await (0, node_fs_promises.writeFile)(node_path.default.join(outDir, `${key}.png`), png);
+			await (0, node_fs_promises.writeFile)(node_path.default.join(outDir, `${article.computed.slug}.png`), png);
 			cache.set(key, hash);
 			rendered += 1;
 		} finally {
@@ -4788,7 +4795,7 @@ async function runPipeline(ctx, options) {
 * @file build plugin — API factory (run + phases), cross-plugin wiring, and onInit config validation.
 */
 /** Error prefix for build config/validation failures (spec/11 Part-3). */
-const ERROR_PREFIX$5 = "[web] build";
+const ERROR_PREFIX$6 = "[web] build";
 /** Recognized font file extensions for OG-image validation. */
 const FONT_EXTENSIONS = [
 	".ttf",
@@ -4859,8 +4866,8 @@ function createApi$2(ctx) {
 * ```
 */
 function validateFonts(og) {
-	if (typeof og.fontDir !== "string" || og.fontDir.length === 0 || !(0, node_fs.existsSync)(og.fontDir)) throw new Error(`${ERROR_PREFIX$5}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
-	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$5}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
+	if (typeof og.fontDir !== "string" || og.fontDir.length === 0 || !(0, node_fs.existsSync)(og.fontDir)) throw new Error(`${ERROR_PREFIX$6}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
+	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$6}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
@@ -4874,10 +4881,10 @@ function validateFonts(og) {
 * ```
 */
 function validateConfig$1(config) {
-	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$5}.outDir: must be a non-empty string.`);
-	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$5}.publicDir: must be a string when set.`);
-	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$5}.template: must be a string path when set.`);
-	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$5}.clientEntry: must be a string path when set.`);
+	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$6}.outDir: must be a non-empty string.`);
+	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$6}.publicDir: must be a string when set.`);
+	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$6}.template: must be a string path when set.`);
+	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$6}.clientEntry: must be a string path when set.`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion
@@ -4979,7 +4986,7 @@ const buildPlugin = createPlugin$1("build", {
 */
 const MOKU_WRANGLER_VERSION = "4.34.0";
 /** Error prefix for deploy runtime failures (spec/11 Part-3). */
-const ERROR_PREFIX$4 = "[web] deploy";
+const ERROR_PREFIX$5 = "[web] deploy";
 /** Mask substituted for a detected secret-like token. */
 const MASK = "***";
 /** Minimum token length eligible for entropy-gated scrubbing. */
@@ -5057,7 +5064,7 @@ function scrubSecrets(text, allowlist) {
 * guardBranch("preview/landing"); // "preview/landing"
 */
 function guardBranch(branch) {
-	if (!BRANCH_REGEX.test(branch) || branch.startsWith("-")) throw deployError("ERR_DEPLOY_INVALID_BRANCH", `${ERROR_PREFIX$4}: branch ${JSON.stringify(branch)} is invalid.\n  Branches must match /^[a-zA-Z0-9/_.-]+$/ so they cannot inject wrangler flags.`);
+	if (!BRANCH_REGEX.test(branch) || branch.startsWith("-")) throw deployError("ERR_DEPLOY_INVALID_BRANCH", `${ERROR_PREFIX$5}: branch ${JSON.stringify(branch)} is invalid.\n  Branches must match /^[a-zA-Z0-9/_.-]+$/ so they cannot inject wrangler flags.`);
 	return branch;
 }
 /**
@@ -5074,7 +5081,7 @@ function guardBranch(branch) {
 function assertWithinRoot(outDir, root) {
 	const resolved = node_path$1.default.isAbsolute(outDir) ? node_path$1.default.resolve(outDir) : node_path$1.default.resolve(root, outDir);
 	const rootResolved = node_path$1.default.resolve(root);
-	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path$1.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
+	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path$1.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$5}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
 	return resolved;
 }
 /**
@@ -5159,11 +5166,11 @@ function classifyWranglerError(exitCode, scrubbedStderr) {
 	const haystack = scrubbedStderr.toLowerCase();
 	for (const signature of ERROR_SIGNATURES) if (signature.match.some((needle) => haystack.includes(needle))) return {
 		code: signature.kind,
-		message: `${ERROR_PREFIX$4}: wrangler failed (exit ${exitCode}).\n  ${signature.advice}`
+		message: `${ERROR_PREFIX$5}: wrangler failed (exit ${exitCode}).\n  ${signature.advice}`
 	};
 	return {
 		code: "ERR_DEPLOY_WRANGLER_FAILED",
-		message: `${ERROR_PREFIX$4}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-500)}`
+		message: `${ERROR_PREFIX$5}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-500)}`
 	};
 }
 /**
@@ -5429,7 +5436,7 @@ async function reconcile(input) {
 * and short-circuiting on the first failure.
 */
 /** Error prefix for deploy preflight failures (spec/11 Part-3). */
-const ERROR_PREFIX$3 = "[web] deploy";
+const ERROR_PREFIX$4 = "[web] deploy";
 /** Cloudflare Pages free-tier file-count limit. */
 const FREE_TIER_FILE_LIMIT = 2e4;
 /** Cloudflare Pages paid-tier file-count limit (env override target). */
@@ -5505,15 +5512,15 @@ async function runPreflight(config, root, env = process.env) {
 	try {
 		await (0, node_fs_promises.stat)(wranglerPath);
 	} catch {
-		throw deployError("ERR_DEPLOY_NO_WRANGLER_CONFIG", `${ERROR_PREFIX$3}: wrangler.jsonc not found.\n  Run \`app.deploy.init()\` to scaffold it, then retry.`);
+		throw deployError("ERR_DEPLOY_NO_WRANGLER_CONFIG", `${ERROR_PREFIX$4}: wrangler.jsonc not found.\n  Run \`app.deploy.init()\` to scaffold it, then retry.`);
 	}
 	const stats = await inspectOutdir(node_path$1.default.isAbsolute(config.outDir) ? node_path$1.default.resolve(config.outDir) : node_path$1.default.resolve(root, config.outDir)).catch(() => {
-		throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$3}: outDir ${JSON.stringify(config.outDir)} is missing.\n  Run your build first, then retry.`);
+		throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(config.outDir)} is missing.\n  Run your build first, then retry.`);
 	});
-	if (stats.fileCount === 0) throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$3}: outDir ${JSON.stringify(config.outDir)} is empty — nothing to deploy.`);
+	if (stats.fileCount === 0) throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(config.outDir)} is empty — nothing to deploy.`);
 	const limit = resolveFileLimit(env);
-	if (stats.fileCount > limit) throw deployError("ERR_DEPLOY_TOO_MANY_FILES", `${ERROR_PREFIX$3}: outDir contains ${stats.fileCount} files; the limit is ${limit}.\n  Raise it with ${MAX_FILES_ENV} (paid tier) or reduce the output.`);
-	if (stats.oversizePath !== null) throw deployError("ERR_DEPLOY_FILE_TOO_LARGE", `${ERROR_PREFIX$3}: file ${JSON.stringify(stats.oversizePath)} exceeds the 25 MiB per-file limit.`);
+	if (stats.fileCount > limit) throw deployError("ERR_DEPLOY_TOO_MANY_FILES", `${ERROR_PREFIX$4}: outDir contains ${stats.fileCount} files; the limit is ${limit}.\n  Raise it with ${MAX_FILES_ENV} (paid tier) or reduce the output.`);
+	if (stats.oversizePath !== null) throw deployError("ERR_DEPLOY_FILE_TOO_LARGE", `${ERROR_PREFIX$4}: file ${JSON.stringify(stats.oversizePath)} exceeds the 25 MiB per-file limit.`);
 }
 //#endregion
 //#region src/plugins/deploy/slug.ts
@@ -5558,7 +5565,7 @@ function toSlug(name) {
 //#endregion
 //#region src/plugins/deploy/api.ts
 /** Error prefix for deploy config/validation failures (spec/11 Part-3). */
-const ERROR_PREFIX$2 = "[web] deploy";
+const ERROR_PREFIX$3 = "[web] deploy";
 /** `YYYY-MM-DD` validator for the compatibility date config field. */
 const COMPAT_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 /**
@@ -5573,10 +5580,10 @@ const COMPAT_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 */
 function validateConfig(ctx) {
 	const { config } = ctx;
-	if (config.target !== "cloudflare-pages") throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$2}: target ${JSON.stringify(config.target)} is unsupported.\n  Only "cloudflare-pages" is supported in this version.`);
-	if (typeof config.outDir !== "string" || config.outDir.length === 0) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$2}: outDir must be a non-empty string.\n  Set pluginConfigs.deploy.outDir to your build output directory (e.g. "dist").`);
-	if (!Array.isArray(config.scrubAllowlist) || !config.scrubAllowlist.every((item) => typeof item === "string")) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$2}: scrubAllowlist must be an array of strings.`);
-	if (config.compatibilityDate !== void 0 && !COMPAT_DATE_REGEX.test(config.compatibilityDate)) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$2}: compatibilityDate ${JSON.stringify(config.compatibilityDate)} must be in YYYY-MM-DD form.`);
+	if (config.target !== "cloudflare-pages") throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: target ${JSON.stringify(config.target)} is unsupported.\n  Only "cloudflare-pages" is supported in this version.`);
+	if (typeof config.outDir !== "string" || config.outDir.length === 0) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: outDir must be a non-empty string.\n  Set pluginConfigs.deploy.outDir to your build output directory (e.g. "dist").`);
+	if (!Array.isArray(config.scrubAllowlist) || !config.scrubAllowlist.every((item) => typeof item === "string")) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: scrubAllowlist must be an array of strings.`);
+	if (config.compatibilityDate !== void 0 && !COMPAT_DATE_REGEX.test(config.compatibilityDate)) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: compatibilityDate ${JSON.stringify(config.compatibilityDate)} must be in YYYY-MM-DD form.`);
 	ctx.require(sitePlugin);
 }
 /**
@@ -5855,7 +5862,38 @@ const COMPONENT_HOOK_NAMES = [
 	"onUnMount",
 	"onDestroy"
 ];
-new Set(COMPONENT_HOOK_NAMES);
+//#endregion
+//#region src/plugins/spa/components.ts
+/** Error prefix for spa fail-fast failures (spec/11 Part-3). */
+const ERROR_PREFIX$2 = "[web]";
+/** The set of legal hook names, frozen for O(1) membership checks. */
+const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
+/**
+* Create a validated component definition. Validates hook names at registration
+* for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+* each provided hook is a function.
+*
+* @param name - Unique component name.
+* @param hooks - Lifecycle hook implementations.
+* @returns A `ComponentDef` ready to `register`.
+* @throws {Error} If `name` is empty, any hook key is not in
+*   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+* @example
+* const counter = createComponent("counter", {
+*   onMount({ el }) { el.textContent = "0"; }
+* });
+*/
+function createComponent(name, hooks) {
+	if (name.trim() === "") throw new Error(`${ERROR_PREFIX$2} component name must be a non-empty string\n  → pass a unique name to createComponent("name", hooks)`);
+	for (const key of Object.keys(hooks)) {
+		if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${name}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
+		if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${name}" must be a function\n  → provide a function or omit the hook`);
+	}
+	return {
+		name,
+		hooks
+	};
+}
 /**
 * Extracts the page data payload from the inline `script#__DATA__` element.
 * Returns an empty object when the script is absent, empty, or invalid JSON.
@@ -7055,9 +7093,13 @@ function cloudflareBindings() {
 * `createApp({ plugins: [...] })` in a Node build; omit them in a browser app.
 * The framework never hard-blocks either runtime — the consumer composes the
 * variant it needs and supplies the matching `env` provider.
+*
+* This is the full surface (dual ESM+CJS). For a guaranteed node-free client
+* bundle, import the `@moku-labs/web/browser` entry instead of relying on
+* tree-shaking this one — see `src/browser.ts`.
 * @see README.md
 */
-const framework = createCore(coreConfig, {
+const core = createCore(coreConfig, {
 	plugins: [
 		sitePlugin,
 		i18nPlugin,
@@ -7096,7 +7138,7 @@ const framework = createCore(coreConfig, {
 * await app.build.run();
 * ```
 */
-const createApp = framework.createApp;
+const createApp = core.createApp;
 /**
 * Create a custom plugin bound to this framework's `Config`/`Events` and core
 * APIs. Plugin types are inferred from the spec object — never written explicitly.
@@ -7112,7 +7154,7 @@ const createApp = framework.createApp;
 * const app = createApp({ plugins: [analytics] });
 * ```
 */
-const createPlugin = framework.createPlugin;
+const createPlugin = core.createPlugin;
 //#endregion
 Object.defineProperty(exports, "Build", {
 	enumerable: true,
@@ -7175,6 +7217,7 @@ exports.canonical = canonical;
 exports.cloudflareBindings = cloudflareBindings;
 exports.contentPlugin = contentPlugin;
 exports.createApp = createApp;
+exports.createComponent = createComponent;
 exports.createPlugin = createPlugin;
 exports.dataPlugin = dataPlugin;
 exports.defineRoutes = defineRoutes;

package/dist/index.d.cts

@@ -2455,6 +2455,24 @@ declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", R
  */
 declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
+//#region src/plugins/spa/components.d.ts
+/**
+ * Create a validated component definition. Validates hook names at registration
+ * for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+ * each provided hook is a function.
+ *
+ * @param name - Unique component name.
+ * @param hooks - Lifecycle hook implementations.
+ * @returns A `ComponentDef` ready to `register`.
+ * @throws {Error} If `name` is empty, any hook key is not in
+ *   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+ * @example
+ * const counter = createComponent("counter", {
+ *   onMount({ el }) { el.textContent = "0"; }
+ * });
+ */
+declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -2640,4 +2658,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.d.mts

@@ -2455,6 +2455,24 @@ declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", R
  */
 declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
+//#region src/plugins/spa/components.d.ts
+/**
+ * Create a validated component definition. Validates hook names at registration
+ * for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+ * each provided hook is a function.
+ *
+ * @param name - Unique component name.
+ * @param hooks - Lifecycle hook implementations.
+ * @returns A `ComponentDef` ready to `register`.
+ * @throws {Error} If `name` is empty, any hook key is not in
+ *   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+ * @example
+ * const counter = createComponent("counter", {
+ *   onMount({ el }) { el.textContent = "0"; }
+ * });
+ */
+declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -2640,4 +2658,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };