@moku-labs/web 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -398,6 +398,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
@@ -416,14 +450,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;
 }
 /**
@@ -1937,6 +1965,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.
@@ -1951,12 +1998,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
@@ -3538,6 +3580,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 (!existsSync(directory)) return false;
+	if ((await readdir(directory)).length === 0) return false;
+	await mkdir(target, { recursive: true });
+	await 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.
@@ -3558,13 +3620,7 @@ async function processImages(ctx, options = {}) {
 	const sourceDirectories = options.sourceDirectories ?? IMAGE_SOURCE_DIRECTORIES;
 	const target = path.join(ctx.config.outDir, "assets");
 	let copied = 0;
-	for (const directory of sourceDirectories) {
-		if (!existsSync(directory)) continue;
-		if ((await readdir(directory)).length === 0) continue;
-		await mkdir(target, { recursive: true });
-		await 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;
 }
@@ -3612,6 +3668,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
@@ -3636,17 +3723,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;
 }
@@ -3807,6 +3885,54 @@ function ogHash(input, template, fontsHash) {
 	].join("|");
 	return 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 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 (!existsSync(fontDir)) return [];
+	const file = (await readdir(fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
+	if (!file) return [];
+	return [{
+		name: FALLBACK_FONT_NAME,
+		data: await readFile(path.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
@@ -3823,21 +3949,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 readFile(font.path),
-		weight: font.weight ?? 400,
-		style: font.style ?? "normal"
-	})));
-	if (!existsSync(og.fontDir)) return [];
-	const file = (await readdir(og.fontDir)).find((name) => FONT_EXTENSIONS$1.some((extension) => name.endsWith(extension)));
-	if (!file) return [];
-	return [{
-		name: "OG",
-		data: await readFile(path.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
@@ -4427,6 +4540,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
@@ -4443,18 +4597,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,
@@ -5020,6 +5168,23 @@ function resetRun(ctx) {
 	ctx.state.runId = `${Date.now()}-${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
@@ -5044,8 +5209,7 @@ async function runOutputs(ctx) {
 	if (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 →
@@ -5597,6 +5761,19 @@ const CHECKOUT_SHA = "11bd71901bbe5b1630ceea73d27597364c9af683";
 const SETUP_BUN_SHA = "4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5";
 /** Pinned `cloudflare/wrangler-action` commit SHA. */
 const WRANGLER_ACTION_SHA = "f84a562284fc78278ff9052435d9526f9c718361";
+/** The `on:` block for each {@link WorkflowTrigger} (kept indentation-exact for YAML). */
+const TRIGGER_ON_BLOCKS = {
+	auto: `on:
+  push:
+    branches: [main]
+  workflow_dispatch:`,
+	"versioned-tag": `on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:`,
+	dispatch: `on:
+  workflow_dispatch:`
+};
 /**
 * Generate a SHA-pinned GitHub Actions workflow that builds and deploys to
 * Cloudflare Pages. Every action is pinned to a commit SHA (with a `# vX`
@@ -5606,9 +5783,10 @@ const WRANGLER_ACTION_SHA = "f84a562284fc78278ff9052435d9526f9c718361";
 *
 * @param input - The generator inputs.
 * @param input.slug - Cloudflare project-name slug used as the wrangler `--project-name`.
+* @param input.trigger - What fires the workflow (see {@link WorkflowTrigger}). Default `"auto"`.
 * @returns The workflow YAML.
 * @example
-* generateGithubWorkflow({ slug: "my-site" });
+* generateGithubWorkflow({ slug: "my-site", trigger: "versioned-tag" });
 */
 function generateGithubWorkflow(input) {
 	return `# .github/workflows/deploy.yml — generated by \`app.deploy.init({ ci: true })\`.
@@ -5616,10 +5794,7 @@ function generateGithubWorkflow(input) {
 
 name: Deploy
 
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
+${TRIGGER_ON_BLOCKS[input.trigger ?? "auto"]}
 
 permissions:
   contents: read
@@ -5751,7 +5926,10 @@ async function writeScaffolding(input) {
 	});
 	if (ci) await reconcile({
 		relativePath: WORKFLOW_PATH,
-		expected: generateGithubWorkflow({ slug }),
+		expected: generateGithubWorkflow({
+			slug,
+			...options.workflowTrigger ? { trigger: options.workflowTrigger } : {}
+		}),
 		existing: await readMaybe(cwd, WORKFLOW_PATH),
 		cwd,
 		check,
@@ -5760,6 +5938,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 = path.join(cwd, relativePath);
+	await mkdir(path.dirname(absolutePath), { recursive: true });
+	await 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}.
 *
@@ -5776,24 +5969,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 mkdir(path.dirname(path.join(cwd, relativePath)), { recursive: true });
-	await writeFile(path.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. */
@@ -5820,6 +6010,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 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.
 *
@@ -5834,20 +6045,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 readdir(current, { withFileTypes: true });
 		for (const entry of entries) {
-			const entryPath = path.join(current, entry.name);
-			if (entry.isDirectory()) stack.push(entryPath);
-			else if (entry.isFile()) {
-				result.fileCount += 1;
-				if ((await stat(entryPath)).size > MAX_FILE_SIZE_BYTES) {
-					result.oversizePath = entryPath;
-					return result;
-				}
-			}
+			await inspectEntry(entry, path.join(current, entry.name), result, stack);
+			if (result.oversizePath !== null) break;
 		}
 	}
 	return result;
@@ -6243,6 +6447,185 @@ const deployPlugin = createPlugin$1("deploy", {
 	api: createApi$2
 });
 //#endregion
+//#region src/plugins/cli/deploy-wizard.ts
+/**
+* @file cli plugin — the guided deploy wizard (`cli.deploy({ guided: true })`). Walks a
+* human through a Cloudflare Pages deploy: checks prerequisites (wrangler config + the
+* Cloudflare credentials) with concrete fix guidance, offers to scaffold/build what is
+* missing, HARD-GATES the deploy on everything being green, runs a local build smoke
+* test, confirms, deploys, then offers to scaffold a GitHub Actions workflow (auto on
+* push to main, or a versioned/manual trigger). The non-guided `--cli` path stays in
+* `api.ts`. Every prompt + line of output flows through injectable `state` seams.
+*/
+/** How to create a Cloudflare API token + where to make it available locally. */
+const TOKEN_HELP = [
+	"Create one at https://dash.cloudflare.com/profile/api-tokens → Create Token →",
+	"use the \"Cloudflare Pages — Edit\" template (or a custom token with the",
+	"Account › Cloudflare Pages › Edit permission). Then make it available:",
+	"  export CLOUDFLARE_API_TOKEN=…   (shell)   or add it to .env (gitignored)."
+].join("\n");
+/** Where to find the Cloudflare account id + where to make it available locally. */
+const ACCOUNT_HELP = [
+	"Find it on the Cloudflare dashboard → Workers & Pages: the Account ID is in the",
+	"right-hand sidebar (also in the dashboard URL). Then make it available:",
+	"  export CLOUDFLARE_ACCOUNT_ID=…   or add it to .env."
+].join("\n");
+/** The GitHub repo secrets the generated workflow consumes. */
+const SECRETS_HELP = ["Add these repo secrets (GitHub → Settings → Secrets and variables → Actions):", "CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID"].join("\n");
+/**
+* Evaluate the three deploy prerequisites against the current project: the Cloudflare
+* wrangler config exists, and both Cloudflare credentials are present in the environment.
+*
+* @param cwd - The project root (where `wrangler.jsonc` lives).
+* @returns The ordered prerequisite checks.
+* @example
+* const prereqs = diagnose(process.cwd());
+*/
+function diagnose(cwd) {
+	const wranglerOk = existsSync(path.join(cwd, "wrangler.jsonc"));
+	const tokenOk = (process.env.CLOUDFLARE_API_TOKEN ?? "") !== "";
+	const accountOk = (process.env.CLOUDFLARE_ACCOUNT_ID ?? "") !== "";
+	return [
+		{
+			ok: wranglerOk,
+			label: "wrangler.jsonc (Cloudflare project config)",
+			detail: wranglerOk ? void 0 : "Missing — scaffold it (offered below) or run app.deploy.init().",
+			scaffoldable: true
+		},
+		{
+			ok: tokenOk,
+			label: "CLOUDFLARE_API_TOKEN is set",
+			detail: tokenOk ? void 0 : TOKEN_HELP,
+			scaffoldable: false
+		},
+		{
+			ok: accountOk,
+			label: "CLOUDFLARE_ACCOUNT_ID is set",
+			detail: accountOk ? void 0 : ACCOUNT_HELP,
+			scaffoldable: false
+		}
+	];
+}
+/**
+* Offer to scaffold a missing `wrangler.jsonc` (the only auto-fixable prerequisite),
+* generating it via the deploy plugin when the user accepts.
+*
+* @param ctx - The cli plugin context.
+* @param prereqs - The current prerequisite checks.
+* @returns Resolves once any accepted fix has run.
+* @example
+* await offerScaffold(ctx, diagnose(cwd));
+*/
+async function offerScaffold(ctx, prereqs) {
+	if (!prereqs.some((item) => item.scaffoldable && !item.ok)) return;
+	if (!await ctx.state.confirm("Scaffold wrangler.jsonc now?")) return;
+	await ctx.require(deployPlugin).init({});
+	ctx.state.render.check(true, "wrangler.jsonc scaffolded");
+}
+/**
+* Map a top-level workflow choice (and, for the versioned option, a sub-choice) to the
+* concrete {@link WorkflowTrigger}, or `null` when the user chose to skip setup.
+*
+* @param ctx - The cli plugin context (for the follow-up sub-choice prompt).
+* @param choice - The selected zero-based index of the top-level options.
+* @returns The resolved trigger, or `null` to skip.
+* @example
+* const trigger = await resolveTrigger(ctx, 1);
+*/
+async function resolveTrigger(ctx, choice) {
+	if (choice === 2) return null;
+	if (choice === 0) return "auto";
+	return await ctx.state.select("How should the versioned deploy be triggered?", ["On a version tag push (v*) + the manual Run-workflow button", "Manual Run-workflow button only (workflow_dispatch)"]) === 0 ? "versioned-tag" : "dispatch";
+}
+/**
+* Offer to scaffold a GitHub Actions deploy workflow, letting the user choose how it is
+* triggered, then remind them which repo secrets to add. A no-op past a "skip" choice.
+*
+* @param ctx - The cli plugin context.
+* @returns Resolves once any chosen workflow has been scaffolded.
+* @example
+* await offerWorkflowSetup(ctx);
+*/
+async function offerWorkflowSetup(ctx) {
+	ctx.state.render.heading("Automate future deploys (GitHub Actions)");
+	const trigger = await resolveTrigger(ctx, await ctx.state.select("Set up a deploy workflow?", [
+		"Auto-deploy on every push to main",
+		"Manual / versioned deploy (choose trigger)",
+		"Skip for now"
+	]));
+	if (trigger === null) return;
+	const result = await ctx.require(deployPlugin).init({
+		ci: true,
+		workflowTrigger: trigger
+	});
+	const workflowPath = ".github/workflows/deploy.yml";
+	const wrote = result.written.includes(workflowPath);
+	ctx.state.render.check(true, wrote ? `wrote ${workflowPath}` : `${workflowPath} already exists (left unchanged)`);
+	ctx.state.render.info(SECRETS_HELP);
+}
+/**
+* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin and
+* report the outcome. A declined confirm returns `{ deployed: false, reason: "declined" }`.
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override + `yes`).
+* @returns The deploy outcome.
+* @example
+* const outcome = await runDeployStep(ctx, { yes: true });
+*/
+async function runDeployStep(ctx, options) {
+	ctx.state.render.heading("Deploy");
+	if (!(options.yes === true || await ctx.state.confirm(`Deploy ${ctx.config.outDir}/ to Cloudflare Pages now?`))) {
+		ctx.state.render.warn("deploy skipped");
+		return {
+			deployed: false,
+			reason: "declined"
+		};
+	}
+	return {
+		deployed: true,
+		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
+	};
+}
+/**
+* Run the guided deploy wizard end to end: diagnose prerequisites (offering to scaffold
+* the wrangler config), HARD-GATE on the remaining blockers, run a local build smoke
+* test, deploy (with confirmation), then offer to scaffold a CI workflow. Returns
+* `{ deployed: false, reason: "blocked" }` when prerequisites are unmet, so a thin script
+* can exit non-zero. Assumes the caller already rendered the `deploy` header.
+*
+* @param ctx - The cli plugin context (state seams + `require` + config).
+* @param options - The deploy options (branch override, `yes`, `guided`).
+* @returns The deploy outcome (`deployed`, or a `declined`/`blocked` skip).
+* @example
+* const outcome = await runDeployWizard(ctx, { guided: true });
+*/
+async function runDeployWizard(ctx, options) {
+	const cwd = process.cwd();
+	ctx.state.render.heading("Checking prerequisites");
+	for (const item of diagnose(cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
+	await offerScaffold(ctx, diagnose(cwd));
+	const blockers = diagnose(cwd).filter((item) => !item.ok);
+	if (blockers.length > 0) {
+		ctx.state.render.heading("Not ready to deploy");
+		for (const item of blockers) ctx.state.render.check(false, item.label, item.detail);
+		ctx.state.render.warn(`Fix the ${blockers.length} item(s) above, then re-run \`bun run deploy\`.`);
+		return {
+			deployed: false,
+			reason: "blocked"
+		};
+	}
+	ctx.state.render.heading("Local test");
+	const summary = await ctx.require(buildPlugin).run();
+	ctx.state.render.check(true, `built ${summary.pageCount} pages → ${summary.outDir}/`);
+	const notFoundOk = existsSync(path.join(ctx.config.outDir, ctx.config.notFoundFile));
+	ctx.state.render.check(notFoundOk, `${ctx.config.notFoundFile} present`, notFoundOk ? void 0 : "Set build.notFound so the SSG emits it (CF Pages else flips to SPA mode).");
+	ctx.state.render.info("Tip: run `bun run preview` to eyeball the built site before deploying.");
+	const outcome = await runDeployStep(ctx, options);
+	await offerWorkflowSetup(ctx);
+	return outcome;
+}
+//#endregion
 //#region src/plugins/cli/errors.ts
 /** Error prefix for cli config/validation/runtime failures (spec/11 Part-3). */
 const ERROR_PREFIX$3 = "[web] cli";
@@ -6276,11 +6659,12 @@ function injectReloadClient(html) {
 	return index === -1 ? html + RELOAD_CLIENT : html.slice(0, index) + RELOAD_CLIENT + html.slice(index);
 }
 /**
-* Run one rebuild and report the result. Skips re-entrancy via the shared `building`
-* flag and routes success to `onReloaded`, failure to `onError`.
+* Run one rebuild and report the result. Announces the start (`onRebuildStart`), then
+* routes success to `onReloaded` and failure to `onError`.
 *
 * @param input - The rebuild dependencies + the changed file.
 * @param input.runBuild - Runs one build and resolves with its summary.
+* @param input.onRebuildStart - Called with the changed file just before the build runs.
 * @param input.onReloaded - Called with the changed file + summary after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @param input.file - The changed file to report alongside the summary.
@@ -6289,6 +6673,7 @@ function injectReloadClient(html) {
 * await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md" });
 */
 async function runOneRebuild(input) {
+	input.onRebuildStart?.(input.file);
 	try {
 		const summary = await input.runBuild();
 		input.onReloaded({
@@ -6310,6 +6695,7 @@ async function runOneRebuild(input) {
 * @param input - The rebuild dependencies.
 * @param input.debounceMs - Debounce window in milliseconds.
 * @param input.runBuild - Runs one build and resolves with its summary.
+* @param input.onRebuildStart - Called with the changed file just before each build runs.
 * @param input.onReloaded - Called with the changed file + summary after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @returns The debounced rebuild driver.
@@ -6322,10 +6708,32 @@ 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,
+				...input.onRebuildStart ? { onRebuildStart: input.onRebuildStart } : {},
+				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).
@@ -6339,15 +6747,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 {
@@ -6376,6 +6776,70 @@ function createRebuilder(input) {
 	};
 }
 /**
+* Whether a changed path (relative to a watched dir) is editor/OS noise that is never a
+* page source: any hidden segment (`.DS_Store`, anything under `.git/` or `.cache/`,
+* vim `.*.swp`) or a `~` backup file. Checks every segment, not just the basename.
+*
+* @param filename - The changed path relative to its watched directory.
+* @returns `true` when the change should be ignored as noise.
+* @example
+* isNoisePath(".git/HEAD"); // true
+*/
+function isNoisePath(filename) {
+	return filename.split(/[/\\]/).some((segment) => segment.startsWith(".")) || filename.endsWith("~");
+}
+/**
+* Create a {@link ChangeGate} that drops three kinds of spurious change events before
+* they reach the debounced rebuilder: editor/OS noise (dotfiles, backups), writes under
+* `outDir` (the build's own output — a loop guard), and the stale duplicate/parent-dir
+* echoes macOS fires for one save. Staleness is judged by a build-start high-water mark:
+* a change whose file mtime is at or before the last build we started was already
+* captured (or is a late echo), so it is ignored — while a genuinely newer edit (even
+* one made mid-build) and a deletion (missing file) always pass. The single timestamp
+* also means no per-path map grows over a long session.
+*
+* @param input - The gate dependencies.
+* @param input.outDir - The build output directory whose writes must never re-trigger a build.
+* @param input.fileMtime - Resolves a path's mtime in ms (or `null` when missing).
+* @param input.now - Monotonic wall clock (ms) used for the build-start high-water mark.
+* @returns The change gate.
+* @example
+* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock });
+*/
+function createChangeGate(input) {
+	const outDirAbs = path.resolve(input.outDir);
+	let lastBuildStartedAt = input.now();
+	return {
+		/**
+		* Decide whether a change beneath `dir` warrants a rebuild (see {@link ChangeGate.accept}).
+		*
+		* @param dir - The watched directory the event fired on.
+		* @param filename - The changed path relative to `dir` (or `undefined`).
+		* @returns `true` to schedule a rebuild, `false` to ignore.
+		* @example
+		* gate.accept("content", "post/en.md");
+		*/
+		accept(dir, filename) {
+			if (filename === void 0) return true;
+			if (isNoisePath(filename)) return false;
+			const changed = path.resolve(dir, filename);
+			if (changed === outDirAbs || changed.startsWith(`${outDirAbs}${path.sep}`)) return false;
+			const mtime = input.fileMtime(changed);
+			if (mtime !== null && mtime < lastBuildStartedAt) return false;
+			return true;
+		},
+		/**
+		* Advance the high-water mark to now (see {@link ChangeGate.markBuildStart}).
+		*
+		* @example
+		* gate.markBuildStart();
+		*/
+		markBuildStart() {
+			lastBuildStartedAt = input.now();
+		}
+	};
+}
+/**
 * Install SIGINT/SIGTERM handlers that run `teardown()` and resolve the returned
 * promise, so a long-running command (`serve`/`preview`) unblocks its `await` on
 * Ctrl-C / termination and detaches its own listeners. Used by both servers.
@@ -6407,18 +6871,45 @@ function installSignalTeardown(teardown) {
 const SSE_OPEN = ": connected\n\n";
 /** The SSE frame pushed to reload a connected browser. */
 const SSE_RELOAD = "event: reload\ndata: 1\n\n";
+/** The SSE comment frame sent on the heartbeat to keep an idle stream warm. */
+const SSE_PING = ": ping\n\n";
+/** Default heartbeat interval (ms): one ping well under any 30s+ proxy idle window. */
+const DEFAULT_HEARTBEAT_MS = 15e3;
 /**
 * Create a {@link ReloadHub} backed by `ReadableStream` controllers. Each `connect()`
 * enqueues into a new stream; `reloadAll()` writes the reload frame to every live
-* controller (dropping any that have closed).
+* controller (dropping any that have closed). A periodic heartbeat comment keeps idle
+* streams warm — belt-and-suspenders alongside the dev server's `idleTimeout: 0`, so a
+* quiet connection is never severed (which the browser surfaces as
+* `ERR_INCOMPLETE_CHUNKED_ENCODING` and then reconnects in a storm).
 *
+* @param options - Optional heartbeat tuning.
+* @param options.heartbeatMs - Heartbeat interval in ms (`0` disables). Default `15000`.
 * @returns The reload hub.
 * @example
 * const hub = createReloadHub();
 */
-function createReloadHub() {
+function createReloadHub(options = {}) {
 	const encoder = new TextEncoder();
 	const clients = /* @__PURE__ */ new Set();
+	/**
+	* Enqueue one frame to every live controller, dropping any that have closed.
+	*
+	* @param frame - The SSE wire text to broadcast.
+	* @example
+	* broadcast(SSE_RELOAD);
+	*/
+	const broadcast = (frame) => {
+		const bytes = encoder.encode(frame);
+		for (const controller of clients) try {
+			controller.enqueue(bytes);
+		} catch {
+			clients.delete(controller);
+		}
+	};
+	const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+	const heartbeat = heartbeatMs > 0 ? setInterval(() => broadcast(SSE_PING), heartbeatMs) : void 0;
+	heartbeat?.unref?.();
 	return {
 		/**
 		* Open one SSE connection, register its controller, and return the streaming
@@ -6466,11 +6957,7 @@ function createReloadHub() {
 		* hub.reloadAll();
 		*/
 		reloadAll() {
-			for (const controller of clients) try {
-				controller.enqueue(encoder.encode(SSE_RELOAD));
-			} catch {
-				clients.delete(controller);
-			}
+			broadcast(SSE_RELOAD);
 		},
 		/**
 		* The number of currently-connected clients.
@@ -6481,9 +6968,42 @@ function createReloadHub() {
 		*/
 		size() {
 			return clients.size;
+		},
+		/**
+		* Stop the heartbeat and close every live SSE stream (SIGINT/SIGTERM teardown).
+		*
+		* @example
+		* hub.close();
+		*/
+		close() {
+			if (heartbeat !== void 0) clearInterval(heartbeat);
+			for (const controller of clients) try {
+				controller.close();
+			} catch {}
+			clients.clear();
 		}
 	};
 }
+/** 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
@@ -6503,13 +7023,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;
 	};
 }
@@ -6530,8 +7044,14 @@ async function runDevServer(ctx, port) {
 	const hub = createReloadHub();
 	const server = ctx.state.serveStatic({
 		port,
+		idleTimeout: 0,
 		fetch: createDevHandler(ctx, hub)
 	});
+	const gate = createChangeGate({
+		outDir: ctx.config.outDir,
+		fileMtime: ctx.state.fileMtime,
+		now: ctx.state.clock
+	});
 	const rebuilder = createRebuilder({
 		debounceMs: ctx.config.debounceMs,
 		/**
@@ -6545,6 +7065,17 @@ async function runDevServer(ctx, port) {
 			return ctx.require(buildPlugin).run();
 		},
 		/**
+		* Show the compact in-place "rebuilding {label}" line before the build runs.
+		*
+		* @param file - The changed watch target shown in the line.
+		* @example
+		* onRebuildStart("content");
+		*/
+		onRebuildStart(file) {
+			gate.markBuildStart();
+			ctx.state.render.rebuildStart(file);
+		},
+		/**
 		* Render the reload line and push a browser reload after a rebuild.
 		*
 		* @param info - The changed file plus the rebuild's page count and duration.
@@ -6566,7 +7097,9 @@ async function runDevServer(ctx, port) {
 			ctx.state.render.error("rebuild failed", error);
 		}
 	});
-	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, () => rebuilder.schedule(dir)));
+	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, (filename) => {
+		if (gate.accept(dir, filename)) rebuilder.schedule(dir);
+	}));
 	ctx.state.render.serverReady({
 		local: `http://localhost:${port}`,
 		network: ctx.state.networkUrl(port),
@@ -6575,6 +7108,7 @@ async function runDevServer(ctx, port) {
 	return installSignalTeardown(() => {
 		rebuilder.cancel();
 		for (const watcher of watchers) watcher.close();
+		hub.close();
 		server.stop();
 	});
 }
@@ -6727,6 +7261,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 (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
@@ -6753,11 +7337,7 @@ function createApi$1(ctx) {
 			const { assertNotFound = true } = options;
 			ctx.state.render.header("build");
 			const result = await ctx.require(buildPlugin).run();
-			const page = path.join(ctx.config.outDir, ctx.config.notFoundFile);
-			if (assertNotFound && !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, path.join(ctx.config.outDir, ctx.config.notFoundFile));
 			return result;
 		},
 		/**
@@ -6788,30 +7368,27 @@ function createApi$1(ctx) {
 			return runPreviewServer(ctx, port);
 		},
 		/**
-		* Scaffold, then deploy. A y/N confirm is shown only when a human is present (an
-		* interactive TTY, with `CI` unset). Non-interactive runs (CI, or any non-TTY)
-		* skip the prompt and deploy, so the consumer scripts never hang a pipeline.
-		* `options.yes` forces the skip anywhere. An interactive "no" returns
-		* `{ deployed: false, reason: "declined" }`.
+		* Deploy to Cloudflare Pages. Two modes: `{ guided: true }` runs the interactive
+		* setup wizard (diagnose prerequisites, guide fixes, gate, local test, deploy, offer
+		* a CI workflow); the default direct path scaffolds, gates on a y/N confirm (shown
+		* only to an interactive TTY with `CI` unset — non-interactive runs proceed so a
+		* pipeline never hangs), then deploys. `options.yes` forces the skip. A "no" returns
+		* `{ deployed: false, reason: "declined" }`; the wizard may return `"blocked"`.
 		*
-		* @param options - Optional branch override and `yes` flag.
-		* @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+		* @param options - Optional branch override, `yes` flag, and `guided` toggle.
+		* @returns The deploy outcome (completed details, or a `declined`/`blocked` skip).
 		* @example
-		* await api.deploy({ branch: "preview/x", yes: true });
+		* await api.deploy({ guided: true });
 		*/
 		async deploy(options = {}) {
 			const { branch, yes = false } = options;
 			ctx.state.render.header("deploy");
+			if (options.guided === true) return runDeployWizard(ctx, options);
 			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 })
@@ -6906,6 +7483,39 @@ const ANSI = {
 	cyan: `${ESC}[36m`,
 	gray: `${ESC}[90m`
 };
+/** ANSI: erase the entire current line, leaving the cursor where it is. */
+const CLEAR_LINE = `${ESC}[2K`;
+/** ANSI: erase from the cursor to the end of the screen (drops stale trailing rows). */
+const CLEAR_BELOW = `${ESC}[0J`;
+/**
+* Braille spinner frames for live "working…" indicators on a TTY (advance one per tick).
+* Off a TTY the Panel never animates, so this is unused in plain/CI output.
+*/
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/**
+* The ANSI sequence to move the cursor up `n` lines (empty string for `n <= 0`). The
+* Panel uses it to repaint a live block in place — move up over the previous draw, then
+* rewrite each row — so progress updates a fixed region instead of scrolling new lines.
+*
+* @param n - Number of lines to move the cursor up.
+* @returns The cursor-up escape sequence, or `""` when `n <= 0`.
+* @example
+* cursorUp(3); // "\x1b[3A"
+*/
+function cursorUp(n) {
+	return n > 0 ? `${ESC}[${n}A` : "";
+}
 /** Unicode rounded box glyphs used when output is a color-capable TTY. */
 const UNICODE_BOX = {
 	topLeft: "╭",
@@ -7122,8 +7732,97 @@ function durationSuffix(palette, durationMs) {
 function createPanelRenderer(options = {}) {
 	const write = options.write ?? ((line) => console.log(line));
 	const writeError = options.writeError ?? ((line) => console.error(line));
+	const writeRaw = options.writeRaw ?? ((chunk) => {
+		process.stdout.write(chunk);
+	});
+	const now = options.now ?? Date.now;
 	const color = options.color ?? supportsColor();
 	const palette = makePalette(color);
+	let phaseRows = [];
+	let phaseDrawn = 0;
+	let phaseOpen = false;
+	let rebuilding = false;
+	let rebuildLabel = "";
+	let rebuildStartedAt = 0;
+	let spinnerFrame = 0;
+	let ticker;
+	/**
+	* The current spinner glyph (with a static fallback under `noUncheckedIndexedAccess`).
+	*
+	* @returns The active braille spinner frame.
+	* @example
+	* frameGlyph(); // "⠙"
+	*/
+	const frameGlyph = () => SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length] ?? "⠋";
+	/**
+	* Render one phase row: a green `✓ name · time` when done, else a spinning cyan glyph
+	* before the dim name.
+	*
+	* @param row - The phase row to render.
+	* @returns The rendered row line (no trailing newline).
+	* @example
+	* renderPhaseRow({ name: "pages", done: true, durationMs: 12 });
+	*/
+	const renderPhaseRow = (row) => {
+		if (row.done) return `  ${palette.green("✓")} ${row.name}${durationSuffix(palette, row.durationMs)}`;
+		return `  ${palette.cyan(frameGlyph())} ${palette.dim(row.name)}`;
+	};
+	/**
+	* Repaint the live phase block in place: move up over the prior draw, then rewrite each
+	* row (clearing any stale trailing lines).
+	*
+	* @example
+	* paintPhaseBlock();
+	*/
+	const paintPhaseBlock = () => {
+		let frame = cursorUp(phaseDrawn);
+		for (const row of phaseRows) frame += `${CLEAR_LINE}${renderPhaseRow(row)}\n`;
+		writeRaw(frame + CLEAR_BELOW);
+		phaseDrawn = phaseRows.length;
+	};
+	/**
+	* Repaint the single in-place rebuild line (spinner + label + live elapsed seconds).
+	*
+	* @example
+	* paintRebuildLine();
+	*/
+	const paintRebuildLine = () => {
+		const elapsed = ((now() - rebuildStartedAt) / 1e3).toFixed(1);
+		const meta = palette.dim(`· ${elapsed}s`);
+		writeRaw(`\r${CLEAR_LINE}  ${palette.cyan(frameGlyph())} rebuilding ${rebuildLabel} ${meta}`);
+	};
+	/**
+	* Advance the spinner one frame and repaint whichever live region is active.
+	*
+	* @example
+	* onTick();
+	*/
+	const onTick = () => {
+		spinnerFrame += 1;
+		if (rebuilding) paintRebuildLine();
+		else if (phaseOpen) paintPhaseBlock();
+	};
+	/**
+	* Start the animation ticker (TTY only; idempotent; `unref`'d so it never blocks exit).
+	*
+	* @example
+	* startTicker();
+	*/
+	const startTicker = () => {
+		if (!color || ticker) return;
+		ticker = setInterval(onTick, 80);
+		ticker.unref?.();
+	};
+	/**
+	* Stop the animation ticker if running.
+	*
+	* @example
+	* stopTicker();
+	*/
+	const stopTicker = () => {
+		if (ticker) clearInterval(ticker);
+		ticker = void 0;
+	};
 	/**
 	* Write each line of a multi-line block through the stdout sink.
 	*
@@ -7146,15 +7845,38 @@ function createPanelRenderer(options = {}) {
 			writeBlock(box([`${palette.bold(palette.cyan("MOKU WEB"))}  ${palette.dim(COMMAND_LABEL[command])}`], color));
 		},
 		/**
-		* Render a live per-phase row from a `build:phase` event.
+		* Render a per-phase row from a `build:phase` event. On a TTY each phase is ONE row
+		* that updates in place (spinning glyph while running → green ✓ + duration when done);
+		* off a TTY one line is printed per completed phase (no start/done duplication). A
+		* no-op while a serve() rebuild is in flight — those show the compact rebuild line.
 		*
 		* @param phase - The `build:phase` payload.
 		* @example
 		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
 		*/
 		phase(phase) {
+			if (rebuilding) return;
+			if (!color) {
+				if (phase.status === "done") write(`  ${palette.green("✓")} ${phase.phase}${durationSuffix(palette, phase.durationMs)}`);
+				return;
+			}
+			if (!phaseOpen) {
+				phaseRows = [];
+				phaseDrawn = 0;
+				phaseOpen = true;
+			}
 			const done = phase.status === "done";
-			write(`  ${done ? palette.green("✓") : palette.dim("•")} ${done ? phase.phase : palette.dim(phase.phase)}${durationSuffix(palette, phase.durationMs)}`);
+			const existing = phaseRows.find((row) => row.name === phase.phase);
+			if (existing) {
+				existing.done = done;
+				existing.durationMs = phase.durationMs;
+			} else phaseRows.push({
+				name: phase.phase,
+				done,
+				durationMs: phase.durationMs
+			});
+			paintPhaseBlock();
+			startTicker();
 		},
 		/**
 		* Render the BUILD summary block from a `build:complete` event.
@@ -7164,6 +7886,10 @@ function createPanelRenderer(options = {}) {
 		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
 		*/
 		built(summary) {
+			if (rebuilding) return;
+			phaseOpen = false;
+			phaseDrawn = 0;
+			stopTicker();
 			const pages = palette.bold(String(summary.pageCount));
 			writeBlock(box([
 				`${palette.green("✓")} ${palette.bold("BUILD")} complete`,
@@ -7185,15 +7911,47 @@ function createPanelRenderer(options = {}) {
 			writeBlock(box(lines, color));
 		},
 		/**
-		* Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+		* Begin a serve() rebuild: show ONE compact "rebuilding {label}" line (an animated
+		* spinner with live elapsed on a TTY; a plain "~ {label}" line otherwise) and mute
+		* the verbose phase rows + BUILD box until {@link reload}/{@link error} settles it.
+		*
+		* @param label - The changed watch target shown in the line.
+		* @example
+		* render.rebuildStart("content");
+		*/
+		rebuildStart(label) {
+			rebuilding = true;
+			rebuildLabel = label;
+			rebuildStartedAt = now();
+			spinnerFrame = 0;
+			if (!color) {
+				write(`  ${palette.yellow("~")} ${label}`);
+				return;
+			}
+			paintRebuildLine();
+			startTicker();
+		},
+		/**
+		* Settle the current rebuild: replace the in-place "rebuilding…" line with a compact
+		* "✓ rebuilt N pages · Xms · reloaded" (on a TTY) and re-enable verbose build output.
+		* Called standalone (no preceding {@link rebuildStart}) it also prints the "~ file"
+		* line so the changed target stays visible.
 		*
 		* @param info - The changed file plus the rebuild's page count and duration.
 		* @example
 		* render.reload({ file: "content/a.md", pageCount: 12, durationMs: 84 });
 		*/
 		reload(info) {
-			write(`  ${palette.yellow("~")} ${info.file}`);
-			write(`  ${palette.green("✓")} rebuilt ${palette.bold(String(info.pageCount))} pages ${palette.dim(`· ${info.durationMs}ms · browser reloaded`)}`);
+			const settledRebuild = rebuilding;
+			rebuilding = false;
+			stopTicker();
+			const line = `  ${palette.green("✓")} rebuilt ${palette.bold(String(info.pageCount))} pages ${palette.dim(`· ${info.durationMs}ms · reloaded`)}`;
+			if (settledRebuild && color) {
+				writeRaw(`\r${CLEAR_LINE}${line}\n`);
+				return;
+			}
+			if (!settledRebuild) write(`  ${palette.yellow("~")} ${info.file}`);
+			write(line);
 		},
 		/**
 		* Render the deploy result panel from a `deploy:complete` event.
@@ -7219,7 +7977,9 @@ function createPanelRenderer(options = {}) {
 		* render.info("watching for changes…");
 		*/
 		info(message) {
-			write(`  ${palette.cyan("›")} ${message}`);
+			const [first = "", ...rest] = message.split("\n");
+			write(`  ${palette.cyan("›")} ${first}`);
+			for (const line of rest) write(`    ${line}`);
 		},
 		/**
 		* Render a warning line (to stderr).
@@ -7240,8 +8000,38 @@ function createPanelRenderer(options = {}) {
 		* render.error("build failed", err);
 		*/
 		error(message, cause) {
+			if (rebuilding) {
+				rebuilding = false;
+				stopTicker();
+				if (color) writeRaw(`\r${CLEAR_LINE}`);
+			}
 			writeError(`  ${palette.red("✗")} ${message}`);
 			if (cause !== void 0) writeError(String(cause));
+		},
+		/**
+		* Render a section heading (a blank line + a bold cyan label) for a multi-step flow.
+		*
+		* @param text - The heading label.
+		* @example
+		* render.heading("Diagnostics");
+		*/
+		heading(text) {
+			write("");
+			write(`  ${palette.bold(palette.cyan(text))}`);
+		},
+		/**
+		* Render a diagnostic line: green `✓` (pass) or red `✗` (fail) + label, with optional
+		* dim, indented detail beneath (e.g. a fix hint for a failing check).
+		*
+		* @param ok - Whether the check passed.
+		* @param label - The check label.
+		* @param detail - Optional multi-line guidance shown indented under the line.
+		* @example
+		* render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
+		*/
+		check(ok, label, detail) {
+			write(`  ${ok ? palette.green("✓") : palette.red("✗")} ${label}`);
+			if (detail !== void 0) for (const line of detail.split("\n")) write(`      ${palette.dim(line)}`);
 		}
 	};
 }
@@ -7320,18 +8110,44 @@ function defaultConfirm(question) {
 	});
 }
 /**
+* Default stdin single-choice prompt. Prints the choices numbered from 1, reads a line
+* via `node:readline`, and resolves the chosen zero-based index (empty / out-of-range
+* falls back to 0). Tests inject a canned selection so no real TTY interaction occurs.
+*
+* @param question - The prompt to display.
+* @param choices - The selectable option labels.
+* @returns Resolves the chosen zero-based index.
+* @example
+* await defaultSelect("Trigger?", ["Auto on push", "Manual only"]);
+*/
+function defaultSelect(question, choices) {
+	return new Promise((resolve) => {
+		const readline = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		for (const [index, choice] of choices.entries()) console.log(`  ${index + 1}) ${choice}`);
+		readline.question(`${question} [1-${choices.length}] `, (answer) => {
+			readline.close();
+			const picked = Number.parseInt(answer.trim(), 10);
+			resolve(Number.isInteger(picked) && picked >= 1 && picked <= choices.length ? picked - 1 : 0);
+		});
+	});
+}
+/**
 * Default recursive directory watcher — wraps `node:fs.watch` with `{ recursive: true }`
 * and adapts its handle to {@link WatchHandle}. Tests inject a fake emitter so no real
 * FS watch is registered.
 *
 * @param dir - The directory to watch recursively.
-* @param onChange - Invoked on any change beneath `dir`.
+* @param onChange - Invoked on any change beneath `dir`, forwarding the changed path
+*   relative to `dir` when `node:fs.watch` reports it (`undefined` otherwise).
 * @returns A handle whose `close()` detaches the watcher.
 * @example
-* const handle = defaultWatch("content", () => rebuild());
+* const handle = defaultWatch("content", file => rebuild(file));
 */
 function defaultWatch(dir, onChange) {
-	const watcher = watch(dir, { recursive: true }, () => onChange());
+	const watcher = watch(dir, { recursive: true }, (_event, filename) => onChange(typeof filename === "string" ? filename : void 0));
 	return { 
 	/**
 	* Detach the underlying `node:fs.watch` listener.
@@ -7344,6 +8160,23 @@ close() {
 	} };
 }
 /**
+* Default file-mtime probe — `node:fs.statSync(path).mtimeMs`, returning `null` for a
+* missing path (so a deleted file still reads as a change). serve() compares this
+* across `fs.watch` events to drop the duplicate notifications macOS fires per save.
+*
+* @param filePath - The absolute path to stat.
+* @returns The modification time in epoch milliseconds, or `null` when absent.
+* @example
+* const mtime = defaultFileMtime("/abs/content/a.md");
+*/
+function defaultFileMtime(filePath) {
+	try {
+		return statSync(filePath).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+/**
 * Default LAN network-URL deriver — wraps {@link networkUrl} so the production seam
 * reads `node:os` interfaces while tests can inject a deterministic value.
 *
@@ -7371,11 +8204,13 @@ function createState$1(_ctx) {
 	return {
 		render: createPanelRenderer(),
 		confirm: defaultConfirm,
+		select: defaultSelect,
 		clock: Date.now,
 		watch: defaultWatch,
 		serveStatic: defaultServeStatic,
 		fileResponse: defaultFileResponse,
-		networkUrl: defaultNetworkUrl
+		networkUrl: defaultNetworkUrl,
+		fileMtime: defaultFileMtime
 	};
 }
 //#endregion
@@ -7502,6 +8337,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.
@@ -7518,10 +8369,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
@@ -7591,6 +8439,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.
@@ -7606,22 +8484,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`
@@ -8092,6 +8955,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",
@@ -8129,7 +8994,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 {
@@ -8848,6 +9713,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.
 *
@@ -8859,19 +9753,8 @@ function pullQuoteTransform(tree) {
 */
 function sectionDividerTransform(tree) {
 	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);
 	});
 }
 /**