@moku-labs/web 1.0.0 → 1.0.1

package/dist/index.cjs

@@ -411,6 +411,40 @@ function isPlainObject$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
+* Tests whether `actual` is an array that recursively matches every element of
+* the `partial` array (element-wise, with equal length).
+*
+* @param actual - The value to test against (must be an array of equal length).
+* @param partial - The expected partial array shape.
+* @returns `true` when `actual` is an equal-length array matching `partial` element-wise.
+* @example
+* ```ts
+* matchesPartialArray([1, 2], [1, 2]); // true
+* matchesPartialArray([1], [1, 2]); // false (length mismatch)
+* ```
+*/
+function matchesPartialArray(actual, partial) {
+	if (!Array.isArray(actual) || actual.length !== partial.length) return false;
+	return partial.every((value, index) => matchesPartial(actual[index], value));
+}
+/**
+* Tests whether `actual` is a plain object in which every `partial` key
+* recursively matches (extra `actual` keys are ignored).
+*
+* @param actual - The value to test against (must be a plain object).
+* @param partial - The expected partial object shape.
+* @returns `true` when every `partial` key exists in `actual` and matches recursively.
+* @example
+* ```ts
+* matchesPartialObject({ a: 1, b: 2 }, { a: 1 }); // true
+* matchesPartialObject({ a: 1 }, { b: 1 }); // false (missing key)
+* ```
+*/
+function matchesPartialObject(actual, partial) {
+	if (!isPlainObject$1(actual)) return false;
+	return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
+}
+/**
 * Subset-equality matcher: is `partial` a recursive subset of `actual`?
 *
 * Fast path via `Object.is` (covers identical primitives/references and
@@ -429,14 +463,8 @@ function isPlainObject$1(value) {
 */
 function matchesPartial(actual, partial) {
 	if (Object.is(actual, partial)) return true;
-	if (Array.isArray(partial)) {
-		if (!Array.isArray(actual) || actual.length !== partial.length) return false;
-		return partial.every((value, index) => matchesPartial(actual[index], value));
-	}
-	if (isPlainObject$1(partial)) {
-		if (!isPlainObject$1(actual)) return false;
-		return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
-	}
+	if (Array.isArray(partial)) return matchesPartialArray(actual, partial);
+	if (isPlainObject$1(partial)) return matchesPartialObject(actual, partial);
 	return false;
 }
 /**
@@ -1950,6 +1978,25 @@ function hasValidLangCount(pattern) {
 	return (pattern.match(/\{lang:\?\}/g) ?? []).length <= MAX_LANG_SEGMENTS;
 }
 /**
+* Assert a single route's pattern is well-formed, throwing the `[web]`-prefixed
+* error for the first failure: not rooted at `/`, unbalanced `{…}` braces, or
+* more than one `{lang:?}` segment. Extracted from {@link validateRoutes} so the
+* loop body stays flat.
+*
+* @param name - The route name key, surfaced in any error message.
+* @param pattern - The route's user pattern to validate.
+* @throws {Error} When the pattern is malformed.
+* @example
+* ```ts
+* assertRouteValid("home", "/{slug}/");
+* ```
+*/
+function assertRouteValid(name, pattern) {
+	if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+	if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+	if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+}
+/**
 * Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
 * naming the offending route/pattern on any failure: empty map, a pattern not
 * starting with `/`, unbalanced `{…}` braces, or more than one `{lang:?}` segment.
@@ -1964,12 +2011,7 @@ function hasValidLangCount(pattern) {
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
 	if (names.length === 0) throw new Error(`${ERROR_PREFIX$11}: route map is empty.\n  Register at least one route via pluginConfigs.router.routes.`);
-	for (const name of names) {
-		const pattern = routes[name]?.pattern ?? "";
-		if (!isPatternRooted(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-		if (!hasBalancedBraces(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-		if (!hasValidLangCount(pattern)) throw new Error(`${ERROR_PREFIX$11}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
-	}
+	for (const name of names) assertRouteValid(name, routes[name]?.pattern ?? "");
 }
 /**
 * Convert a user pattern to a `URLPattern` source string, in a `withLang` or
@@ -3551,6 +3593,26 @@ async function generateFeeds(ctx) {
 /** Conventional source directories scanned for static images to copy. */
 const IMAGE_SOURCE_DIRECTORIES = ["public", "static"];
 /**
+* Copy one source directory into the assets target, skipping it when the
+* directory is absent or empty. The target is created lazily so an all-empty
+* build never touches `outDir`.
+*
+* @param directory - The candidate source directory to copy.
+* @param target - The assets directory inside `outDir` to copy into.
+* @returns `true` when the directory was copied, `false` when skipped.
+* @example
+* ```ts
+* const didCopy = await copyImageDirectory("public", "dist/assets");
+* ```
+*/
+async function copyImageDirectory(directory, target) {
+	if (!(0, node_fs.existsSync)(directory)) return false;
+	if ((await (0, node_fs_promises.readdir)(directory)).length === 0) return false;
+	await (0, node_fs_promises.mkdir)(target, { recursive: true });
+	await (0, node_fs_promises.cp)(directory, target, { recursive: true });
+	return true;
+}
+/**
 * Copies static image directories into the output directory. No-op when
 * `config.images` is false or no source directory exists. Image bytes are copied
 * verbatim (optimization is a no-op hook point) — build only sequences I/O.
@@ -3571,13 +3633,7 @@ async function processImages(ctx, options = {}) {
 	const sourceDirectories = options.sourceDirectories ?? IMAGE_SOURCE_DIRECTORIES;
 	const target = node_path$1.default.join(ctx.config.outDir, "assets");
 	let copied = 0;
-	for (const directory of sourceDirectories) {
-		if (!(0, node_fs.existsSync)(directory)) continue;
-		if ((await (0, node_fs_promises.readdir)(directory)).length === 0) continue;
-		await (0, node_fs_promises.mkdir)(target, { recursive: true });
-		await (0, node_fs_promises.cp)(directory, target, { recursive: true });
-		copied += 1;
-	}
+	for (const directory of sourceDirectories) if (await copyImageDirectory(directory, target)) copied += 1;
 	ctx.log.debug("build:images", { copied });
 	return copied;
 }
@@ -3625,6 +3681,37 @@ function pairRoutes(router) {
 	return pairs;
 }
 /**
+* Compute the single bare→default redirect job for one generated parameter set, or
+* `null` when no redirect is needed. The BARE (locale-less) path is derived by
+* stripping `lang`. `generate()` supplies `lang` (pages need it), so using `params`
+* as-is makes the "bare" URL already carry the locale → target === bareUrl → NO
+* redirect is ever emitted. Removing `lang` yields the real lang-less file/URL
+* (`/`, `/about/`, `/{slug}/`) that must redirect to the default-locale URL.
+*
+* @param entry - The compiled `TypedRoute` (owns `toFile`/`toUrl`).
+* @param raw - One raw parameter set from `generate()` (may be `null`/`undefined`).
+* @param defaultLocale - The default locale to redirect bare paths to.
+* @returns The `{ file, target }` redirect job, or `null` when no redirect is needed.
+* @example
+* ```ts
+* redirectJobFor(entry, { lang: "en", slug: "hello" }, "en");
+* ```
+*/
+function redirectJobFor(entry, raw, defaultLocale) {
+	const bareParams = { ...raw ?? {} };
+	delete bareParams.lang;
+	const file = entry.toFile(bareParams);
+	const target = entry.toUrl({
+		...bareParams,
+		lang: defaultLocale
+	});
+	if (!(target !== entry.toUrl(bareParams))) return null;
+	return {
+		file,
+		target
+	};
+}
+/**
 * Expand one route into bare→default redirect jobs for the default locale. Uses
 * `generate?.(defaultLocale)` (or a single empty-params instance) and emits a job
 * only when the bare file path differs from the default-locale URL (i.e. the route
@@ -3649,17 +3736,8 @@ async function expandRedirects(definition, entry, defaultLocale, ctx) {
 	const parameterSets = definition._handlers.generate ? await definition._handlers.generate(generateContext) : [{}];
 	const jobs = [];
 	for (const raw of parameterSets) {
-		const bareParams = { ...raw ?? {} };
-		delete bareParams.lang;
-		const file = entry.toFile(bareParams);
-		const target = entry.toUrl({
-			...bareParams,
-			lang: defaultLocale
-		});
-		if (target !== entry.toUrl(bareParams)) jobs.push({
-			file,
-			target
-		});
+		const job = redirectJobFor(entry, raw, defaultLocale);
+		if (job) jobs.push(job);
 	}
 	return jobs;
 }
@@ -3820,6 +3898,54 @@ function ogHash(input, template, fontsHash) {
 	].join("|");
 	return (0, node_crypto.createHash)("sha256").update(payload).digest("hex");
 }
+/** Weight applied to fonts with no explicit `weight`. */
+const DEFAULT_FONT_WEIGHT = 400;
+/** Style applied to fonts with no explicit `style`. */
+const DEFAULT_FONT_STYLE = "normal";
+/** Family name given to the single fallback font scanned from `fontDir`. */
+const FALLBACK_FONT_NAME = "OG";
+/**
+* Load each explicitly-configured OG font, reading its `path` to a Buffer once and
+* filling in the default weight/style when omitted.
+*
+* @param fonts - The explicit named fonts to load.
+* @returns The loaded Satori font entries, in configuration order.
+* @example
+* ```ts
+* await loadExplicitFonts([{ name: "Inter", path: "./Inter.ttf" }]);
+* ```
+*/
+async function loadExplicitFonts(fonts) {
+	return Promise.all(fonts.map(async (font) => ({
+		name: font.name,
+		data: await (0, node_fs_promises.readFile)(font.path),
+		weight: font.weight ?? DEFAULT_FONT_WEIGHT,
+		style: font.style ?? DEFAULT_FONT_STYLE
+	})));
+}
+/**
+* Scan `fontDir` for the first recognized font file and load it as a single
+* 400/normal fallback; yields an empty list when the directory or a usable file
+* is missing.
+*
+* @param fontDir - Directory scanned for a fallback font file.
+* @returns The single fallback font, or an empty list when none is available.
+* @example
+* ```ts
+* await scanFallbackFont("./fonts");
+* ```
+*/
+async function scanFallbackFont(fontDir) {
+	if (!(0, node_fs.existsSync)(fontDir)) return [];
+	const file = (await (0, node_fs_promises.readdir)(fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
+	if (!file) return [];
+	return [{
+		name: FALLBACK_FONT_NAME,
+		data: await (0, node_fs_promises.readFile)(node_path.default.join(fontDir, file)),
+		weight: DEFAULT_FONT_WEIGHT,
+		style: DEFAULT_FONT_STYLE
+	}];
+}
 /**
 * Load the configured OG fonts ONCE per build. When `ogImage.fonts` is set, each
 * `path` is read to a Buffer (outside any per-image loop) and mapped to a Satori
@@ -3836,21 +3962,8 @@ function ogHash(input, template, fontsHash) {
 * ```
 */
 async function loadFonts(og) {
-	if (og.fonts && og.fonts.length > 0) return Promise.all(og.fonts.map(async (font) => ({
-		name: font.name,
-		data: await (0, node_fs_promises.readFile)(font.path),
-		weight: font.weight ?? 400,
-		style: font.style ?? "normal"
-	})));
-	if (!(0, node_fs.existsSync)(og.fontDir)) return [];
-	const file = (await (0, node_fs_promises.readdir)(og.fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
-	if (!file) return [];
-	return [{
-		name: "OG",
-		data: await (0, node_fs_promises.readFile)(node_path.default.join(og.fontDir, file)),
-		weight: 400,
-		style: "normal"
-	}];
+	if (og.fonts !== void 0 && og.fonts.length > 0) return loadExplicitFonts(og.fonts ?? []);
+	return scanFallbackFont(og.fontDir);
 }
 /**
 * The built-in default OG card — a centered title on a dark background. Used when
@@ -4440,6 +4553,47 @@ function fillTemplate(template, parts) {
 	return template.replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets);
 }
 /**
+* Resolve the compiled entry for a manifest definition, asserting the router
+* invariant that `manifest()` and `entries()` stay in sync (see {@link makeEntryMap}).
+*
+* @param byPattern - The pattern→compiled-`TypedRoute` index.
+* @param definition - The route definition from the manifest.
+* @returns The compiled `TypedRoute` for the definition's pattern.
+* @throws {Error} When no compiled entry exists for the definition's pattern.
+* @example
+* ```ts
+* const entry = resolveEntry(byPattern, definition);
+* ```
+*/
+function resolveEntry(byPattern, definition) {
+	const entry = byPattern.get(definition.pattern);
+	if (!entry) throw new Error(`[web] build.pages: no router entry for pattern "${definition.pattern}" — router.manifest() and router.entries() are out of sync.`);
+	return entry;
+}
+/**
+* Produce the param sets one route generates for a single locale: the route's
+* `.generate(ctx)` result when present, else a single empty-params instance. The
+* generate context is the spec `{ locale, require, has }`, so a `.generate()` handler
+* pulls sibling APIs the spec way.
+*
+* @param definition - The route definition from the manifest.
+* @param locale - The active locale to generate param sets for.
+* @param ctx - Plugin context (provides `require`/`has` for the generate context).
+* @returns The param sets for this route+locale (`[{}]` when there is no `.generate()`).
+* @example
+* ```ts
+* const paramSets = await generateParamSets(def, "en", ctx);
+* ```
+*/
+async function generateParameterSets(definition, locale, ctx) {
+	const generateContext = {
+		locale,
+		require: ctx.require,
+		has: ctx.has
+	};
+	return definition._handlers.generate ? await definition._handlers.generate(generateContext) : [{}];
+}
+/**
 * Expand one route definition into its concrete page instances across all locales,
 * using `generate?.(ctx)` when present (else a single empty-params instance per
 * locale). The generate context is the spec `{ locale, require, has }`, so a
@@ -4456,18 +4610,12 @@ function fillTemplate(template, parts) {
 * ```
 */
 async function expandRoute(definition, locales, byPattern, ctx) {
-	const entry = byPattern.get(definition.pattern);
-	if (!entry) throw new Error(`[web] build.pages: no router entry for pattern "${definition.pattern}" — router.manifest() and router.entries() are out of sync.`);
+	const entry = resolveEntry(byPattern, definition);
 	const { name } = entry;
 	const instances = [];
 	for (const locale of locales) {
-		const generateContext = {
-			locale,
-			require: ctx.require,
-			has: ctx.has
-		};
-		const generated = definition._handlers.generate ? await definition._handlers.generate(generateContext) : [{}];
-		for (const raw of generated) instances.push({
+		const parameterSets = await generateParameterSets(definition, locale, ctx);
+		for (const raw of parameterSets) instances.push({
 			definition,
 			entry,
 			name,
@@ -5033,6 +5181,23 @@ function resetRun(ctx) {
 	ctx.state.runId = `${Date.now()}-${(0, node_crypto.randomUUID)()}`;
 }
 /**
+* Report each rejected outcome from a settled output batch as a `build:outputs`
+* error, leaving fulfilled outcomes untouched (failures are isolated, not fatal).
+*
+* @param ctx - The phase context (used to log rejections).
+* @param settled - The settled results from the `runOutputs` task batch.
+* @example
+* ```ts
+* reportOutputFailures(ctx, await Promise.allSettled(tasks));
+* ```
+*/
+function reportOutputFailures(ctx, settled) {
+	for (const outcome of settled) {
+		if (outcome.status !== "rejected") continue;
+		ctx.log.error("build:outputs", { reason: String(outcome.reason) });
+	}
+}
+/**
 * Phase 4 — run feeds / sitemap / og-images / public / not-found / locale-redirects
 * concurrently, each gated by its config flag (or, for `public`, the presence of the
 * source dir), isolated with `Promise.allSettled` so one failure does not lose the
@@ -5057,8 +5222,7 @@ async function runOutputs(ctx) {
 	if ((0, node_fs.existsSync)(ctx.config.publicDir ?? "public")) tasks.push(withPhase(ctx, "public", () => copyPublic(ctx)));
 	if (ctx.config.notFound) tasks.push(withPhase(ctx, "not-found", () => generateNotFound(ctx)));
 	if (ctx.config.localeRedirects) tasks.push(withPhase(ctx, "locale-redirects", () => generateLocaleRedirects(ctx)));
-	const settled = await Promise.allSettled(tasks);
-	for (const outcome of settled) if (outcome.status === "rejected") ctx.log.error("build:outputs", { reason: String(outcome.reason) });
+	reportOutputFailures(ctx, await Promise.allSettled(tasks));
 }
 /**
 * Executes the full SSG pipeline for one run: clean → bundle → content/images →
@@ -5773,6 +5937,21 @@ async function writeScaffolding(input) {
 	return result;
 }
 /**
+* Create the parent directory then write the scaffold file to disk.
+*
+* @param cwd - Project root the file is written into.
+* @param relativePath - Path (relative to cwd) of the scaffold file.
+* @param contents - The content to write.
+* @returns Resolves once the file (and any missing parents) exist on disk.
+* @example
+* await writeScaffoldFile(process.cwd(), "wrangler.jsonc", contents);
+*/
+async function writeScaffoldFile(cwd, relativePath, contents) {
+	const absolutePath = node_path$1.default.join(cwd, relativePath);
+	await (0, node_fs_promises.mkdir)(node_path$1.default.dirname(absolutePath), { recursive: true });
+	await (0, node_fs_promises.writeFile)(absolutePath, contents, "utf8");
+}
+/**
 * Reconcile one scaffold file against disk: in check mode record drift, otherwise
 * skip an existing file or write a new one. Mutates the shared {@link InitResult}.
 *
@@ -5789,24 +5968,21 @@ async function writeScaffolding(input) {
 */
 async function reconcile(input) {
 	const { relativePath, expected, existing, cwd, check, result } = input;
+	const fileExists = existing !== null;
+	const fileDrifted = fileExists && existing !== expected;
 	if (check) {
-		if (existing !== null && existing !== expected) result.drifted.push(relativePath);
+		if (fileDrifted) result.drifted.push(relativePath);
 		return;
 	}
-	if (existing !== null) {
+	if (fileExists) {
 		result.skipped.push(relativePath);
 		return;
 	}
-	await (0, node_fs_promises.mkdir)(node_path$1.default.dirname(node_path$1.default.join(cwd, relativePath)), { recursive: true });
-	await (0, node_fs_promises.writeFile)(node_path$1.default.join(cwd, relativePath), expected, "utf8");
+	await writeScaffoldFile(cwd, relativePath, expected);
 	result.written.push(relativePath);
 }
 //#endregion
 //#region src/plugins/deploy/preflight.ts
-/**
-* @file deploy plugin — preflight validators (cheap → expensive), run in order
-* and short-circuiting on the first failure.
-*/
 /** Error prefix for deploy preflight failures (spec/11 Part-3). */
 const ERROR_PREFIX$5 = "[web] deploy";
 /** Cloudflare Pages free-tier file-count limit. */
@@ -5833,6 +6009,27 @@ function resolveFileLimit(env = process.env) {
 	return Math.min(parsed, PAID_TIER_FILE_LIMIT);
 }
 /**
+* Fold one directory entry into the running walk: queue subdirectories, and for
+* files bump the count and flag the path when it breaches the per-file size cap.
+*
+* @param entry - The directory entry being visited.
+* @param entryPath - The absolute path of `entry`.
+* @param result - The running walk aggregate, mutated in place.
+* @param stack - The pending-directory stack, pushed to for subdirectories.
+* @returns Resolves once the entry has been folded into `result`/`stack`.
+* @example
+* await inspectEntry(entry, "/project/dist/app.js", result, stack);
+*/
+async function inspectEntry(entry, entryPath, result, stack) {
+	if (entry.isDirectory()) {
+		stack.push(entryPath);
+		return;
+	}
+	if (!entry.isFile()) return;
+	result.fileCount += 1;
+	if ((await (0, node_fs_promises.stat)(entryPath)).size > MAX_FILE_SIZE_BYTES) result.oversizePath = entryPath;
+}
+/**
 * Recursively walk `dir`, counting files and flagging the first file over the
 * per-file size cap. Short-circuits once an oversize file is found.
 *
@@ -5847,20 +6044,13 @@ async function inspectOutdir(dir) {
 		oversizePath: null
 	};
 	const stack = [dir];
-	while (stack.length > 0) {
+	while (stack.length > 0 && result.oversizePath === null) {
 		const current = stack.pop();
 		if (current === void 0) break;
 		const entries = await (0, node_fs_promises.readdir)(current, { withFileTypes: true });
 		for (const entry of entries) {
-			const entryPath = node_path$1.default.join(current, entry.name);
-			if (entry.isDirectory()) stack.push(entryPath);
-			else if (entry.isFile()) {
-				result.fileCount += 1;
-				if ((await (0, node_fs_promises.stat)(entryPath)).size > MAX_FILE_SIZE_BYTES) {
-					result.oversizePath = entryPath;
-					return result;
-				}
-			}
+			await inspectEntry(entry, node_path$1.default.join(current, entry.name), result, stack);
+			if (result.oversizePath !== null) break;
 		}
 	}
 	return result;
@@ -6335,10 +6525,31 @@ function createRebuilder(input) {
 	let building = false;
 	let dirty = false;
 	/**
-	* Run the queued rebuild once, then — if a change arrived while it was in flight —
-	* re-run exactly once more so no change is dropped. Marks `dirty` (instead of
-	* running) when a rebuild is already underway, resetting the in-flight flag when
-	* each run settles.
+	* Rebuild repeatedly until no change arrived mid-flight: each pass clears `dirty`,
+	* runs one build, then loops again if a `schedule()` set `dirty` while it ran, so
+	* no change is dropped.
+	*
+	* @returns Resolves once a pass completes with no pending change (errors are routed,
+	*   never thrown).
+	* @example
+	* await drainPendingRebuilds();
+	*/
+	const drainPendingRebuilds = async () => {
+		do {
+			dirty = false;
+			await runOneRebuild({
+				runBuild: input.runBuild,
+				onReloaded: input.onReloaded,
+				onError: input.onError,
+				file: pendingFile
+			});
+		} while (dirty);
+	};
+	/**
+	* Run the queued rebuild once the debounce timer fires. Marks `dirty` (instead of
+	* running) when a rebuild is already underway, otherwise holds the in-flight flag
+	* across a full {@link drainPendingRebuilds} so concurrent changes coalesce into
+	* exactly one extra re-run.
 	*
 	* @returns Resolves once the rebuild (and any coalesced re-run) settles (errors are
 	*   routed, never thrown).
@@ -6352,15 +6563,7 @@ function createRebuilder(input) {
 			return;
 		}
 		building = true;
-		do {
-			dirty = false;
-			await runOneRebuild({
-				runBuild: input.runBuild,
-				onReloaded: input.onReloaded,
-				onError: input.onError,
-				file: pendingFile
-			});
-		} while (dirty);
+		await drainPendingRebuilds();
 		building = false;
 	};
 	return {
@@ -6497,6 +6700,26 @@ function createReloadHub() {
 		}
 	};
 }
+/** The content-type sent on rewritten HTML responses (live-reload injection). */
+const HTML_CONTENT_TYPE = "text/html; charset=utf-8";
+/**
+* Re-render a static file response with the live-reload client injected, preserving
+* the resolved status. Reads the original body to text so {@link injectReloadClient}
+* can splice the snippet in before `</body>`.
+*
+* @param response - The original static file response to rewrite.
+* @param status - The resolved status to carry onto the rewritten response.
+* @returns A fresh HTML response containing the injected reload client.
+* @example
+* const injected = await injectReloadResponse(fileResponse, 200);
+*/
+async function injectReloadResponse(response, status) {
+	const html = injectReloadClient(await response.text());
+	return new Response(html, {
+		status,
+		headers: { "content-type": HTML_CONTENT_TYPE }
+	});
+}
 /**
 * Build the live-reload-aware request handler for the dev server: serves the SSE
 * stream at {@link RELOAD_PATH}, injects the reload client into HTML responses (when
@@ -6516,13 +6739,7 @@ function createDevHandler(ctx, hub) {
 		const resolved = resolveCleanUrl(ctx.config.outDir, pathname);
 		if (resolved.file === null) return new Response("Not Found", { status: 404 });
 		const response = ctx.state.fileResponse(resolved.file, resolved.status);
-		if (ctx.config.liveReload && resolved.file.endsWith(".html")) {
-			const html = injectReloadClient(await response.text());
-			return new Response(html, {
-				status: resolved.status,
-				headers: { "content-type": "text/html; charset=utf-8" }
-			});
-		}
+		if (ctx.config.liveReload && resolved.file.endsWith(".html")) return injectReloadResponse(response, resolved.status);
 		return response;
 	};
 }
@@ -6740,6 +6957,56 @@ function validateConfig(config) {
 	if (typeof config.debounceMs !== "number" || config.debounceMs < 0) throw cliError("ERR_CLI_CONFIG", `${ERROR_PREFIX$3}: debounceMs must be a number >= 0.\n  Set pluginConfigs.cli.debounceMs to the rebuild debounce window in milliseconds (e.g. 150).`);
 }
 /**
+* Assert the SSG emitted the not-found page, rendering a hint and throwing
+* `ERR_CLI_NOT_FOUND` when it is missing (CF Pages flips to SPA mode without a
+* top-level 404). A no-op when the page exists.
+*
+* @param ctx - Plugin context (provides `state.render` for the failure hint).
+* @param page - The absolute path the not-found page is expected at.
+* @throws {Error} `ERR_CLI_NOT_FOUND` when the not-found page is missing.
+* @example
+* assertNotFoundPage(ctx, path.join(ctx.config.outDir, ctx.config.notFoundFile));
+*/
+function assertNotFoundPage(ctx, page) {
+	if ((0, node_fs.existsSync)(page)) return;
+	ctx.state.render.error(`${page} missing — set build.notFound (CF Pages would flip to SPA mode)`);
+	throw cliError("ERR_CLI_NOT_FOUND", `${ERROR_PREFIX$3}: ${page} missing after build.\n  Set build.notFound so the SSG emits it (CF Pages flips to SPA mode without a top-level 404), or pass { assertNotFound: false } to skip this check.`);
+}
+/**
+* Whether the deploy confirmation prompt should be shown to a human. True only on
+* an interactive TTY with `CI` unset and when the caller has not passed `yes`; CI
+* and non-TTY runs are not prompted so consumer scripts never block a pipeline.
+*
+* @param yes - The caller's `yes` flag (forces the prompt to be skipped anywhere).
+* @returns `true` when a confirmation prompt should be shown, otherwise `false`.
+* @example
+* if (shouldPromptDeploy(false)) { ... }
+*/
+function shouldPromptDeploy(yes) {
+	return process.stdout.isTTY === true && process.env.CI === void 0 && !yes;
+}
+/**
+* Resolve whether a deploy may proceed, handling the human/non-interactive split:
+* prompts an interactive TTY user (rendering the "skipped" warning on a "no"),
+* renders the non-interactive notice when no prompt and no `yes`, and otherwise
+* proceeds silently. Returns whether the caller should run the deploy.
+*
+* @param ctx - Plugin context (provides `state.confirm` and `state.render`).
+* @param yes - The caller's `yes` flag (forces the skip anywhere).
+* @returns `true` when the deploy should run, `false` when an interactive user declined.
+* @example
+* if (!(await confirmDeploy(ctx, false))) return { deployed: false, reason: "declined" };
+*/
+async function confirmDeploy(ctx, yes) {
+	if (!shouldPromptDeploy(yes)) {
+		if (!yes) ctx.state.render.info("non-interactive — skipping deploy confirmation");
+		return true;
+	}
+	const confirmed = await ctx.state.confirm(`Deploy ${ctx.config.outDir}/ to cloudflare-pages?`);
+	if (!confirmed) ctx.state.render.warn("deploy skipped");
+	return confirmed;
+}
+/**
 * Create the cli plugin API surface — exactly `build`, `serve`, `preview`, `deploy`.
 * Each method renders `state.render.header(<command>)` first, then does its work;
 * live progress is rendered by the hooks wired in `index.ts`, so each method's
@@ -6766,11 +7033,7 @@ function createApi$1(ctx) {
 			const { assertNotFound = true } = options;
 			ctx.state.render.header("build");
 			const result = await ctx.require(buildPlugin).run();
-			const page = node_path$1.default.join(ctx.config.outDir, ctx.config.notFoundFile);
-			if (assertNotFound && !(0, node_fs.existsSync)(page)) {
-				ctx.state.render.error(`${page} missing — set build.notFound (CF Pages would flip to SPA mode)`);
-				throw cliError("ERR_CLI_NOT_FOUND", `${ERROR_PREFIX$3}: ${page} missing after build.\n  Set build.notFound so the SSG emits it (CF Pages flips to SPA mode without a top-level 404), or pass { assertNotFound: false } to skip this check.`);
-			}
+			if (assertNotFound) assertNotFoundPage(ctx, node_path$1.default.join(ctx.config.outDir, ctx.config.notFoundFile));
 			return result;
 		},
 		/**
@@ -6816,15 +7079,10 @@ function createApi$1(ctx) {
 			const { branch, yes = false } = options;
 			ctx.state.render.header("deploy");
 			await ctx.require(deployPlugin).init({ ci: true });
-			if (process.stdout.isTTY === true && process.env.CI === void 0 && !yes) {
-				if (!await ctx.state.confirm(`Deploy ${ctx.config.outDir}/ to cloudflare-pages?`)) {
-					ctx.state.render.warn("deploy skipped");
-					return {
-						deployed: false,
-						reason: "declined"
-					};
-				}
-			} else if (!yes) ctx.state.render.info("non-interactive — skipping deploy confirmation");
+			if (!await confirmDeploy(ctx, yes)) return {
+				deployed: false,
+				reason: "declined"
+			};
 			return {
 				deployed: true,
 				...await ctx.require(deployPlugin).run(branch === void 0 ? {} : { branch })
@@ -7515,6 +7773,22 @@ 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);
 /**
+* Validate a single hook entry: its key must be a known hook name and its value
+* must be a function. Throws fail-fast on the first violation.
+*
+* @param componentName - The owning component name (for error messages).
+* @param hooks - The hooks object being validated.
+* @param key - The hook key to validate.
+* @throws {Error} If `key` is not in `COMPONENT_HOOK_NAMES`.
+* @throws {TypeError} If the hook value is not a function.
+* @example
+* validateHookEntry("counter", hooks, "onMount");
+*/
+function validateHookEntry(componentName, hooks, key) {
+	if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${componentName}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
+	if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${componentName}" must be a function\n  → provide a function or omit the hook`);
+}
+/**
 * 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.
@@ -7531,10 +7805,7 @@ const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
 */
 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`);
-	}
+	for (const key of Object.keys(hooks)) validateHookEntry(name, hooks, key);
 	return {
 		name,
 		hooks
@@ -7604,6 +7875,36 @@ function makeContext(element, data) {
 	};
 }
 /**
+* Mounts a single `data-component` element: classifies persistent vs
+* page-specific, builds the instance, fires `onCreate` then `onMount`, records
+* it in state, and emits `spa:component-mount`. No-ops if the element is already
+* mounted, has no component name, or names an unregistered component.
+*
+* @param state - The plugin state (registeredComponents + instances).
+* @param emit - The event emitter for spa:component-mount.
+* @param swapArea - The swap-region element, or null when none was found.
+* @param data - The current page data payload.
+* @param element - The candidate element carrying a `data-component` attribute.
+* @example
+* mountElement(state, emit, swapArea, data, element);
+*/
+function mountElement(state, emit, swapArea, data, element) {
+	if (state.instances.has(element)) return;
+	const name = element.dataset.component;
+	if (!name) return;
+	const definition = state.registeredComponents.get(name);
+	if (!definition) return;
+	const instance = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
+	const ctx = makeContext(element, data);
+	runHook(instance, "onCreate", ctx);
+	runHook(instance, "onMount", ctx);
+	state.instances.set(element, instance);
+	emit("spa:component-mount", {
+		name: definition.name,
+		el: element
+	});
+}
+/**
 * Scans the swap region, mounts components for matching `data-component`
 * elements, classifies persistent (outside swap area) vs page-specific (inside),
 * fires `onCreate` then `onMount`, and emits `spa:component-mount` per instance.
@@ -7619,22 +7920,7 @@ function scanAndMount(state, emit, swapSelector) {
 	if (typeof document === "undefined") return;
 	const swapArea = document.querySelector(swapSelector);
 	const data = extractPageData(document);
-	for (const element of document.querySelectorAll("[data-component]")) {
-		if (state.instances.has(element)) continue;
-		const name = element.dataset.component;
-		if (!name) continue;
-		const definition = state.registeredComponents.get(name);
-		if (!definition) continue;
-		const instance = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
-		const ctx = makeContext(element, data);
-		runHook(instance, "onCreate", ctx);
-		runHook(instance, "onMount", ctx);
-		state.instances.set(element, instance);
-		emit("spa:component-mount", {
-			name: definition.name,
-			el: element
-		});
-	}
+	for (const element of document.querySelectorAll("[data-component]")) mountElement(state, emit, swapArea, data, element);
 }
 /**
 * Unmounts page-specific instances inside the swap region (runs `onUnMount`
@@ -8105,6 +8391,8 @@ function attachRouter(handlers, navigate) {
 //#region src/plugins/spa/state.ts
 /** Error prefix for spa config-validation failures (spec/11 Part-3). */
 const ERROR_PREFIX$1 = "[web]";
+/** Last-resort `swapSelector` when neither config nor defaults supply one. */
+const FALLBACK_SWAP_SELECTOR = "main > section";
 /** Default SPA config (declared as a value — no inline assertion). */
 const defaultSpaConfig = {
 	swapSelector: "main > section",
@@ -8142,7 +8430,7 @@ function isValidSelector(selector) {
 * const resolved = resolveSpaConfig({ swapSelector: "main > section" });
 */
 function resolveSpaConfig(config) {
-	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? "main > section";
+	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? FALLBACK_SWAP_SELECTOR;
 	if (swapSelector.trim() === "") throw new Error(`${ERROR_PREFIX$1} spa.swapSelector must be a non-empty string.\n  Set a CSS selector for the page region to swap (e.g. "main > section").`);
 	if (!isValidSelector(swapSelector)) throw new Error(`${ERROR_PREFIX$1} spa.swapSelector is not a valid CSS selector: "${swapSelector}".\n  Provide a syntactically valid selector.`);
 	return {
@@ -8861,6 +9149,35 @@ function pullQuoteTransform(tree) {
 		}
 	});
 }
+/** CSS class for the divider wrapper that replaces an `<hr>`. */
+const SECTION_DIVIDER_CLASS = "section-divider";
+/** CSS class for the inner ornament span inside the section divider. */
+const SECTION_DIVIDER_ORNAMENT_CLASS = "section-divider-ornament";
+/** Glyphs rendered inside the section-divider ornament span. */
+const SECTION_DIVIDER_ORNAMENT = "***";
+/**
+* Rewrite one `<hr>` element in place into an ornamental section divider:
+* a `<div>` wrapper carrying a single ornament `<span>`.
+*
+* @param node - The hast element to rewrite (expected to be an `<hr>`).
+* @example
+* ```ts
+* rewriteHrToDivider(node);
+* ```
+*/
+function rewriteHrToDivider(node) {
+	node.tagName = "div";
+	node.properties = { class: SECTION_DIVIDER_CLASS };
+	node.children = [{
+		type: "element",
+		tagName: "span",
+		properties: { class: SECTION_DIVIDER_ORNAMENT_CLASS },
+		children: [{
+			type: "text",
+			value: SECTION_DIVIDER_ORNAMENT
+		}]
+	}];
+}
 /**
 * Hast transformer rewriting `<hr>` into an ornamental section divider.
 *
@@ -8872,19 +9189,8 @@ function pullQuoteTransform(tree) {
 */
 function sectionDividerTransform(tree) {
 	(0, unist_util_visit.visit)(tree, "element", (node) => {
-		if (node.tagName === "hr") {
-			node.tagName = "div";
-			node.properties = { class: "section-divider" };
-			node.children = [{
-				type: "element",
-				tagName: "span",
-				properties: { class: "section-divider-ornament" },
-				children: [{
-					type: "text",
-					value: "***"
-				}]
-			}];
-		}
+		if (node.tagName !== "hr") return;
+		rewriteHrToDivider(node);
 	});
 }
 /**