@moku-labs/web 0.5.5 → 0.6.0

package/dist/index.cjs

@@ -35,9 +35,11 @@ let node_crypto = require("node:crypto");
 let feed = require("feed");
 let preact = require("preact");
 let preact_render_to_string = require("preact-render-to-string");
+let node_readline = require("node:readline");
+let node_os = require("node:os");
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
-const ERROR_PREFIX$14 = "[web]";
+const ERROR_PREFIX$15 = "[web]";
 /**
 * Creates the env plugin API surface mounted at `ctx.env`. Closes over
 * `ctx.state` ({@link EnvState}) and reads the frozen `resolved` / `publicMap`
@@ -81,7 +83,7 @@ function createEnvApi(ctx) {
 		*/
 		require(key) {
 			const value = resolved.get(key);
-			if (value === void 0) throw new Error(`${ERROR_PREFIX$14} env: required variable "${key}" is not defined.`);
+			if (value === void 0) throw new Error(`${ERROR_PREFIX$15} env: required variable "${key}" is not defined.`);
 			return value;
 		},
 		/**
@@ -148,7 +150,7 @@ function createEnvState() {
 /** Error message thrown by every frozen-map mutator. */
 const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
 /** Error prefix for all resolution-pipeline failures. */
-const ERROR_PREFIX$13 = "[web]";
+const ERROR_PREFIX$14 = "[web]";
 /**
 * Throws the canonical frozen-map error; installed as a map's `set`/`clear`/`delete`.
 *
@@ -199,8 +201,8 @@ function crossCheckPublicPrefix(config) {
 	const { schema, publicPrefix } = config;
 	for (const [key, spec] of Object.entries(schema)) {
 		const hasPrefix = key.startsWith(publicPrefix);
-		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$13} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
-		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$13} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
+		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX$14} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
+		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX$14} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
 	}
 }
 /**
@@ -251,7 +253,7 @@ function validateSchema(ctx) {
 	crossCheckPublicPrefix(config);
 	for (const [key, spec] of Object.entries(schema)) {
 		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
-		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$13} env: required variable "${key}" is not defined by any provider or default.`);
+		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX$14} env: required variable "${key}" is not defined by any provider or default.`);
 	}
 	for (const [key, spec] of Object.entries(schema)) {
 		const value = merged[key];
@@ -793,7 +795,7 @@ const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
-const ERROR_PREFIX$12 = "[web]";
+const ERROR_PREFIX$13 = "[web]";
 /**
 * Validates the resolved i18n config (fail-fast at `createApp`). Throws when
 * `locales` is empty or when `defaultLocale` is not a member of `locales`.
@@ -809,8 +811,8 @@ const ERROR_PREFIX$12 = "[web]";
 */
 function validateI18nConfig(ctx) {
 	const { locales, defaultLocale } = ctx.config;
-	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$12} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
-	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$12} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
+	if (locales.length === 0) throw new Error(`${ERROR_PREFIX$13} i18n.locales must contain at least one locale.\n  Set pluginConfigs.i18n.locales to a non-empty array, e.g. ["en"].`);
+	if (!locales.includes(defaultLocale)) throw new Error(`${ERROR_PREFIX$13} i18n.defaultLocale "${defaultLocale}" is not in i18n.locales [${locales.join(", ")}].\n  Set pluginConfigs.i18n.defaultLocale to one of the configured locales, or add "${defaultLocale}" to i18n.locales.`);
 }
 /**
 * Creates the i18n plugin API surface — locale registry accessors plus the
@@ -1335,6 +1337,23 @@ function calculateReadingTime(text) {
 function articleToUrl(locale, slug) {
 	return `/${locale}/${slug}/`;
 }
+/** Matches an `<img>` `src` that points at the co-located `images/` dir (relative or root-relative). */
+const RELATIVE_IMAGE_SRC = /(<img\b[^>]*?\bsrc=")(?:\.?\/)?images\//g;
+/**
+* Rewrite relative co-located image URLs (`./images/x.webp`) in rendered article HTML to the shared
+* absolute path the build copies them to (`/<slug>/images/...`), so they resolve from any locale page.
+*
+* @param html - The rendered article HTML.
+* @param slug - Article directory name.
+* @returns The HTML with image `src`s rewritten to absolute paths.
+* @example
+* ```ts
+* rewriteImageUrls('<img src="./images/a.webp">', "post"); // '<img src="/post/images/a.webp">'
+* ```
+*/
+function rewriteImageUrls(html, slug) {
+	return html.replaceAll(RELATIVE_IMAGE_SRC, `$1/${slug}/images/`);
+}
 /**
 * Build the canonical "article not found" error for {@link createContentApi.load}.
 * Centralised so the null-resolve path and the production draft-suppression path
@@ -1450,7 +1469,7 @@ async function readArticle(ctx, slug, fileLocale, outLocale, isFallback) {
 	ctx.state.dirtyPaths.delete(filePath);
 	const { frontmatter, body } = parseFrontmatter(raw, ctx.config);
 	const processor = ensureProcessor(ctx.state, ctx.config);
-	const html = String(await processor.process(body));
+	const html = rewriteImageUrls(String(await processor.process(body)), slug);
 	const { readingTime, wordCount } = calculateReadingTime(body);
 	return {
 		frontmatter,
@@ -1662,6 +1681,18 @@ function createContentApi(ctx) {
 		*/
 		articleToCard(article) {
 			return toCard(article);
+		},
+		/**
+		* The configured content source directory (e.g. `"./content"`).
+		*
+		* @returns The content directory path from config.
+		* @example
+		* ```ts
+		* api.contentDir(); // "./content"
+		* ```
+		*/
+		contentDir() {
+			return ctx.config.contentDir;
 		}
 	};
 }
@@ -1785,7 +1816,7 @@ const contentPlugin = createPlugin$1("content", {
 //#endregion
 //#region src/plugins/site/api.ts
 /** Error prefix for all site lifecycle/validation failures. */
-const ERROR_PREFIX$11 = "[web]";
+const ERROR_PREFIX$12 = "[web]";
 /**
 * Joins a relative path against an absolute base URL, normalizing the slash
 * boundary to exactly one "/". Returns the base unchanged for an empty or
@@ -1853,8 +1884,8 @@ function isAbsoluteUrl(value) {
 * ```
 */
 function validateSiteConfig(ctx) {
-	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$11} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
-	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$11} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
+	if (!isNonEmpty(ctx.config.name)) throw new Error(`${ERROR_PREFIX$12} site.name is required.\n  Provide a non-empty site name in pluginConfigs.site.name.`);
+	if (!isAbsoluteUrl(ctx.config.url)) throw new Error(`${ERROR_PREFIX$12} site.url must be a valid absolute URL (http/https), received ${JSON.stringify(ctx.config.url)}.\n  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".`);
 }
 /**
 * Creates the site plugin API surface — read-only accessors over frozen config
@@ -2044,7 +2075,7 @@ function matchRoute(compiled, pathname) {
 * `manifest`. Returns values/copies, never the raw `ctx.state` reference (spec/11 §2.4).
 */
 /** Error prefix for router API failures. */
-const ERROR_PREFIX$10 = "[web] router";
+const ERROR_PREFIX$11 = "[web] router";
 /**
 * Read the compiled matcher table, throwing if `onInit` has not run yet. This
 * `null` cannot occur in practice post-`onInit`; the guard documents the invariant.
@@ -2058,7 +2089,7 @@ const ERROR_PREFIX$10 = "[web] router";
 * ```
 */
 function readTable(state) {
-	if (state.table === null) throw new Error(`${ERROR_PREFIX$10}: matcher table accessed before onInit compiled it.`);
+	if (state.table === null) throw new Error(`${ERROR_PREFIX$11}: matcher table accessed before onInit compiled it.`);
 	return state.table;
 }
 /**
@@ -2112,7 +2143,7 @@ function toClientRoute(entry) {
 * api.match("/en/hello/");
 * ```
 */
-function createApi$4(ctx) {
+function createApi$5(ctx) {
 	const { state } = ctx;
 	return {
 		/**
@@ -2142,7 +2173,7 @@ function createApi$4(ctx) {
 		*/
 		toUrl(routeName, params) {
 			const entry = readTable(state).byName.get(routeName);
-			if (!entry) throw new Error(`${ERROR_PREFIX$10}: unknown route name "${routeName}".`);
+			if (!entry) throw new Error(`${ERROR_PREFIX$11}: unknown route name "${routeName}".`);
 			return entry.toUrl(params);
 		},
 		/**
@@ -2277,7 +2308,7 @@ function bySpecificity(a, b) {
 * only (`CompileInput`) — never the plugin ctx.
 */
 /** Shared `[web]` error prefix for router validation failures. */
-const ERROR_PREFIX$9 = "[web] router";
+const ERROR_PREFIX$10 = "[web] router";
 /**
 * Validate the route map (fail-fast in `onInit`). Throws with the `[web]` prefix
 * naming the offending route/pattern on any failure: empty map, a pattern not
@@ -2292,12 +2323,12 @@ const ERROR_PREFIX$9 = "[web] router";
 */
 function validateRoutes(routes) {
 	const names = Object.keys(routes);
-	if (names.length === 0) throw new Error(`${ERROR_PREFIX$9}: route map is empty — provide at least one route via pluginConfigs.router.routes.`);
+	if (names.length === 0) throw new Error(`${ERROR_PREFIX$10}: route map is empty — provide at least one route via pluginConfigs.router.routes.`);
 	for (const name of names) {
 		const pattern = routes[name]?.pattern ?? "";
-		if (!pattern.startsWith("/")) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern must start with "/" (got "${pattern}").`);
-		if ((pattern.match(/\{/g) ?? []).length !== (pattern.match(/\}/g) ?? []).length) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
-		if ((pattern.match(/\{lang:\?\}/g) ?? []).length > 1) throw new Error(`${ERROR_PREFIX$9}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
+		if (!pattern.startsWith("/")) throw new Error(`${ERROR_PREFIX$10}: route "${name}" pattern must start with "/" (got "${pattern}").`);
+		if ((pattern.match(/\{/g) ?? []).length !== (pattern.match(/\}/g) ?? []).length) throw new Error(`${ERROR_PREFIX$10}: route "${name}" pattern has unbalanced braces ("${pattern}").`);
+		if ((pattern.match(/\{lang:\?\}/g) ?? []).length > 1) throw new Error(`${ERROR_PREFIX$10}: route "${name}" pattern has more than one {lang:?} segment ("${pattern}").`);
 	}
 }
 /**
@@ -2702,7 +2733,7 @@ function defineRoutes(routes) {
 * const state = createState({ global: {}, config: { routes: {} } });
 * ```
 */
-function createState$4(_ctx) {
+function createState$5(_ctx) {
 	return {
 		table: null,
 		mode: _ctx.config.mode ?? "hybrid"
@@ -2738,8 +2769,8 @@ const routerPlugin = createPlugin$1("router", {
 		routes: {},
 		mode: "hybrid"
 	},
-	createState: createState$4,
-	api: createApi$4,
+	createState: createState$5,
+	api: createApi$5,
 	onInit(ctx) {
 		const i18n = ctx.require(i18nPlugin);
 		const baseUrl = ctx.require(sitePlugin).url();
@@ -3079,7 +3110,7 @@ function serializeHead(elements) {
 * it to a string. It holds no resource and caches no subscription.
 */
 /** Error prefix for head API invariant failures. */
-const ERROR_PREFIX$8 = "[head]";
+const ERROR_PREFIX$9 = "[head]";
 /**
 * Read the normalized defaults, asserting the post-`onInit` invariant (the slot is
 * `null` only before `onInit` assigns it, which cannot occur at render time).
@@ -3093,7 +3124,7 @@ const ERROR_PREFIX$8 = "[head]";
 * ```
 */
 function readDefaults(state) {
-	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$8}: defaults accessed before onInit normalized them.`);
+	if (state.defaults === null) throw new Error(`${ERROR_PREFIX$9}: defaults accessed before onInit normalized them.`);
 	return state.defaults;
 }
 /**
@@ -3109,7 +3140,7 @@ function readDefaults(state) {
 * api.render(route, data);
 * ```
 */
-function createApi$3(ctx) {
+function createApi$4(ctx) {
 	return { 
 	/**
 	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
@@ -3136,7 +3167,7 @@ render(route, data) {
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
-const ERROR_PREFIX$7 = "[head] config:";
+const ERROR_PREFIX$8 = "[head] config:";
 /** The allowed `twitterCard` literals (also the runtime guard set). */
 const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 /**
@@ -3149,7 +3180,7 @@ const VALID_TWITTER_CARDS = ["summary", "summary_large_image"];
 * createPlugin("head", { config: defaultConfig });
 * ```
 */
-const defaultConfig$2 = { twitterCard: "summary_large_image" };
+const defaultConfig$3 = { twitterCard: "summary_large_image" };
 /**
 * Structurally validate the resolved head config (no I/O). Throws a standard
 * `[head] config: …` error when `titleTemplate` is provided without the `%s`
@@ -3163,8 +3194,8 @@ const defaultConfig$2 = { twitterCard: "summary_large_image" };
 * ```
 */
 function validateHeadConfig(config) {
-	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$7} titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
-	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$7} twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
+	if (config.titleTemplate !== void 0 && !config.titleTemplate.includes("%s")) throw new Error(`${ERROR_PREFIX$8} titleTemplate must contain the "%s" token (replaced by the route title), received ${JSON.stringify(config.titleTemplate)}.`);
+	if (config.twitterCard !== void 0 && !VALID_TWITTER_CARDS.includes(config.twitterCard)) throw new Error(`${ERROR_PREFIX$8} twitterCard must be one of [${VALID_TWITTER_CARDS.join(", ")}], received ${JSON.stringify(config.twitterCard)}.`);
 }
 /**
 * Validate then build the frozen, normalized {@link HeadDefaults} snapshot read by
@@ -3232,7 +3263,7 @@ const headHelpers = {
 * const state = createState({ global: {}, config: {} });
 * ```
 */
-function createState$3(_ctx) {
+function createState$4(_ctx) {
 	return { defaults: null };
 }
 //#endregion
@@ -3267,9 +3298,9 @@ const headPlugin = createPlugin$1("head", {
 		routerPlugin
 	],
 	helpers: headHelpers,
-	config: defaultConfig$2,
-	createState: createState$3,
-	api: createApi$3,
+	config: defaultConfig$3,
+	createState: createState$4,
+	api: createApi$4,
 	onInit(ctx) {
 		ctx.state.defaults = normalizeHeadConfig(ctx.config);
 	}
@@ -3445,6 +3476,52 @@ function readCachedContent(ctx) {
 	return cached instanceof Map ? cached : /* @__PURE__ */ new Map();
 }
 //#endregion
+//#region src/plugins/build/phases/content-images.ts
+/**
+* @file build phase — content-images. Copies each article's co-located image directory
+* (`<contentDir>/<slug>/images/`) to a single shared output dir (`<outDir>/<slug>/images/`) reused by
+* every locale, matching the absolute `/<slug>/images/...` URLs the content renderer emits. Gated by
+* `config.images`.
+*/
+/** Conventional per-article image subdirectory name (alongside `<slug>/<locale>.md`). */
+const ARTICLE_IMAGE_DIR = "images";
+/**
+* Copy every article's co-located `images/` directory to `<outDir>/<slug>/images/`. No-op when
+* `config.images` is false or the content directory does not exist.
+*
+* @param ctx - Plugin context (provides `config`, `log`, `require`).
+* @returns The number of directories copied (one per article that has an `images/` dir).
+* @example
+* ```ts
+* const copied = await copyContentImages(ctx);
+* ```
+*/
+async function copyContentImages(ctx) {
+	if (!ctx.config.images) {
+		ctx.log.debug("build:content-images", { skipped: true });
+		return 0;
+	}
+	const contentDir = ctx.require(contentPlugin).contentDir();
+	if (!(0, node_fs.existsSync)(contentDir)) {
+		ctx.log.debug("build:content-images", {
+			skipped: true,
+			reason: "no content dir"
+		});
+		return 0;
+	}
+	const entries = await (0, node_fs_promises.readdir)(contentDir, { withFileTypes: true });
+	let copied = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const source = node_path$1.default.join(contentDir, entry.name, ARTICLE_IMAGE_DIR);
+		if (!(0, node_fs.existsSync)(source)) continue;
+		await (0, node_fs_promises.cp)(source, node_path$1.default.join(ctx.config.outDir, entry.name, ARTICLE_IMAGE_DIR), { recursive: true });
+		copied += 1;
+	}
+	ctx.log.debug("build:content-images", { copied });
+	return copied;
+}
+//#endregion
 //#region src/plugins/build/phases/feeds.ts
 /**
 * @file build phase 4 — feeds. Generates RSS/Atom/JSON from cached content plus
@@ -4690,6 +4767,7 @@ const PHASE_ORDER = [
 	"content",
 	"images",
 	"pages",
+	"content-images",
 	"feeds",
 	"sitemap",
 	"og-images",
@@ -4796,6 +4874,7 @@ async function runPipeline(ctx, options) {
 	await withPhase(phaseContext, "bundle", () => bundle(phaseContext));
 	await Promise.all([withPhase(phaseContext, "content", () => loadContent(phaseContext)), withPhase(phaseContext, "images", () => processImages(phaseContext))]);
 	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext));
+	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
 	await withPhase(phaseContext, "root-index", async () => {
 		if (pages.rootHtml !== null) await (0, node_fs_promises.writeFile)(node_path$1.default.join(outDir, "index.html"), pages.rootHtml, "utf8");
@@ -4814,7 +4893,7 @@ async function runPipeline(ctx, options) {
 * @file build plugin — API factory (run + phases), cross-plugin wiring, and onInit config validation.
 */
 /** Error prefix for build config/validation failures (spec/11 Part-3). */
-const ERROR_PREFIX$6 = "[web] build";
+const ERROR_PREFIX$7 = "[web] build";
 /** Recognized font file extensions for OG-image validation. */
 const FONT_EXTENSIONS = [
 	".ttf",
@@ -4822,7 +4901,7 @@ const FONT_EXTENSIONS = [
 	".woff"
 ];
 /** Typed default `build` config (R6: no inline `as`). `ogImage: false` disables OG generation. */
-const defaultConfig$1 = {
+const defaultConfig$2 = {
 	outDir: "./dist",
 	minify: true,
 	feeds: true,
@@ -4844,7 +4923,7 @@ const defaultConfig$1 = {
 * await api.run({ outDir: "./preview" });
 * ```
 */
-function createApi$2(ctx) {
+function createApi$3(ctx) {
 	return {
 		/**
 		* Run the full SSG pipeline and write the site to disk.
@@ -4885,8 +4964,8 @@ function createApi$2(ctx) {
 * ```
 */
 function validateFonts(og) {
-	if (typeof og.fontDir !== "string" || og.fontDir.length === 0 || !(0, node_fs.existsSync)(og.fontDir)) throw new Error(`${ERROR_PREFIX$6}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
-	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$6}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
+	if (typeof og.fontDir !== "string" || og.fontDir.length === 0 || !(0, node_fs.existsSync)(og.fontDir)) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
+	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
@@ -4899,11 +4978,11 @@ function validateFonts(og) {
 * validateConfig(ctx.config);
 * ```
 */
-function validateConfig$1(config) {
-	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$6}.outDir: must be a non-empty string.`);
-	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$6}.publicDir: must be a string when set.`);
-	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$6}.template: must be a string path when set.`);
-	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$6}.clientEntry: must be a string path when set.`);
+function validateConfig$2(config) {
+	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$7}.outDir: must be a non-empty string.`);
+	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$7}.publicDir: must be a string when set.`);
+	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$7}.template: must be a string path when set.`);
+	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$7}.clientEntry: must be a string path when set.`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion
@@ -4942,7 +5021,7 @@ function createEvents(register) {
 * const state = createState({ global: {}, config });
 * ```
 */
-function createState$2(ctx) {
+function createState$3(ctx) {
 	return {
 		config: ctx.config,
 		manifest: null,
@@ -4986,11 +5065,11 @@ const buildPlugin = createPlugin$1("build", {
 		routerPlugin,
 		headPlugin
 	],
-	config: defaultConfig$1,
-	createState: createState$2,
+	config: defaultConfig$2,
+	createState: createState$3,
 	events: createEvents,
-	api: createApi$2,
-	onInit: (ctx) => validateConfig$1(ctx.config)
+	api: createApi$3,
+	onInit: (ctx) => validateConfig$2(ctx.config)
 });
 //#endregion
 //#region src/plugins/deploy/wrangler.ts
@@ -5005,7 +5084,7 @@ const buildPlugin = createPlugin$1("build", {
 */
 const MOKU_WRANGLER_VERSION = "4.34.0";
 /** Error prefix for deploy runtime failures (spec/11 Part-3). */
-const ERROR_PREFIX$5 = "[web] deploy";
+const ERROR_PREFIX$6 = "[web] deploy";
 /** Mask substituted for a detected secret-like token. */
 const MASK = "***";
 /** Minimum token length eligible for entropy-gated scrubbing. */
@@ -5083,7 +5162,7 @@ function scrubSecrets(text, allowlist) {
 * guardBranch("preview/landing"); // "preview/landing"
 */
 function guardBranch(branch) {
-	if (!BRANCH_REGEX.test(branch) || branch.startsWith("-")) throw deployError("ERR_DEPLOY_INVALID_BRANCH", `${ERROR_PREFIX$5}: branch ${JSON.stringify(branch)} is invalid.\n  Branches must match /^[a-zA-Z0-9/_.-]+$/ so they cannot inject wrangler flags.`);
+	if (!BRANCH_REGEX.test(branch) || branch.startsWith("-")) throw deployError("ERR_DEPLOY_INVALID_BRANCH", `${ERROR_PREFIX$6}: branch ${JSON.stringify(branch)} is invalid.\n  Branches must match /^[a-zA-Z0-9/_.-]+$/ so they cannot inject wrangler flags.`);
 	return branch;
 }
 /**
@@ -5100,7 +5179,7 @@ function guardBranch(branch) {
 function assertWithinRoot(outDir, root) {
 	const resolved = node_path$1.default.isAbsolute(outDir) ? node_path$1.default.resolve(outDir) : node_path$1.default.resolve(root, outDir);
 	const rootResolved = node_path$1.default.resolve(root);
-	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path$1.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$5}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
+	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path$1.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$6}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
 	return resolved;
 }
 /**
@@ -5185,11 +5264,11 @@ function classifyWranglerError(exitCode, scrubbedStderr) {
 	const haystack = scrubbedStderr.toLowerCase();
 	for (const signature of ERROR_SIGNATURES) if (signature.match.some((needle) => haystack.includes(needle))) return {
 		code: signature.kind,
-		message: `${ERROR_PREFIX$5}: wrangler failed (exit ${exitCode}).\n  ${signature.advice}`
+		message: `${ERROR_PREFIX$6}: wrangler failed (exit ${exitCode}).\n  ${signature.advice}`
 	};
 	return {
 		code: "ERR_DEPLOY_WRANGLER_FAILED",
-		message: `${ERROR_PREFIX$5}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-500)}`
+		message: `${ERROR_PREFIX$6}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-500)}`
 	};
 }
 /**
@@ -5455,7 +5534,7 @@ async function reconcile(input) {
 * and short-circuiting on the first failure.
 */
 /** Error prefix for deploy preflight failures (spec/11 Part-3). */
-const ERROR_PREFIX$4 = "[web] deploy";
+const ERROR_PREFIX$5 = "[web] deploy";
 /** Cloudflare Pages free-tier file-count limit. */
 const FREE_TIER_FILE_LIMIT = 2e4;
 /** Cloudflare Pages paid-tier file-count limit (env override target). */
@@ -5531,15 +5610,15 @@ async function runPreflight(config, root, env = process.env) {
 	try {
 		await (0, node_fs_promises.stat)(wranglerPath);
 	} catch {
-		throw deployError("ERR_DEPLOY_NO_WRANGLER_CONFIG", `${ERROR_PREFIX$4}: wrangler.jsonc not found.\n  Run \`app.deploy.init()\` to scaffold it, then retry.`);
+		throw deployError("ERR_DEPLOY_NO_WRANGLER_CONFIG", `${ERROR_PREFIX$5}: wrangler.jsonc not found.\n  Run \`app.deploy.init()\` to scaffold it, then retry.`);
 	}
 	const stats = await inspectOutdir(node_path$1.default.isAbsolute(config.outDir) ? node_path$1.default.resolve(config.outDir) : node_path$1.default.resolve(root, config.outDir)).catch(() => {
-		throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(config.outDir)} is missing.\n  Run your build first, then retry.`);
+		throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$5}: outDir ${JSON.stringify(config.outDir)} is missing.\n  Run your build first, then retry.`);
 	});
-	if (stats.fileCount === 0) throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(config.outDir)} is empty — nothing to deploy.`);
+	if (stats.fileCount === 0) throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$5}: outDir ${JSON.stringify(config.outDir)} is empty — nothing to deploy.`);
 	const limit = resolveFileLimit(env);
-	if (stats.fileCount > limit) throw deployError("ERR_DEPLOY_TOO_MANY_FILES", `${ERROR_PREFIX$4}: outDir contains ${stats.fileCount} files; the limit is ${limit}.\n  Raise it with ${MAX_FILES_ENV} (paid tier) or reduce the output.`);
-	if (stats.oversizePath !== null) throw deployError("ERR_DEPLOY_FILE_TOO_LARGE", `${ERROR_PREFIX$4}: file ${JSON.stringify(stats.oversizePath)} exceeds the 25 MiB per-file limit.`);
+	if (stats.fileCount > limit) throw deployError("ERR_DEPLOY_TOO_MANY_FILES", `${ERROR_PREFIX$5}: outDir contains ${stats.fileCount} files; the limit is ${limit}.\n  Raise it with ${MAX_FILES_ENV} (paid tier) or reduce the output.`);
+	if (stats.oversizePath !== null) throw deployError("ERR_DEPLOY_FILE_TOO_LARGE", `${ERROR_PREFIX$5}: file ${JSON.stringify(stats.oversizePath)} exceeds the 25 MiB per-file limit.`);
 }
 //#endregion
 //#region src/plugins/deploy/slug.ts
@@ -5584,7 +5663,7 @@ function toSlug(name) {
 //#endregion
 //#region src/plugins/deploy/api.ts
 /** Error prefix for deploy config/validation failures (spec/11 Part-3). */
-const ERROR_PREFIX$3 = "[web] deploy";
+const ERROR_PREFIX$4 = "[web] deploy";
 /** `YYYY-MM-DD` validator for the compatibility date config field. */
 const COMPAT_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 /**
@@ -5597,12 +5676,12 @@ const COMPAT_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 * @example
 * createPlugin("deploy", { onInit: validateConfig });
 */
-function validateConfig(ctx) {
+function validateConfig$1(ctx) {
 	const { config } = ctx;
-	if (config.target !== "cloudflare-pages") throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: target ${JSON.stringify(config.target)} is unsupported.\n  Only "cloudflare-pages" is supported in this version.`);
-	if (typeof config.outDir !== "string" || config.outDir.length === 0) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: outDir must be a non-empty string.\n  Set pluginConfigs.deploy.outDir to your build output directory (e.g. "dist").`);
-	if (!Array.isArray(config.scrubAllowlist) || !config.scrubAllowlist.every((item) => typeof item === "string")) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: scrubAllowlist must be an array of strings.`);
-	if (config.compatibilityDate !== void 0 && !COMPAT_DATE_REGEX.test(config.compatibilityDate)) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$3}: compatibilityDate ${JSON.stringify(config.compatibilityDate)} must be in YYYY-MM-DD form.`);
+	if (config.target !== "cloudflare-pages") throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$4}: target ${JSON.stringify(config.target)} is unsupported.\n  Only "cloudflare-pages" is supported in this version.`);
+	if (typeof config.outDir !== "string" || config.outDir.length === 0) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$4}: outDir must be a non-empty string.\n  Set pluginConfigs.deploy.outDir to your build output directory (e.g. "dist").`);
+	if (!Array.isArray(config.scrubAllowlist) || !config.scrubAllowlist.every((item) => typeof item === "string")) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$4}: scrubAllowlist must be an array of strings.`);
+	if (config.compatibilityDate !== void 0 && !COMPAT_DATE_REGEX.test(config.compatibilityDate)) throw deployError("ERR_DEPLOY_CONFIG", `${ERROR_PREFIX$4}: compatibilityDate ${JSON.stringify(config.compatibilityDate)} must be in YYYY-MM-DD form.`);
 	ctx.require(sitePlugin);
 }
 /**
@@ -5618,7 +5697,7 @@ function validateConfig(ctx) {
 * const api = createApi(ctx);
 * await api.run({ branch: "preview/landing" });
 */
-function createApi$1(ctx) {
+function createApi$2(ctx) {
 	return {
 		/**
 		* Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
@@ -5709,7 +5788,7 @@ function createApi$1(ctx) {
 * createPlugin("deploy", { config: defaultConfig });
 * ```
 */
-const defaultConfig = {
+const defaultConfig$1 = {
 	target: "cloudflare-pages",
 	outDir: "dist",
 	productionBranch: "main",
@@ -5762,7 +5841,7 @@ const defaultSpawn = (cmd, options) => {
 * @example
 * const state = createState({ global: {}, config });
 */
-function createState$1(_ctx) {
+function createState$2(_ctx) {
 	return {
 		lastDeployment: null,
 		spawn: defaultSpawn
@@ -5796,146 +5875,1307 @@ function createState$1(_ctx) {
 * ```
 */
 const deployPlugin = createPlugin$1("deploy", {
-	config: defaultConfig,
+	config: defaultConfig$1,
 	depends: [sitePlugin],
-	createState: createState$1,
+	createState: createState$2,
 	events: deployEvents,
-	onInit: validateConfig,
-	api: createApi$1
+	onInit: validateConfig$1,
+	api: createApi$2
 });
 //#endregion
-//#region src/plugins/spa/api.ts
+//#region src/plugins/cli/errors.ts
+/** Error prefix for cli config/validation/runtime failures (spec/11 Part-3). */
+const ERROR_PREFIX$3 = "[web] cli";
 /**
-* Creates the spa plugin API surface (registration / control). All methods
-* delegate to the single shared kernel stored in `ctx.state.kernel`.
+* Construct a cli `Error` carrying a taxonomy `code` property. Centralizes the
+* `Object.assign(new Error(message), { code })` pattern so the `code` is always
+* preserved on the thrown value (the message is expected to already be prefixed).
 *
-* @param ctx - Plugin context exposing `state` (kernel) and `log`.
-* @returns The {@link SpaApi} surface mounted at `app.spa`.
+* @param code - The cli error `code` from the taxonomy.
+* @param message - The actionable error message.
+* @returns An `Error` whose `code` property is set.
 * @example
-* const api = createApi(ctx);
-* api.register(counter);
+* throw cliError("ERR_CLI_CONFIG", "[web] cli: port must be 1–65535.");
 */
-function createApi(ctx) {
+function cliError(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+/** The live-reload client snippet injected before `</body>` in served HTML. */
+const RELOAD_CLIENT = `<script>(()=>{try{const s=new EventSource("/__moku_reload");s.addEventListener("reload",()=>location.reload());}catch{}})();<\/script>`;
+/**
+* Inject the live-reload SSE client immediately before the closing `</body>` (or
+* append it when there is no `</body>`). Pure — unit-testable without a server.
+*
+* @param html - The page HTML to augment.
+* @returns The HTML with the reload client injected.
+* @example
+* injectReloadClient("<body>hi</body>"); // "<body>hi<script>…<\/script></body>"
+*/
+function injectReloadClient(html) {
+	const index = html.lastIndexOf("</body>");
+	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`.
+*
+* @param input - The rebuild dependencies + the changed file.
+* @param input.runBuild - Runs one build and resolves with its summary.
+* @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.
+* @returns Resolves once the rebuild settles (always — errors are routed, not thrown).
+* @example
+* await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md" });
+*/
+async function runOneRebuild(input) {
+	try {
+		const summary = await input.runBuild();
+		input.onReloaded({
+			file: input.file,
+			pageCount: summary.pageCount,
+			durationMs: summary.durationMs
+		});
+	} catch (error) {
+		input.onError(error);
+	}
+}
+/**
+* Create a {@link Rebuilder}. The latest changed file within the debounce window
+* wins; while a rebuild is in flight further notifications are dropped (the watcher
+* keeps firing, but only one build runs at a time, matching the blog `dev.ts`).
+*
+* @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.onReloaded - Called with the changed file + summary after a rebuild.
+* @param input.onError - Called when a rebuild throws.
+* @returns The debounced rebuild driver.
+* @example
+* createRebuilder({ debounceMs: 150, runBuild, onReloaded, onError });
+*/
+function createRebuilder(input) {
+	let timer;
+	let pendingFile = "";
+	let building = false;
+	/**
+	* Run the queued rebuild once (skips when one is already in flight), resetting the
+	* in-flight flag when it settles.
+	*
+	* @returns Resolves once the rebuild settles (errors are routed, never thrown).
+	* @example
+	* await fire();
+	*/
+	const fire = async () => {
+		timer = void 0;
+		if (building) return;
+		building = true;
+		await runOneRebuild({
+			runBuild: input.runBuild,
+			onReloaded: input.onReloaded,
+			onError: input.onError,
+			file: pendingFile
+		});
+		building = false;
+	};
 	return {
 		/**
-		* Register a component definition (last-registered-wins); warns on collision.
+		* Queue a rebuild for the changed file (debounced + coalesced).
 		*
-		* @param component - The component definition created via `createComponent`.
+		* @param file - The changed path that triggered the rebuild.
 		* @example
-		* app.spa.register(counter);
+		* rebuilder.schedule("a.md");
 		*/
-		register(component) {
-			if (ctx.state.registeredComponents.has(component.name)) ctx.log.warn("spa:component-collision", { name: component.name });
-			ctx.state.kernel?.register(component);
+		schedule(file) {
+			pendingFile = file;
+			if (timer) clearTimeout(timer);
+			timer = setTimeout(fire, input.debounceMs);
 		},
 		/**
-		* Programmatically navigate to a path (client runtime; no-op without a DOM).
+		* Cancel any pending (not-yet-fired) rebuild timer.
 		*
-		* @param path - Target path (pathname, optionally with search/hash).
 		* @example
-		* app.spa.navigate("/about");
+		* rebuilder.cancel();
 		*/
-		navigate(path) {
-			ctx.state.kernel?.processNav(path);
+		cancel() {
+			if (timer) clearTimeout(timer);
+			timer = void 0;
+		}
+	};
+}
+/**
+* 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.
+*
+* @param teardown - Cleanup to run on the first termination signal.
+* @returns A promise that resolves once a termination signal has been handled.
+* @example
+* await installSignalTeardown(() => server.stop());
+*/
+function installSignalTeardown(teardown) {
+	return new Promise((resolve) => {
+		/**
+		* Detach both signal listeners, run teardown, and resolve the wait (once).
+		*
+		* @example
+		* onSignal();
+		*/
+		const onSignal = () => {
+			process.off("SIGINT", onSignal);
+			process.off("SIGTERM", onSignal);
+			teardown();
+			resolve();
+		};
+		process.on("SIGINT", onSignal);
+		process.on("SIGTERM", onSignal);
+	});
+}
+/** The SSE comment line sent on connect to open the stream. */
+const SSE_OPEN = ": connected\n\n";
+/** The SSE frame pushed to reload a connected browser. */
+const SSE_RELOAD = "event: reload\ndata: 1\n\n";
+/**
+* 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).
+*
+* @returns The reload hub.
+* @example
+* const hub = createReloadHub();
+*/
+function createReloadHub() {
+	const encoder = new TextEncoder();
+	const clients = /* @__PURE__ */ new Set();
+	return {
+		/**
+		* Open one SSE connection, register its controller, and return the streaming
+		* `Response` (a connect comment is sent immediately to open the stream).
+		*
+		* @returns A `text/event-stream` response wired to this hub.
+		* @example
+		* return hub.connect();
+		*/
+		connect() {
+			let owned;
+			const stream = new ReadableStream({
+				/**
+				* Register the stream's controller and send the opening comment.
+				*
+				* @param controller - The new stream's controller.
+				* @example
+				* start(controller);
+				*/
+				start(controller) {
+					owned = controller;
+					clients.add(controller);
+					controller.enqueue(encoder.encode(SSE_OPEN));
+				},
+				/**
+				* Drop this client's controller when the browser disconnects.
+				*
+				* @example
+				* cancel();
+				*/
+				cancel() {
+					if (owned) clients.delete(owned);
+				}
+			});
+			return new Response(stream, { headers: {
+				"content-type": "text/event-stream",
+				"cache-control": "no-cache",
+				connection: "keep-alive"
+			} });
 		},
 		/**
-		* Read the current resolved URL.
+		* Push a `reload` frame to every connected client, dropping any closed ones.
 		*
-		* @returns The current pathname + search.
 		* @example
-		* app.spa.current();
+		* hub.reloadAll();
 		*/
-		current() {
-			return ctx.state.currentUrl;
+		reloadAll() {
+			for (const controller of clients) try {
+				controller.enqueue(encoder.encode(SSE_RELOAD));
+			} catch {
+				clients.delete(controller);
+			}
+		},
+		/**
+		* The number of currently-connected clients.
+		*
+		* @returns The live client count.
+		* @example
+		* hub.size();
+		*/
+		size() {
+			return clients.size;
 		}
 	};
 }
-//#endregion
-//#region src/plugins/spa/events.ts
 /**
-* Declares the spa plugin's events. Extracted from index.ts to keep the wiring
-* file under the line budget.
+* 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
+* `liveReload`), and falls through to the {@link resolveCleanUrl} static resolver for
+* everything else.
+*
+* @param ctx - The cli plugin context (provides `config` + `state.fileResponse`).
+* @param hub - The reload hub the SSE endpoint connects to.
+* @returns The `fetch` handler passed to the static server.
+* @example
+* const handler = createDevHandler(ctx, hub);
+*/
+function createDevHandler(ctx, hub) {
+	return async (request) => {
+		const pathname = decodeURIComponent(new URL(request.url).pathname);
+		if (pathname === "/__moku_reload") return hub.connect();
+		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" }
+			});
+		}
+		return response;
+	};
+}
+/**
+* Run the dev loop: an initial build, an in-process static server that injects the
+* live-reload client, a recursive watcher over `config.watchDirs`, and a debounced
+* rebuild that re-renders and pushes a browser reload. Resolves on SIGINT/SIGTERM,
+* which stops the server, closes the watchers, and cancels any pending rebuild.
 *
-* @param register - The event registration function supplied by the kernel.
-* @returns The map of spa event descriptors.
+* @param ctx - The cli plugin context (config, state seams, `require`).
+* @param port - The port to bind the dev server to.
+* @returns Resolves once the server has been torn down by a termination signal.
 * @example
-* const events = spaEvents(register);
+* await runDevServer(ctx, 4173);
 */
-function spaEvents(register) {
-	return {
-		"spa:navigate": register("A navigation has been intercepted and is starting."),
-		"spa:navigated": register("The swap completed and the new URL is active."),
-		"spa:component-mount": register("A component instance attached to an element."),
-		"spa:component-unmount": register("A component instance detached from an element.")
-	};
+async function runDevServer(ctx, port) {
+	await ctx.require(buildPlugin).run();
+	const hub = createReloadHub();
+	const server = ctx.state.serveStatic({
+		port,
+		fetch: createDevHandler(ctx, hub)
+	});
+	const rebuilder = createRebuilder({
+		debounceMs: ctx.config.debounceMs,
+		/**
+		* Re-run the SSG build for a rebuild.
+		*
+		* @returns The rebuild summary.
+		* @example
+		* await runBuild();
+		*/
+		runBuild() {
+			return ctx.require(buildPlugin).run();
+		},
+		/**
+		* 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.
+		* @example
+		* onReloaded({ file: "a.md", pageCount: 1, durationMs: 10 });
+		*/
+		onReloaded(info) {
+			ctx.state.render.reload(info);
+			hub.reloadAll();
+		},
+		/**
+		* Render a rebuild failure (the dev loop keeps running).
+		*
+		* @param error - The thrown rebuild error.
+		* @example
+		* onError(new Error("boom"));
+		*/
+		onError(error) {
+			ctx.state.render.error("rebuild failed", error);
+		}
+	});
+	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, () => rebuilder.schedule(dir)));
+	ctx.state.render.serverReady({
+		local: `http://localhost:${port}`,
+		network: ctx.state.networkUrl(port),
+		watching: ctx.config.watchDirs
+	});
+	return installSignalTeardown(() => {
+		rebuilder.cancel();
+		for (const watcher of watchers) watcher.close();
+		server.stop();
+	});
 }
 //#endregion
-//#region src/plugins/spa/types.ts
-var types_exports$8 = /* @__PURE__ */ require_convention.__exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
-/** Allowed hook names — single source of truth for fail-fast validation. */
-const COMPONENT_HOOK_NAMES = [
-	"onCreate",
-	"onMount",
-	"onNavStart",
-	"onNavEnd",
-	"onUnMount",
-	"onDestroy"
-];
-//#endregion
-//#region src/plugins/spa/components.ts
-/** Error prefix for spa fail-fast failures (spec/11 Part-3). */
-const ERROR_PREFIX$2 = "[web]";
-/** The set of legal hook names, frozen for O(1) membership checks. */
-const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
+//#region src/plugins/cli/preview.ts
 /**
-* Create a validated component definition. Validates hook names at registration
-* for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
-* each provided hook is a function.
+* @file cli plugin — static preview server for the built `dist/`. Exposes a PURE,
+* server-agnostic clean-URL resolver (`resolveCleanUrl`) — unit-tested without a
+* socket — plus `runPreviewServer`, which serves the resolved files via `Bun.serve`
+* the way Cloudflare Pages does (trailing slash → `index.html`, extensionless →
+* `<path>/index.html`, a miss → the nearest `404.html`). No reload injection.
+*/
+/**
+* Strip leading `../` segments (after `normalize`) so a request can never escape the
+* served root via path traversal.
 *
-* @param name - Unique component name.
-* @param hooks - Lifecycle hook implementations.
-* @returns A `ComponentDef` ready to `register`.
-* @throws {Error} If `name` is empty, any hook key is not in
-*   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+* @param pathname - The decoded request pathname.
+* @returns The traversal-safe relative path.
 * @example
-* const counter = createComponent("counter", {
-*   onMount({ el }) { el.textContent = "0"; }
-* });
+* safePath("../../etc/passwd"); // "etc/passwd"
 */
-function createComponent(name, hooks) {
-	if (name.trim() === "") throw new Error(`${ERROR_PREFIX$2} component name must be a non-empty string\n  → pass a unique name to createComponent("name", hooks)`);
-	for (const key of Object.keys(hooks)) {
-		if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${name}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
-		if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${name}" must be a function\n  → provide a function or omit the hook`);
-	}
-	return {
-		name,
-		hooks
-	};
+function safePath(pathname) {
+	return node_path$1.default.normalize(pathname).replace(/^(\.\.(?:[/\\]|$))+/, "");
 }
 /**
-* Extracts the page data payload from the inline `script#__DATA__` element.
-* Returns an empty object when the script is absent, empty, or invalid JSON.
+* The default {@link FileProbe} backed by `node:fs.statSync` — a single stat (no
+* exists+stat race) that swallows the ENOENT thrown for a missing path.
 *
-* @param doc - The document to read the data script from.
-* @returns The parsed page data, or `{}` when unavailable.
+* @param filePath - Candidate on-disk path.
+* @returns Whether it resolves to a regular file.
 * @example
-* const data = extractPageData(document);
+* statIsFile("/dist/index.html");
 */
-function extractPageData(doc) {
-	const text = doc.querySelector("script#__DATA__")?.textContent;
-	if (!text) return {};
+function statIsFile(filePath) {
 	try {
-		return JSON.parse(text);
+		return (0, node_fs.statSync)(filePath).isFile();
 	} catch {
-		return {};
+		return false;
 	}
 }
 /**
-* Builds a live component instance bound to an element.
+* Resolve a request pathname to a real file under `rootDir`, mirroring Cloudflare
+* Pages clean URLs. Pure and server-agnostic: it touches the filesystem only through
+* the injected {@link FileProbe}, so it is unit-tested without a server. A trailing
+* slash maps to `index.html`; an extensionless path tries the file then
+* `<path>/index.html`; a miss climbs toward the root for the nearest `404.html`
+* (served with status `404`).
 *
-* @param definition - The component definition.
-* @param element - The element the instance binds to.
+* @param rootDir - The absolute (or cwd-relative) build output directory.
+* @param pathname - The decoded request pathname (always starts with `/`).
+* @param isFile - File-existence probe (defaults to {@link statIsFile}).
+* @returns The resolved file + status (file `null` when not even a `404.html` exists).
+* @example
+* resolveCleanUrl("dist", "/about/", path => set.has(path));
+*/
+function resolveCleanUrl(rootDir, pathname, isFile = statIsFile) {
+	const relative = safePath(pathname);
+	const base = node_path$1.default.join(rootDir, relative);
+	const candidates = pathname.endsWith("/") ? [node_path$1.default.join(base, "index.html")] : [base, node_path$1.default.join(base, "index.html")];
+	for (const candidate of candidates) if (isFile(candidate)) return {
+		file: candidate,
+		status: 200
+	};
+	const segments = node_path$1.default.join(rootDir, relative).split(node_path$1.default.sep).filter(Boolean);
+	for (let depth = segments.length; depth >= 1; depth--) {
+		const candidate = node_path$1.default.join(segments.slice(0, depth).join(node_path$1.default.sep), "404.html");
+		if (isFile(candidate)) return {
+			file: candidate,
+			status: 404
+		};
+	}
+	const root = node_path$1.default.join(rootDir, "404.html");
+	return isFile(root) ? {
+		file: root,
+		status: 404
+	} : {
+		file: null,
+		status: 404
+	};
+}
+/**
+* Build the request handler for the preview server: resolves each request via
+* {@link resolveCleanUrl} and serves the file (no reload injection, mirroring prod).
+*
+* @param ctx - The cli plugin context (provides `config` + `state.fileResponse`).
+* @returns The `fetch` handler passed to the static server.
+* @example
+* const handler = createPreviewHandler(ctx);
+*/
+function createPreviewHandler(ctx) {
+	return (request) => {
+		const pathname = decodeURIComponent(new URL(request.url).pathname);
+		const resolved = resolveCleanUrl(ctx.config.outDir, pathname);
+		if (resolved.file === null) return new Response("Not Found", { status: 404 });
+		return ctx.state.fileResponse(resolved.file, resolved.status);
+	};
+}
+/**
+* Run the static preview server for the built `dist/`. Serves files resolved by
+* {@link resolveCleanUrl} via the injectable static-server seam — with no live-reload
+* injection, mirroring production. Renders the server-ready panel and resolves on
+* SIGINT/SIGTERM.
+*
+* @param ctx - The cli plugin context (provides `config` + `state` seams).
+* @param port - The port to bind to.
+* @returns Resolves once the server has been torn down by a termination signal.
+* @example
+* await runPreviewServer(ctx, 4173);
+*/
+function runPreviewServer(ctx, port) {
+	const server = ctx.state.serveStatic({
+		port,
+		fetch: createPreviewHandler(ctx)
+	});
+	ctx.state.render.serverReady({
+		local: `http://localhost:${port}`,
+		network: ctx.state.networkUrl(port)
+	});
+	return installSignalTeardown(() => server.stop());
+}
+//#endregion
+//#region src/plugins/cli/api.ts
+/**
+* @file cli plugin — API factory (build · serve · preview · deploy), the cli plugin
+* context type, and config-only `validateConfig`. The four closures are wiring-thin:
+* each renders the Panel header, then delegates to `build`/`deploy` (via `require`)
+* or to the server modules. Live build/deploy progress arrives through hooks (in
+* `index.ts`), so the methods' return values come from the awaited `run()` results.
+*/
+/** Lowest valid TCP port. */
+const MIN_PORT = 1;
+/** Highest valid TCP port. */
+const MAX_PORT = 65535;
+/**
+* Validate the resolved cli config during `onInit` (config-only — no resource
+* allocation, per spec/06 §2). Throws `ERR_CLI_CONFIG` (`[web] cli: …`) when `port`
+* is not an integer in 1–65535, `outDir`/`notFoundFile` are not non-empty strings,
+* `watchDirs` is not a non-empty string array, or `debounceMs` is negative.
+*
+* @param config - The resolved cli configuration to validate.
+* @throws {Error} `ERR_CLI_CONFIG` when any field is invalid.
+* @example
+* validateConfig({ outDir: "dist", port: 4173, watchDirs: ["content"], debounceMs: 150, notFoundFile: "404.html", liveReload: true });
+*/
+function validateConfig(config) {
+	if (!Number.isInteger(config.port) || config.port < MIN_PORT || config.port > MAX_PORT) throw cliError("ERR_CLI_CONFIG", `${ERROR_PREFIX$3}: port must be an integer in ${MIN_PORT}–${MAX_PORT}.\n  Set pluginConfigs.cli.port to a valid TCP port (e.g. 4173).`);
+	if (typeof config.outDir !== "string" || config.outDir.length === 0) throw cliError("ERR_CLI_CONFIG", `${ERROR_PREFIX$3}: outDir must be a non-empty string.\n  Set pluginConfigs.cli.outDir to your build output directory (e.g. "dist").`);
+	if (typeof config.notFoundFile !== "string" || config.notFoundFile.length === 0) throw cliError("ERR_CLI_CONFIG", `${ERROR_PREFIX$3}: notFoundFile must be a non-empty string.\n  Set pluginConfigs.cli.notFoundFile to the not-found page filename (e.g. "404.html").`);
+	if (!Array.isArray(config.watchDirs) || config.watchDirs.length === 0 || !config.watchDirs.every((dir) => typeof dir === "string" && dir.length > 0)) throw cliError("ERR_CLI_CONFIG", `${ERROR_PREFIX$3}: watchDirs must be a non-empty array of non-empty strings.\n  Set pluginConfigs.cli.watchDirs to the directories serve() should watch (e.g. ["content", "src"]).`);
+	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).`);
+}
+/**
+* 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
+* return value comes from the awaited `build.run()` / `deploy.run()` result.
+*
+* @param ctx - Plugin context (provides `require`, `state`, `config`).
+* @returns The {@link Api} surface mounted at `app.cli`.
+* @example
+* const api = createApi(ctx);
+* await api.build();
+*/
+function createApi$1(ctx) {
+	return {
+		/**
+		* Run the SSG build and (by default) assert the not-found page exists.
+		*
+		* @param options - Optional `assertNotFound` toggle (default `true`).
+		* @returns The build summary (`outDir`, `pageCount`, `durationMs`).
+		* @throws {Error} `ERR_CLI_NOT_FOUND` when the not-found page is missing and asserted.
+		* @example
+		* await api.build();
+		*/
+		async build(options = {}) {
+			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.`);
+			}
+			return result;
+		},
+		/**
+		* Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
+		* `watchDirs`, debounced rebuild + reload. Resolves on SIGINT/SIGTERM.
+		*
+		* @param options - Optional port override (defaults to `config.port`).
+		* @returns Resolves once the server has been torn down.
+		* @example
+		* await api.serve({ port: 3000 });
+		*/
+		serve(options = {}) {
+			const { port = ctx.config.port } = options;
+			ctx.state.render.header("serve");
+			return runDevServer(ctx, port);
+		},
+		/**
+		* Static preview of the built `dist/` with CF-Pages clean-URL resolution.
+		*
+		* @param options - Optional port override (defaults to `config.port`).
+		* @returns Resolves once the server has been torn down.
+		* @example
+		* await api.preview();
+		*/
+		preview(options = {}) {
+			const { port = ctx.config.port } = options;
+			ctx.state.render.header("preview");
+			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" }`.
+		*
+		* @param options - Optional branch override and `yes` flag.
+		* @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+		* @example
+		* await api.deploy({ branch: "preview/x", yes: true });
+		*/
+		async deploy(options = {}) {
+			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");
+			return {
+				deployed: true,
+				...await ctx.require(deployPlugin).run(branch === void 0 ? {} : { branch })
+			};
+		}
+	};
+}
+//#endregion
+//#region src/plugins/cli/defaults.ts
+/**
+* Default cli configuration. Consumers override individual fields via
+* `pluginConfigs.cli`. Declared as a typed const (no inline `as` assertion).
+*
+* @example
+* ```ts
+* createPlugin("cli", { config: defaultConfig });
+* ```
+*/
+const defaultConfig = {
+	outDir: "dist",
+	port: 4173,
+	watchDirs: ["content", "src"],
+	debounceMs: 150,
+	notFoundFile: "404.html",
+	liveReload: true
+};
+//#endregion
+//#region src/plugins/cli/network.ts
+/**
+* @file cli plugin — LAN network-URL derivation. Picks the first non-internal IPv4
+* from `node:os` `networkInterfaces()` to render the "Network" URL in the
+* server-ready panel. The interface source is injectable so it is unit-testable.
+*/
+/**
+* Whether an interface entry is a usable, non-internal IPv4 address.
+*
+* @param entry - One interface address entry.
+* @returns `true` when it is an external IPv4 address.
+* @example
+* isExternalIPv4({ address: "10.0.0.2", family: "IPv4", internal: false }); // true
+*/
+function isExternalIPv4(entry) {
+	return !entry.internal && (entry.family === "IPv4" || entry.family === 4);
+}
+/**
+* Pick the first non-internal IPv4 address from the interface source, or `null` when
+* none exists (offline / loopback-only).
+*
+* @param source - Interface source (defaults to `node:os` `networkInterfaces`).
+* @returns The first external IPv4 address string, or `null`.
+* @example
+* const ip = lanAddress();
+*/
+function lanAddress(source = node_os.networkInterfaces) {
+	for (const entries of Object.values(source())) for (const entry of entries ?? []) if (isExternalIPv4(entry)) return entry.address;
+	return null;
+}
+/**
+* Build the LAN URL (`http://<ip>:<port>`) for the server-ready panel, or `null`
+* when no non-internal IPv4 is available.
+*
+* @param port - The port the server is bound to.
+* @param source - Interface source (defaults to `node:os` `networkInterfaces`).
+* @returns The `http://<ip>:<port>` URL, or `null` when offline.
+* @example
+* networkUrl(4173); // "http://192.168.1.10:4173" or null
+*/
+function networkUrl(port, source = node_os.networkInterfaces) {
+	const ip = lanAddress(source);
+	return ip === null ? null : `http://${ip}:${port}`;
+}
+//#endregion
+//#region src/plugins/cli/render/ansi.ts
+/**
+* @file cli plugin — TTY/NO_COLOR-aware ANSI color + box-drawing helpers shared by
+* the Panel renderer. Modeled on the legacy `scripts/_log.ts`: color and box glyphs
+* are emitted only on a real TTY with `NO_COLOR` unset; otherwise plain ASCII so
+* CI logs and pipes stay readable.
+*/
+/** The ANSI escape byte (ESC, `0x1b`), built so no literal control char is in source. */
+const ESC = String.fromCodePoint(27);
+/** ANSI SGR codes used by the Panel renderer (each prefixed with the ESC byte). */
+const ANSI = {
+	reset: `${ESC}[0m`,
+	bold: `${ESC}[1m`,
+	dim: `${ESC}[2m`,
+	red: `${ESC}[31m`,
+	green: `${ESC}[32m`,
+	yellow: `${ESC}[33m`,
+	blue: `${ESC}[34m`,
+	magenta: `${ESC}[35m`,
+	cyan: `${ESC}[36m`,
+	gray: `${ESC}[90m`
+};
+/** Unicode rounded box glyphs used when output is a color-capable TTY. */
+const UNICODE_BOX = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│"
+};
+/** ASCII box glyphs used when output is piped/CI (plain mode). */
+const ASCII_BOX = {
+	topLeft: "+",
+	topRight: "+",
+	bottomLeft: "+",
+	bottomRight: "+",
+	horizontal: "-",
+	vertical: "|"
+};
+/**
+* Matches every ANSI SGR escape sequence (used to measure visible width). Built from
+* the {@link ESC} byte so no literal control character appears in the source regex.
+*/
+const ANSI_PATTERN = new RegExp(String.raw`${ESC}\[[0-9;]*m`, "g");
+/**
+* Whether ANSI color/box glyphs should be emitted: a TTY stream with `NO_COLOR`
+* unset. Reads `process.stdout.isTTY` and `process.env.NO_COLOR` by default so the
+* renderer auto-degrades in CI and pipes, exactly like the legacy logger.
+*
+* @param stream - Stream to probe for `isTTY` (defaults to `process.stdout`).
+* @param noColor - The `NO_COLOR` value (defaults to `process.env.NO_COLOR`).
+* @returns `true` when color should be used.
+* @example
+* supportsColor(); // true in an interactive terminal
+*/
+function supportsColor(stream = process.stdout, noColor = process.env.NO_COLOR) {
+	return stream.isTTY === true && noColor === void 0;
+}
+/**
+* Select the box glyph set for the given color mode (Unicode on a TTY, ASCII off it).
+*
+* @param color - Whether color/Unicode output is enabled.
+* @returns The matching {@link BoxGlyphs} set.
+* @example
+* const glyphs = boxGlyphs(supportsColor());
+*/
+function boxGlyphs(color) {
+	return color ? UNICODE_BOX : ASCII_BOX;
+}
+/**
+* The visible width of a string, ignoring any ANSI escape sequences it contains.
+*
+* @param text - The (possibly colorized) text to measure.
+* @returns The number of visible characters.
+* @example
+* visibleWidth(`${ANSI.red}hi${ANSI.reset}`); // 2
+*/
+function visibleWidth(text) {
+	return text.replaceAll(ANSI_PATTERN, "").length;
+}
+/**
+* Build a {@link Palette} bound to a fixed color mode. When `color` is `false` every
+* helper returns its input unchanged, so the same render code path produces plain
+* output in CI/pipes.
+*
+* @param color - Whether color is enabled (typically `supportsColor()`).
+* @returns The bound color palette.
+* @example
+* const palette = makePalette(supportsColor());
+* const line = palette.green("done");
+*/
+function makePalette(color) {
+	return {
+		enabled: color,
+		/**
+		* Wrap text in the given ANSI code (returns it unchanged when color is off).
+		*
+		* @param code - The ANSI SGR code to apply.
+		* @param text - The text to colorize.
+		* @returns The colorized (or unchanged) text.
+		* @example
+		* palette.paint(ANSI.green, "ok");
+		*/
+		paint(code, text) {
+			return color ? `${code}${text}${ANSI.reset}` : text;
+		},
+		/**
+		* Bold the given text (no-op in plain mode).
+		*
+		* @param text - The text to embolden.
+		* @returns The bold (or unchanged) text.
+		* @example
+		* palette.bold("title");
+		*/
+		bold(text) {
+			return this.paint(ANSI.bold, text);
+		},
+		/**
+		* Dim the given text (no-op in plain mode).
+		*
+		* @param text - The text to dim.
+		* @returns The dim (or unchanged) text.
+		* @example
+		* palette.dim("· 84ms");
+		*/
+		dim(text) {
+			return this.paint(ANSI.dim, text);
+		},
+		/**
+		* Color the given text green (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The green (or unchanged) text.
+		* @example
+		* palette.green("✓");
+		*/
+		green(text) {
+			return this.paint(ANSI.green, text);
+		},
+		/**
+		* Color the given text yellow (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The yellow (or unchanged) text.
+		* @example
+		* palette.yellow("~");
+		*/
+		yellow(text) {
+			return this.paint(ANSI.yellow, text);
+		},
+		/**
+		* Color the given text red (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The red (or unchanged) text.
+		* @example
+		* palette.red("✗");
+		*/
+		red(text) {
+			return this.paint(ANSI.red, text);
+		},
+		/**
+		* Color the given text cyan (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The cyan (or unchanged) text.
+		* @example
+		* palette.cyan("http://localhost:4173");
+		*/
+		cyan(text) {
+			return this.paint(ANSI.cyan, text);
+		}
+	};
+}
+/**
+* Frame a list of already-rendered content lines in a box, padding each line to the
+* width of the widest visible line. Uses Unicode borders when `color` is enabled and
+* ASCII otherwise. Visible width ignores embedded ANSI so colored lines align.
+*
+* @param lines - The content lines (may contain ANSI color codes).
+* @param color - Whether to use Unicode borders (and assume color-capable output).
+* @returns The boxed lines (top border, content rows, bottom border).
+* @example
+* box(["Local:   http://localhost:4173"], true);
+*/
+function box(lines, color) {
+	const glyphs = boxGlyphs(color);
+	const inner = Math.max(0, ...lines.map((line) => visibleWidth(line)));
+	const horizontal = glyphs.horizontal.repeat(inner + 2);
+	const top = `${glyphs.topLeft}${horizontal}${glyphs.topRight}`;
+	const bottom = `${glyphs.bottomLeft}${horizontal}${glyphs.bottomRight}`;
+	return [
+		top,
+		...lines.map((line) => {
+			const pad = " ".repeat(inner - visibleWidth(line));
+			return `${glyphs.vertical} ${line}${pad} ${glyphs.vertical}`;
+		}),
+		bottom
+	];
+}
+//#endregion
+//#region src/plugins/cli/render/panel.ts
+/** Per-command label shown in the header badge beside the logo. */
+const COMMAND_LABEL = {
+	build: "build",
+	serve: "serve · dev",
+	preview: "preview",
+	deploy: "deploy"
+};
+/**
+* Render one human-readable duration suffix (e.g. `· 84ms`).
+*
+* @param palette - The active color palette.
+* @param durationMs - Duration in milliseconds (omitted → empty string).
+* @returns The dim `· Nms` suffix, or `""` when no duration is given.
+* @example
+* durationSuffix(palette, 84); // " · 84ms" (dim)
+*/
+function durationSuffix(palette, durationMs) {
+	if (durationMs === void 0) return "";
+	return ` ${palette.dim(`· ${durationMs}ms`)}`;
+}
+/**
+* Create the Panel {@link CliRenderer}. Output is written through the injected sink
+* (default `console.log`/`console.error`) and colorized only when color is enabled,
+* so the identical render path yields box-drawn color panels on a TTY and plain
+* ASCII lines in CI/pipes.
+*
+* @param options - Optional sinks + a color override (see {@link PanelOptions}).
+* @returns The renderer mounted on `state.render` and driven by the API + hooks.
+* @example
+* const render = createPanelRenderer();
+* render.header("build");
+*/
+function createPanelRenderer(options = {}) {
+	const write = options.write ?? ((line) => console.log(line));
+	const writeError = options.writeError ?? ((line) => console.error(line));
+	const color = options.color ?? supportsColor();
+	const palette = makePalette(color);
+	/**
+	* Write each line of a multi-line block through the stdout sink.
+	*
+	* @param lines - The rendered lines to write in order.
+	* @example
+	* writeBlock(["a", "b"]);
+	*/
+	const writeBlock = (lines) => {
+		for (const line of lines) write(line);
+	};
+	return {
+		/**
+		* Render the boxed `MOKU WEB` logo + command label.
+		*
+		* @param command - The command being run, shown beside the logo.
+		* @example
+		* render.header("serve");
+		*/
+		header(command) {
+			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.
+		*
+		* @param phase - The `build:phase` payload.
+		* @example
+		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
+		*/
+		phase(phase) {
+			const done = phase.status === "done";
+			write(`  ${done ? palette.green("✓") : palette.dim("•")} ${done ? phase.phase : palette.dim(phase.phase)}${durationSuffix(palette, phase.durationMs)}`);
+		},
+		/**
+		* Render the BUILD summary block from a `build:complete` event.
+		*
+		* @param summary - The `build:complete` payload.
+		* @example
+		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
+		*/
+		built(summary) {
+			const pages = palette.bold(String(summary.pageCount));
+			writeBlock(box([
+				`${palette.green("✓")} ${palette.bold("BUILD")} complete`,
+				`${palette.dim("pages")}   ${pages}`,
+				`${palette.dim("time")}    ${summary.durationMs}ms`,
+				`${palette.dim("out")}     ${summary.outDir}/`
+			], color));
+		},
+		/**
+		* Render the bordered server-ready panel (Local / Network URLs + watched dirs).
+		*
+		* @param info - Local/Network URLs and optionally the watched directories.
+		* @example
+		* render.serverReady({ local: "http://localhost:4173", network: null });
+		*/
+		serverReady(info) {
+			const lines = [`${palette.green("➜")} ${palette.bold("Local")}    ${palette.cyan(info.local)}`, `${palette.green("➜")} ${palette.bold("Network")}  ${info.network ? palette.cyan(info.network) : palette.dim("unavailable")}`];
+			if (info.watching && info.watching.length > 0) lines.push(`${palette.dim("watching")} ${palette.dim(info.watching.join(", "))}`);
+			writeBlock(box(lines, color));
+		},
+		/**
+		* Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+		*
+		* @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`)}`);
+		},
+		/**
+		* Render the deploy result panel from a `deploy:complete` event.
+		*
+		* @param result - The `deploy:complete` payload.
+		* @example
+		* render.deployed({ url: "https://x.pages.dev", deploymentId: "id", branch: "main", durationMs: 1200 });
+		*/
+		deployed(result) {
+			writeBlock(box([
+				`${palette.green("✓")} ${palette.bold("DEPLOYED")}`,
+				`${palette.dim("url")}     ${palette.cyan(result.url)}`,
+				`${palette.dim("branch")}  ${result.branch}`,
+				`${palette.dim("id")}      ${result.deploymentId}`,
+				`${palette.dim("time")}    ${result.durationMs}ms`
+			], color));
+		},
+		/**
+		* Render a neutral informational line.
+		*
+		* @param message - The line to print.
+		* @example
+		* render.info("watching for changes…");
+		*/
+		info(message) {
+			write(`  ${palette.cyan("›")} ${message}`);
+		},
+		/**
+		* Render a warning line (to stderr).
+		*
+		* @param message - The warning to print.
+		* @example
+		* render.warn("deploy skipped");
+		*/
+		warn(message) {
+			writeError(`  ${palette.yellow("⚠")} ${message}`);
+		},
+		/**
+		* Render an error line (to stderr), optionally with a cause.
+		*
+		* @param message - The error summary to print.
+		* @param cause - Optional underlying error/value to print beneath the summary.
+		* @example
+		* render.error("build failed", err);
+		*/
+		error(message, cause) {
+			writeError(`  ${palette.red("✗")} ${message}`);
+			if (cause !== void 0) writeError(String(cause));
+		}
+	};
+}
+//#endregion
+//#region src/plugins/cli/state.ts
+/**
+* @file cli plugin — state factory. Wires the default injectable seams: the Panel
+* renderer, a stdin y/N `confirm`, the `Date.now` clock, a recursive `node:fs.watch`
+* wrapper, and the `Bun.serve`/`Bun.file` static-server seams (resolved lazily, like
+* deploy's `defaultSpawn`, so a non-Bun runtime fails coded rather than as a raw
+* `TypeError` and tests can inject fakes). Unit tests swap any of these.
+*/
+/**
+* Resolve the `Bun` runtime global, or `undefined` when not running under Bun.
+*
+* @returns The Bun runtime, or `undefined`.
+* @example
+* const bun = bunRuntime();
+*/
+function bunRuntime() {
+	return globalThis.Bun;
+}
+/**
+* Default static-server factory — resolves `Bun.serve` lazily at call time so the
+* server is only required when a long-running command actually starts one.
+*
+* @param options - Port + `fetch` handler (see {@link ServeStaticFunction}).
+* @returns The running server handle.
+* @throws {Error} When no Bun runtime is available to serve.
+* @example
+* defaultServeStatic({ port: 4173, fetch: () => new Response("ok") });
+*/
+const defaultServeStatic = (options) => {
+	const runtime = bunRuntime();
+	if (runtime === void 0) throw new Error("[web] cli: no Bun runtime available to start the server.\n  Run serve()/preview() under Bun, or inject state.serveStatic in tests.");
+	return runtime.serve(options);
+};
+/**
+* Default file-response factory — `new Response(Bun.file(path), { status })`. Resolves
+* `Bun.file` lazily so it is only required when a request is actually served.
+*
+* @param path - Absolute on-disk path to stream.
+* @param status - HTTP status for the response.
+* @returns The file `Response`.
+* @throws {Error} When no Bun runtime is available to read the file.
+* @example
+* defaultFileResponse("/dist/index.html", 200);
+*/
+const defaultFileResponse = (path, status) => {
+	const runtime = bunRuntime();
+	if (runtime === void 0) throw new Error("[web] cli: no Bun runtime available to read files.\n  Run serve()/preview() under Bun, or inject state.fileResponse in tests.");
+	return new Response(runtime.file(path), { status });
+};
+/**
+* Default stdin y/N prompt. Reads a single line from `process.stdin` via
+* `node:readline` and resolves `true` only on an explicit `y`/`yes` (default `No`).
+* Tests inject a canned answer so no real TTY interaction occurs.
+*
+* @param question - The yes/no question to display.
+* @returns Resolves `true` when the user answered yes.
+* @example
+* await defaultConfirm("Deploy dist/?");
+*/
+function defaultConfirm(question) {
+	return new Promise((resolve) => {
+		const readline = (0, node_readline.createInterface)({
+			input: process.stdin,
+			output: process.stdout
+		});
+		readline.question(`${question} [y/N] `, (answer) => {
+			readline.close();
+			resolve(/^y(es)?$/i.test(answer.trim()));
+		});
+	});
+}
+/**
+* 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`.
+* @returns A handle whose `close()` detaches the watcher.
+* @example
+* const handle = defaultWatch("content", () => rebuild());
+*/
+function defaultWatch(dir, onChange) {
+	const watcher = (0, node_fs.watch)(dir, { recursive: true }, () => onChange());
+	return { 
+	/**
+	* Detach the underlying `node:fs.watch` listener.
+	*
+	* @example
+	* handle.close();
+	*/
+close() {
+		watcher.close();
+	} };
+}
+/**
+* Default LAN network-URL deriver — wraps {@link networkUrl} so the production seam
+* reads `node:os` interfaces while tests can inject a deterministic value.
+*
+* @param port - The port the server is bound to.
+* @returns The `http://<ip>:<port>` URL, or `null` when offline.
+* @example
+* defaultNetworkUrl(4173);
+*/
+function defaultNetworkUrl(port) {
+	return networkUrl(port);
+}
+/**
+* Create the initial cli plugin state with the production seams wired. Every field is
+* an injectable seam (`render`, `confirm`, `clock`, `watch`, the server factories,
+* and `networkUrl`) so commands run under unit tests without real sockets/FS/TTY.
+*
+* @param _ctx - Minimal context with global + config (unused — state is static).
+* @param _ctx.global - Global plugin registry.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns The initial cli state.
+* @example
+* const state = createState({ global: {}, config });
+*/
+function createState$1(_ctx) {
+	return {
+		render: createPanelRenderer(),
+		confirm: defaultConfirm,
+		clock: Date.now,
+		watch: defaultWatch,
+		serveStatic: defaultServeStatic,
+		fileResponse: defaultFileResponse,
+		networkUrl: defaultNetworkUrl
+	};
+}
+//#endregion
+//#region src/plugins/cli/index.ts
+/**
+* @file cli — Complex plugin (wiring harness only). Developer CLI:
+* build · serve · preview · deploy, with the boxed Panel renderer.
+* Depends: build, deploy. Listens: build:phase, build:complete, deploy:complete.
+* @see README.md
+*/
+/**
+* cli plugin — the node-only developer CLI for `@moku-labs/web`. Mounts exactly four
+* methods at `app.cli` (`build`/`serve`/`preview`/`deploy`), each rendering through
+* the boxed Panel UI. Live build/deploy progress rides on hooks over the `build` and
+* `deploy` plugins' events; there is no argv parser and no `run()` dispatcher — the
+* consumer drives it from one thin script per command.
+*
+* @example Compose the CLI in a consumer app (node-only)
+* ```ts
+* import { buildPlugin, cliPlugin, createApp, deployPlugin } from "@moku-labs/web";
+*
+* const app = createApp({
+*   plugins: [buildPlugin, deployPlugin, cliPlugin],
+*   pluginConfigs: { cli: { outDir: "dist", port: 4173, watchDirs: ["content", "src"] } }
+* });
+* await app.start();
+* await app.cli.build();
+* ```
+*/
+const cliPlugin = createPlugin$1("cli", {
+	config: defaultConfig,
+	depends: [buildPlugin, deployPlugin],
+	createState: createState$1,
+	onInit: (ctx) => validateConfig(ctx.config),
+	hooks: (ctx) => ({
+		"build:phase": (p) => ctx.state.render.phase(p),
+		"build:complete": (p) => ctx.state.render.built(p),
+		"deploy:complete": (p) => ctx.state.render.deployed(p)
+	}),
+	api: createApi$1
+});
+//#endregion
+//#region src/plugins/spa/api.ts
+/**
+* Creates the spa plugin API surface (registration / control). All methods
+* delegate to the single shared kernel stored in `ctx.state.kernel`.
+*
+* @param ctx - Plugin context exposing `state` (kernel) and `log`.
+* @returns The {@link SpaApi} surface mounted at `app.spa`.
+* @example
+* const api = createApi(ctx);
+* api.register(counter);
+*/
+function createApi(ctx) {
+	return {
+		/**
+		* Register a component definition (last-registered-wins); warns on collision.
+		*
+		* @param component - The component definition created via `createComponent`.
+		* @example
+		* app.spa.register(counter);
+		*/
+		register(component) {
+			if (ctx.state.registeredComponents.has(component.name)) ctx.log.warn("spa:component-collision", { name: component.name });
+			ctx.state.kernel?.register(component);
+		},
+		/**
+		* Programmatically navigate to a path (client runtime; no-op without a DOM).
+		*
+		* @param path - Target path (pathname, optionally with search/hash).
+		* @example
+		* app.spa.navigate("/about");
+		*/
+		navigate(path) {
+			ctx.state.kernel?.processNav(path);
+		},
+		/**
+		* Read the current resolved URL.
+		*
+		* @returns The current pathname + search.
+		* @example
+		* app.spa.current();
+		*/
+		current() {
+			return ctx.state.currentUrl;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/spa/events.ts
+/**
+* Declares the spa plugin's events. Extracted from index.ts to keep the wiring
+* file under the line budget.
+*
+* @param register - The event registration function supplied by the kernel.
+* @returns The map of spa event descriptors.
+* @example
+* const events = spaEvents(register);
+*/
+function spaEvents(register) {
+	return {
+		"spa:navigate": register("A navigation has been intercepted and is starting."),
+		"spa:navigated": register("The swap completed and the new URL is active."),
+		"spa:component-mount": register("A component instance attached to an element."),
+		"spa:component-unmount": register("A component instance detached from an element.")
+	};
+}
+//#endregion
+//#region src/plugins/spa/types.ts
+var types_exports$9 = /* @__PURE__ */ require_convention.__exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
+/** Allowed hook names — single source of truth for fail-fast validation. */
+const COMPONENT_HOOK_NAMES = [
+	"onCreate",
+	"onMount",
+	"onNavStart",
+	"onNavEnd",
+	"onUnMount",
+	"onDestroy"
+];
+//#endregion
+//#region src/plugins/spa/components.ts
+/** Error prefix for spa fail-fast failures (spec/11 Part-3). */
+const ERROR_PREFIX$2 = "[web]";
+/** The set of legal hook names, frozen for O(1) membership checks. */
+const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
+/**
+* Create a validated component definition. Validates hook names at registration
+* for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+* each provided hook is a function.
+*
+* @param name - Unique component name.
+* @param hooks - Lifecycle hook implementations.
+* @returns A `ComponentDef` ready to `register`.
+* @throws {Error} If `name` is empty, any hook key is not in
+*   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+* @example
+* const counter = createComponent("counter", {
+*   onMount({ el }) { el.textContent = "0"; }
+* });
+*/
+function createComponent(name, hooks) {
+	if (name.trim() === "") throw new Error(`${ERROR_PREFIX$2} component name must be a non-empty string\n  → pass a unique name to createComponent("name", hooks)`);
+	for (const key of Object.keys(hooks)) {
+		if (!HOOK_NAME_SET.has(key)) throw new Error(`${ERROR_PREFIX$2} unknown component hook "${key}" on "${name}"\n  → valid hooks: ${COMPONENT_HOOK_NAMES.join(", ")}`);
+		if (typeof hooks[key] !== "function") throw new TypeError(`${ERROR_PREFIX$2} component hook "${key}" on "${name}" must be a function\n  → provide a function or omit the hook`);
+	}
+	return {
+		name,
+		hooks
+	};
+}
+/**
+* Extracts the page data payload from the inline `script#__DATA__` element.
+* Returns an empty object when the script is absent, empty, or invalid JSON.
+*
+* @param doc - The document to read the data script from.
+* @returns The parsed page data, or `{}` when unavailable.
+* @example
+* const data = extractPageData(document);
+*/
+function extractPageData(doc) {
+	const text = doc.querySelector("script#__DATA__")?.textContent;
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return {};
+	}
+}
+/**
+* Builds a live component instance bound to an element.
+*
+* @param definition - The component definition.
+* @param element - The element the instance binds to.
 * @param persistent - Whether the instance survives navigation.
 * @returns The constructed (not-yet-mounted) instance.
 * @example
@@ -6937,27 +8177,30 @@ const spaPlugin = createPlugin$1("spa", {
 //#region src/plugins/build/types.ts
 var types_exports = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/content/types.ts
+//#region src/plugins/cli/types.ts
 var types_exports$1 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/data/types.ts
+//#region src/plugins/content/types.ts
 var types_exports$2 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/deploy/types.ts
+//#region src/plugins/data/types.ts
 var types_exports$3 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/env/types.ts
+//#region src/plugins/deploy/types.ts
 var types_exports$4 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/head/types.ts
+//#region src/plugins/env/types.ts
 var types_exports$5 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/log/types.ts
+//#region src/plugins/head/types.ts
 var types_exports$6 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
-//#region src/plugins/router/types.ts
+//#region src/plugins/log/types.ts
 var types_exports$7 = /* @__PURE__ */ require_convention.__exportAll({});
 //#endregion
+//#region src/plugins/router/types.ts
+var types_exports$8 = /* @__PURE__ */ require_convention.__exportAll({});
+//#endregion
 //#region src/plugins/env/providers.ts
 /**
 * @file env plugin — built-in providers: dotenv, processEnv, cloudflareBindings.
@@ -7180,58 +8423,65 @@ Object.defineProperty(exports, "Build", {
 		return types_exports;
 	}
 });
-Object.defineProperty(exports, "Content", {
+Object.defineProperty(exports, "Cli", {
 	enumerable: true,
 	get: function() {
 		return types_exports$1;
 	}
 });
-Object.defineProperty(exports, "Data", {
+Object.defineProperty(exports, "Content", {
 	enumerable: true,
 	get: function() {
 		return types_exports$2;
 	}
 });
-Object.defineProperty(exports, "Deploy", {
+Object.defineProperty(exports, "Data", {
 	enumerable: true,
 	get: function() {
 		return types_exports$3;
 	}
 });
-Object.defineProperty(exports, "Env", {
+Object.defineProperty(exports, "Deploy", {
 	enumerable: true,
 	get: function() {
 		return types_exports$4;
 	}
 });
-Object.defineProperty(exports, "Head", {
+Object.defineProperty(exports, "Env", {
 	enumerable: true,
 	get: function() {
 		return types_exports$5;
 	}
 });
-Object.defineProperty(exports, "Log", {
+Object.defineProperty(exports, "Head", {
 	enumerable: true,
 	get: function() {
 		return types_exports$6;
 	}
 });
-Object.defineProperty(exports, "Router", {
+Object.defineProperty(exports, "Log", {
 	enumerable: true,
 	get: function() {
 		return types_exports$7;
 	}
 });
-Object.defineProperty(exports, "Spa", {
+Object.defineProperty(exports, "Router", {
 	enumerable: true,
 	get: function() {
 		return types_exports$8;
 	}
 });
+Object.defineProperty(exports, "Spa", {
+	enumerable: true,
+	get: function() {
+		return types_exports$9;
+	}
+});
 exports.browserEnv = browserEnv;
 exports.buildArticleHead = buildArticleHead;
 exports.buildPlugin = buildPlugin;
 exports.canonical = canonical;
+exports.cliPlugin = cliPlugin;
 exports.cloudflareBindings = cloudflareBindings;
 exports.contentPlugin = contentPlugin;
 exports.createApp = createApp;