@moku-labs/web 1.1.0 → 1.3.0

package/dist/index.mjs

@@ -1,14 +1,16 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
 import { n as relativeDataFile, t as dataSuffix } from "./convention-CepUwWmT.mjs";
 import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
-import { existsSync, readFileSync, readdirSync, statSync, watch } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Feed } from "feed";
 import { h } from "preact";
 import { renderToString } from "preact-render-to-string";
+import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 import { networkInterfaces } from "node:os";
 import matter from "gray-matter";
 import rehypeShiki from "@shikijs/rehype";
@@ -1280,18 +1282,24 @@ function isPublished(article, isProduction) {
 * locale collection: existing files only, drafts dropped in production, sorted
 * date-descending. The single load+filter+sort step behind {@link createContentApi.loadAll}.
 *
+* When a `cached` map is supplied (incremental dev rebuild), a slug already present in it
+* is reused as-is (skipping the re-read + Markdown/Shiki re-render); only slugs absent
+* from it — the ones a preceding `invalidate()` dropped, plus any never-loaded — are
+* resolved fresh. With no `cached` map every slug is resolved (the full load).
+*
 * @param ctx - Kernel-free domain context (provider + i18n helpers + stage).
 * @param slugs - Every known article slug from the provider.
 * @param locale - The locale to resolve and collect.
+* @param cached - Optional per-locale article cache to reuse for unchanged slugs.
 * @returns The published (date-descending) articles for this locale.
 * @example
 * ```ts
 * const present = await loadAndFilterArticles(ctx, slugs, "en");
 * ```
 */
-async function loadAndFilterArticles(ctx, slugs, locale) {
+async function loadAndFilterArticles(ctx, slugs, locale, cached) {
 	const isProduction = ctx.global.stage === "production";
-	return (await Promise.all(slugs.map((slug) => resolveArticle(ctx, slug, locale)))).filter((article) => article !== null).filter((article) => isPublished(article, isProduction)).toSorted(byDateDescending);
+	return (await Promise.all(slugs.map((slug) => cached?.get(slug) ?? resolveArticle(ctx, slug, locale)))).filter((article) => article !== null).filter((article) => isPublished(article, isProduction)).toSorted(byDateDescending);
 }
 /**
 * Derive the article slug from a source file path — the parent directory name
@@ -1328,19 +1336,26 @@ function createContentApi(ctx) {
 		* Load every article across every active locale (locale fallback, production
 		* draft exclusion, date sort, `contentId` after sort), cache them, emit `content:ready`.
 		*
+		* With `{ reuse: true }` (dev incremental rebuild) cached articles are reused for
+		* every slug a preceding `invalidate()` did not drop, so only the dirty articles
+		* re-read + re-run the Markdown/Shiki pipeline; the `contentId` ordinals are still
+		* recomputed across the FULL sorted set, so ids + order match a full load.
+		*
+		* @param options - Optional load behaviour (`reuse`); omit for a full load.
 		* @returns A locale-keyed map of date-descending articles.
 		* @example
 		* ```ts
 		* const byLocale = await api.loadAll();
 		* ```
 		*/
-		async loadAll() {
+		async loadAll(options) {
+			const reuse = options?.reuse === true;
 			const slugs = await ctx.provider.slugs();
 			const locales = ctx.locales();
 			const result = /* @__PURE__ */ new Map();
 			let total = 0;
 			for (const locale of locales) {
-				const present = await loadAndFilterArticles(ctx, slugs, locale);
+				const present = await loadAndFilterArticles(ctx, slugs, locale, reuse ? ctx.state.articles.get(locale) : void 0);
 				const cache = /* @__PURE__ */ new Map();
 				let index = 0;
 				for (const article of present) {
@@ -3341,7 +3356,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 /**
 * Bundles CSS and JS into the output directory via two separate runner passes
 * (dodging Bun's mixed-entrypoint segfault), honoring `config.minify`, and caches
-* the resulting hashed asset paths in `state.buildCache` for downstream phases.
+* the resulting hashed asset paths in `state.buildCache` for downstream phases. The
+* two passes run CONCURRENTLY (`Promise.all`) — they target disjoint hashed outputs
+* and distinct `buildCache` keys (`css`/`js`), so overlapping them ~halves bundle
+* wall-time with no shared-state hazard. The CSS pass is still dispatched first, so
+* the runner's invocation order stays css-then-js.
 *
 * @param ctx - Plugin context (provides `state`, `config`, `log`).
 * @param options - Optional dependency-injection seam (runner + entrypoints).
@@ -3354,10 +3373,10 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const assetsDir = path.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await runOne(ctx, runner, "css", cssEntrypoints, outDir, path.join(outDir, "assets"), minify);
-	await runOne(ctx, runner, "js", jsEntrypoints, outDir, path.join(outDir, "assets"), minify);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
 }
 //#endregion
 //#region src/plugins/build/phases/content.ts
@@ -3374,15 +3393,24 @@ const CONTENT_CACHE_KEY = "content";
 * pages/feeds/og-images phases. Performs NO Markdown parsing itself — the
 * content plugin owns rendering (god-plugin invariant).
 *
+* On a dev incremental rebuild (`options.changed` set) it first `invalidate()`s the
+* changed Markdown so `loadAll({ reuse: true })` re-reads + re-renders ONLY those
+* articles, reusing the cached HTML for the rest. With no options it does a full load.
+*
 * @param ctx - Plugin context (provides `require`, `state`, `log`).
+* @param options - Optional incremental hints; omit for a full load.
+* @param options.reuse - Reuse cached content for slugs not invalidated (dev incremental rebuild).
+* @param options.changed - The changed Markdown paths to invalidate before loading.
 * @returns The locale-keyed article map returned by the content plugin.
 * @example
 * ```ts
 * const byLocale = await loadContent(ctx);
 * ```
 */
-async function loadContent(ctx) {
-	const byLocale = await ctx.require(contentPlugin).loadAll();
+async function loadContent(ctx, options) {
+	const content = ctx.require(contentPlugin);
+	if (options?.changed && options.changed.length > 0) content.invalidate(options.changed);
+	const byLocale = await content.loadAll({ reuse: options?.reuse ?? false });
 	ctx.state.buildCache.set(CONTENT_CACHE_KEY, byLocale);
 	ctx.log.debug("build:content", { locales: byLocale.size });
 	return byLocale;
@@ -4736,6 +4764,71 @@ function renderBody(definition, routeContext) {
 	return renderToString(definition._handlers.layout ? definition._handlers.layout(layoutContext, vnode) : vnode);
 }
 /**
+* Hash a page's render inputs (its loaded data) for the render cache. `null` when the
+* data is not JSON-serializable — such a page is never cached and always re-renders.
+*
+* @param data - The route's loaded data (the only per-page input besides params/locale/code).
+* @returns The hex SHA-256 of the serialized data, or `null` when it cannot be serialized.
+* @example
+* ```ts
+* hashData({ title: "Hi" }); // "9f8e…"
+* ```
+*/
+function hashData(data) {
+	try {
+		const serialized = JSON.stringify(data) ?? "";
+		return createHash("sha256").update(serialized).digest("hex");
+	} catch {
+		return null;
+	}
+}
+/**
+* The render-cache key for one page instance: name + params + locale (the stable identity
+* that, together with the data hash, determines its body). NUL-joined so no value collides.
+*
+* @param instance - The page instance.
+* @returns The cache key string.
+* @example
+* ```ts
+* renderCacheKey(instance); // "article{\"slug\":\"x\"}en"
+* ```
+*/
+function renderCacheKey(instance) {
+	return `${instance.name}${JSON.stringify(instance.params)}${instance.locale}`;
+}
+/**
+* Render one page's body, reusing the cached body when this page's data is unchanged.
+* The body is the synchronous, dominant-cost step ({@link renderBody}); an incremental
+* dev rebuild (`reuse`, code unchanged) skips it for every page whose data hash matches
+* the cache, and a changed page (or a non-`reuse` run) renders + refreshes the cache.
+*
+* @param ctx - Plugin context (provides the cross-run `state.renderCache`).
+* @param instance - The page instance being rendered.
+* @param routeContext - The route context passed to `.render()`/`.layout()`.
+* @param data - The route's loaded data (hashed to detect a change).
+* @param reuse - Whether this run may reuse a cached body (incremental, no code change).
+* @returns The SSR-rendered body HTML.
+* @example
+* ```ts
+* const body = renderBodyCached(ctx, instance, routeContext, data, true);
+* ```
+*/
+function renderBodyCached(ctx, instance, routeContext, data, reuse) {
+	const cache = ctx.state.renderCache;
+	const key = renderCacheKey(instance);
+	const hash = hashData(data);
+	if (reuse && hash !== null) {
+		const hit = cache.get(key);
+		if (hit?.dataHash === hash) return hit.body;
+	}
+	const body = renderBody(instance.definition, routeContext);
+	if (hash !== null) cache.set(key, {
+		dataHash: hash,
+		body
+	});
+	return body;
+}
+/**
 * Write a rendered page document to its on-disk path. The path comes from the
 * compiled `TypedRoute.toFile(params)` (honoring any route-level `.toFile()`
 * override), resolved under the build `outDir`; parent directories are created first.
@@ -4764,13 +4857,14 @@ async function writeDocument(outDir, entry, params, html) {
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `has`).
 * @param instance - The concrete page instance to render.
 * @param shell - Per-build wiring shared across instances (asset tags + template).
+* @param reuse - Whether this run may reuse a cached body (incremental, no code change).
 * @returns The instance's URL, rendered HTML, loaded data, and client-nav flag.
 * @example
 * ```ts
-* await renderInstance(ctx, instance, { assets: "", template: null });
+* await renderInstance(ctx, instance, { assets: "", template: null }, false);
 * ```
 */
-async function renderInstance(ctx, instance, shell) {
+async function renderInstance(ctx, instance, shell, reuse) {
 	const { definition, entry, params, locale } = instance;
 	const router = ctx.require(routerPlugin);
 	const data = await loadRouteData(definition, params, locale, ctx);
@@ -4783,7 +4877,7 @@ async function renderInstance(ctx, instance, shell) {
 	};
 	const parts = {
 		head: composeHeadHtml(ctx, instance, url, routeContext, data),
-		body: renderBody(definition, routeContext),
+		body: renderBodyCached(ctx, instance, routeContext, data, reuse),
 		assets: shell.assets,
 		locale
 	};
@@ -4877,27 +4971,77 @@ function findRootHtml(rendered) {
 	return rendered.find((page) => page.url === "/" || page.url === "")?.html ?? null;
 }
 /**
+* Pages rendered concurrently per batch. Kept small so the macrotask yield between
+* batches fires frequently — a large batch renders for seconds before yielding, which
+* leaves a watching dev server's spinner repainting only every few seconds (sluggish).
+* Smaller batches trade a little write-concurrency for a smooth, responsive spinner.
+*/
+const RENDER_BATCH_SIZE = 2;
+/**
+* Batch size for an incremental (`reuse`) rebuild. Most instances are cheap cache hits, so
+* a larger batch cuts the per-batch `setImmediate` round-trips (which would otherwise add
+* pure latency to an otherwise-fast rebuild) without starving the dev spinner.
+*/
+const INCREMENTAL_BATCH_SIZE = 32;
+/**
+* Render `items` through `worker` in bounded-size batches, yielding a macrotask
+* (`setImmediate`) between batches. Beyond bounding peak concurrency/memory for large
+* sites, the yield lets the single JS thread breathe: one un-yielded `Promise.all` over
+* hundreds of synchronous `renderToString` calls starves the event loop, which freezes a
+* watching dev server's progress spinner until the whole phase resolves. Output order is
+* preserved (batch order + `Promise.all` order within a batch).
+*
+* @template Item - The input item type.
+* @template Out - The rendered output type.
+* @param items - The items to render.
+* @param batchSize - Maximum items rendered concurrently per batch.
+* @param worker - Renders one item to its output.
+* @returns All rendered outputs in input order.
+* @example
+* ```ts
+* const pages = await renderInBatches(instances, 32, i => renderInstance(ctx, i, shell));
+* ```
+*/
+async function renderInBatches(items, batchSize, worker) {
+	const out = [];
+	for (let start = 0; start < items.length; start += batchSize) {
+		const batch = items.slice(start, start + batchSize);
+		out.push(...await Promise.all(batch.map((item) => worker(item))));
+		if (start + batchSize < items.length) await new Promise((resolve) => {
+			setImmediate(resolve);
+		});
+	}
+	return out;
+}
+/**
 * Renders every route in the manifest to `outDir/<path>/index.html`. Reads as a
-* pipeline: resolve deps → prepare the shared shell → expand instances → render all
-* concurrently (`Promise.all`, legal intra-plugin concurrency) → write data sidecars
-* (hybrid/spa) → capture the root page's HTML for the root-index phase.
+* pipeline: resolve deps → prepare the shared shell → expand instances → render in
+* bounded batches ({@link renderInBatches}) → write data sidecars (hybrid/spa) →
+* capture the root page's HTML for the root-index phase.
+*
+* On an incremental rebuild (`options.reuse`) the cross-run render cache is kept and each
+* unchanged-data page reuses its cached body; a full render clears the cache first so a
+* removed/renamed route's stale body never lingers.
 *
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `log`, `has`).
+* @param options - Optional incremental hint; omit for a full render.
+* @param options.reuse - Reuse cached page bodies for unchanged-data pages (dev incremental rebuild).
 * @returns The number of pages rendered and the captured default-page HTML.
 * @example
 * ```ts
 * const { pageCount, rootHtml } = await renderPages(ctx);
 * ```
 */
-async function renderPages(ctx) {
+async function renderPages(ctx, options) {
+	const reuse = options?.reuse === true;
 	const router = ctx.require(routerPlugin);
 	const manifest = router.manifest();
 	ctx.state.manifest = [...manifest];
 	const locales = ctx.require(i18nPlugin).locales();
 	const byPattern = makeEntryMap(router);
+	if (!reuse) ctx.state.renderCache.clear();
 	const shell = await prepareShell(ctx);
-	const instances = await expandAllInstances(manifest, locales, byPattern, ctx);
-	const rendered = await Promise.all(instances.map((instance) => renderInstance(ctx, instance, shell)));
+	const rendered = await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse));
 	await writeDataSidecars(ctx, rendered, router.mode());
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {
@@ -5105,6 +5249,40 @@ async function generateSitemap(ctx) {
 * @file build plugin — pipeline driver. Sequences the fixed multi-phase build,
 * emits `build:phase` boundaries, and runs intra-phase work via `Promise.all`.
 */
+/** Matches a Markdown source path (a content edit). */
+const MARKDOWN_PATH = /\.md$/;
+/** Matches a stylesheet path (a CSS edit — does not change rendered page bodies). */
+const STYLE_PATH = /\.css$/;
+/** Matches a code path (TS/JS/JSON — may change ANY page's render output). */
+const CODE_PATH = /\.(?:tsx?|jsx?|mjs|cjs|json)$/;
+/**
+* Derive the {@link ChangePlan} for a run from its changed-path set (see the type docs
+* for the rules).
+*
+* @param changed - Absolute/relative changed paths, or `undefined` for a full build.
+* @returns The reuse plan for this run.
+* @example
+* ```ts
+* const plan = planIncrementalRebuild(options?.changed);
+* ```
+*/
+function planIncrementalRebuild(changed) {
+	if (changed === void 0 || changed.length === 0) return {
+		contentChanged: [],
+		contentReuse: false,
+		renderReuse: false
+	};
+	if (!changed.every((file) => MARKDOWN_PATH.test(file) || STYLE_PATH.test(file) || CODE_PATH.test(file))) return {
+		contentChanged: [],
+		contentReuse: false,
+		renderReuse: false
+	};
+	return {
+		contentChanged: changed.filter((file) => MARKDOWN_PATH.test(file)),
+		contentReuse: true,
+		renderReuse: !changed.some((file) => CODE_PATH.test(file))
+	};
+}
 /**
 * The static ordered list of pipeline phase names.
 *
@@ -5218,8 +5396,7 @@ async function runOutputs(ctx) {
 * `build:phase` boundary per phase and `build:complete` once at the end.
 *
 * @param ctx - Plugin context (provides `require`, `emit`, `state`, `config`, `log`).
-* @param options - Optional run overrides.
-* @param options.outDir - Override the configured output directory for this run.
+* @param options - Optional per-run overrides ({@link RunOptions}).
 * @returns The build result (outDir, pageCount, durationMs).
 * @example
 * ```ts
@@ -5234,17 +5411,22 @@ async function runPipeline(ctx, options) {
 		...ctx,
 		config: {
 			...ctx.config,
-			outDir
+			outDir,
+			...options?.overrides
 		}
 	};
-	await rm(outDir, {
+	const plan = planIncrementalRebuild(options?.changed);
+	if (!options?.skipClean) await rm(outDir, {
 		recursive: true,
 		force: true
 	});
 	await mkdir(outDir, { recursive: true });
 	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 Promise.all([withPhase(phaseContext, "content", () => loadContent(phaseContext, {
+		reuse: plan.contentReuse,
+		changed: plan.contentChanged
+	})), withPhase(phaseContext, "images", () => processImages(phaseContext))]);
+	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext, { reuse: plan.renderReuse }));
 	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
 	await withPhase(phaseContext, "root-index", async () => {
@@ -5297,10 +5479,12 @@ const defaultConfig$2 = {
 function createApi$3(ctx) {
 	return {
 		/**
-		* Run the full SSG pipeline and write the site to disk.
+		* Run the full SSG pipeline and write the site to disk. With no options a full
+		* production build runs; dev callers pass `skipClean`/`overrides`/`changed` for a
+		* fast incremental rebuild (all gated behind opt-in fields — the default path is
+		* unchanged).
 		*
-		* @param options - Optional run overrides.
-		* @param options.outDir - Override the configured output directory for this run.
+		* @param options - Optional per-run overrides (outDir / skipClean / overrides / changed).
 		* @returns The build result (outDir, pageCount, durationMs).
 		* @example
 		* ```ts
@@ -5393,8 +5577,8 @@ function createEvents(register) {
 /**
 * Creates initial `build` plugin state: a frozen config snapshot plus empty
 * per-run caches (`manifest`, `buildCache`, `runId`) and the cross-run OG
-* content-hash cache. Holds caches and config only — no domain data is
-* duplicated here (pulled fresh via `ctx.require` each run).
+* content-hash + page-render caches. Holds caches and config only — no domain data
+* is duplicated here (pulled fresh via `ctx.require` each run).
 *
 * @param ctx - Minimal context with global and config.
 * @param ctx.global - Global plugin registry (unused; caches are config-driven).
@@ -5411,7 +5595,8 @@ function createState$3(ctx) {
 		manifest: null,
 		buildCache: /* @__PURE__ */ new Map(),
 		runId: null,
-		ogImageHashCache: /* @__PURE__ */ new Map()
+		ogImageHashCache: /* @__PURE__ */ new Map(),
+		renderCache: /* @__PURE__ */ new Map()
 	};
 }
 //#endregion
@@ -5635,12 +5820,37 @@ function buildWranglerArgs(input) {
 		branch
 	];
 }
+/**
+* Assemble the argv for `wrangler pages project create` (no shell). Guards the
+* production branch against flag injection; the slug is already a safe `toSlug` output.
+*
+* @param input - The resolved project-create inputs.
+* @param input.slug - Cloudflare project-name slug (`toSlug(site.name())`).
+* @param input.branch - Production branch (guarded by `/^[a-zA-Z0-9/_.-]+$/`).
+* @returns The wrangler argv array.
+* @throws {Error} `ERR_DEPLOY_INVALID_BRANCH` when the branch fails the guard.
+* @example
+* buildProjectCreateArgs({ slug: "my-site", branch: "main" });
+*/
+function buildProjectCreateArgs(input) {
+	const branch = guardBranch(input.branch);
+	return [
+		"bunx",
+		"wrangler",
+		"pages",
+		"project",
+		"create",
+		input.slug,
+		"--production-branch",
+		branch
+	];
+}
 /** Lowercased substring matchers for the wrangler error taxonomy. */
 const ERROR_SIGNATURES = [
 	{
 		match: ["could not find project", "project not found"],
 		kind: "ERR_DEPLOY_PROJECT_NOT_FOUND",
-		advice: "The Cloudflare Pages project does not exist. Run `app.deploy.init()` or create it in the dashboard, then retry."
+		advice: "The Cloudflare Pages project does not exist yet. Create it in the dashboard (Workers & Pages → Create → Pages) or with `bunx wrangler pages project create <name>`, then retry. (app.deploy.init() only scaffolds local config — it does not create the remote project.)"
 	},
 	{
 		match: [
@@ -6219,15 +6429,16 @@ function validateConfig$1(ctx) {
 * Run wrangler for the prepared argv and surface its scrubbed result, translating
 * a non-zero exit into the classified deploy error. The API token is read from env
 * here so it never crosses a logging boundary; only scrubbed output is returned.
+* Shared by `run()` (deploy) and `createProject()` (project create).
 *
 * @param ctx - Plugin context (provides `state.spawn`, `config`, `env`).
 * @param args - The fully-built, pre-validated wrangler argv.
 * @returns The wrangler `stdout` plus the scrubbed `stderr` to log on success.
 * @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
 * @example
-* const { stdout, scrubbedStderr } = await executeDeploy(ctx, args);
+* const { stdout, scrubbedStderr } = await executeWrangler(ctx, args);
 */
-async function executeDeploy(ctx, args) {
+async function executeWrangler(ctx, args) {
 	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
 	const { stdout, scrubbedStderr, exitCode } = await runWrangler({
 		spawn: ctx.state.spawn,
@@ -6299,7 +6510,7 @@ function createApi$2(ctx) {
 				root
 			});
 			const start = Date.now();
-			const { stdout, scrubbedStderr } = await executeDeploy(ctx, args);
+			const { stdout, scrubbedStderr } = await executeWrangler(ctx, args);
 			ctx.log.info(scrubbedStderr);
 			const result = buildDeployResult(stdout, branch, start);
 			ctx.state.lastDeployment = result;
@@ -6338,6 +6549,38 @@ function createApi$2(ctx) {
 				cwd: process.cwd(),
 				options
 			});
+		},
+		/**
+		* The Cloudflare Pages project name this app deploys to (`toSlug(site.name())`).
+		*
+		* @returns The project-name slug.
+		* @example
+		* api.projectName(); // "my-site"
+		*/
+		projectName() {
+			return toSlug(ctx.require(sitePlugin).name());
+		},
+		/**
+		* Create the remote Cloudflare Pages project via wrangler, so a first deploy has a
+		* target. Derives the slug from `site.name()` and the production branch from config.
+		*
+		* @returns The created project name + production branch.
+		* @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
+		* @example
+		* await api.createProject(); // { name: "my-site", branch: "main" }
+		*/
+		async createProject() {
+			const name = toSlug(ctx.require(sitePlugin).name());
+			const branch = ctx.config.productionBranch ?? "main";
+			const { scrubbedStderr } = await executeWrangler(ctx, buildProjectCreateArgs({
+				slug: name,
+				branch
+			}));
+			ctx.log.info(scrubbedStderr);
+			return {
+				name,
+				branch
+			};
 		}
 	};
 }
@@ -6449,13 +6692,14 @@ const deployPlugin = createPlugin$1("deploy", {
 //#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.
+* @file cli plugin — the guided deploy wizard (`cli.deploy({ guided: true })`, the default
+* for `bun run deploy`; the direct `--cli` path stays in `api.ts`). Walks a human through a
+* Cloudflare Pages deploy: checks prerequisites (wrangler config + the Cloudflare
+* credentials) with concrete fix guidance, offers to scaffold what is missing (a
+* `wrangler.jsonc`, and a placeholder `.env` for any missing credentials), 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). 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 = [
@@ -6470,21 +6714,56 @@ const ACCOUNT_HELP = [
 	"right-hand sidebar (also in the dashboard URL). Then make it available:",
 	"  export CLOUDFLARE_ACCOUNT_ID=…   or add it to .env."
 ].join("\n");
+/** Shown when a credential is in the raw environment but the app's env providers did not resolve it. */
+const PROVIDERS_HELP = [
+	"Found in your shell/.env but the app's env plugin did not resolve it — its providers",
+	"are not wired. Add the Node providers in createApp so the deploy can read it:",
+	"  pluginConfigs.env = { providers: [processEnv(), dotenv()] }   (import them from @moku-labs/web)."
+].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");
 /**
+* Build one credential prerequisite by reading the SAME source the deploy reads — the
+* resolved `ctx.env` table — so a ✓ guarantees `ctx.env.require(key)` will succeed. When
+* the value is present in the raw `process.env` but unresolved by the app's providers
+* (the silent "deploy can't see it" trap a bare `process.env` check would mark green),
+* the fix hint points at wiring the providers instead of re-adding the value.
+*
+* @param ctx - The cli plugin context (provides the resolved `ctx.env`).
+* @param key - The credential variable name.
+* @param label - The diagnostic line label.
+* @param missingHelp - The fix hint when the credential is genuinely absent everywhere.
+* @returns The credential prerequisite check.
+* @example
+* credentialPrereq(ctx, "CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_TOKEN is set", TOKEN_HELP);
+*/
+function credentialPrereq(ctx, key, label, missingHelp) {
+	if ((ctx.env.get(key) ?? "") !== "") return {
+		ok: true,
+		label,
+		detail: void 0,
+		scaffoldable: false
+	};
+	return {
+		ok: false,
+		label,
+		detail: (process.env[key] ?? "") !== "" ? PROVIDERS_HELP : missingHelp,
+		scaffoldable: false
+	};
+}
+/**
 * Evaluate the three deploy prerequisites against the current project: the Cloudflare
-* wrangler config exists, and both Cloudflare credentials are present in the environment.
+* wrangler config exists, and both Cloudflare credentials resolve through `ctx.env` (the
+* deploy's own source of truth — not a bare `process.env` read that can diverge from it).
 *
+* @param ctx - The cli plugin context (provides the resolved `ctx.env`).
 * @param cwd - The project root (where `wrangler.jsonc` lives).
 * @returns The ordered prerequisite checks.
 * @example
-* const prereqs = diagnose(process.cwd());
+* const prereqs = diagnose(ctx, process.cwd());
 */
-function diagnose(cwd) {
+function diagnose(ctx, 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,
@@ -6492,18 +6771,8 @@ function diagnose(cwd) {
 			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
-		}
+		credentialPrereq(ctx, "CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_TOKEN is set", TOKEN_HELP),
+		credentialPrereq(ctx, "CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_ACCOUNT_ID is set", ACCOUNT_HELP)
 	];
 }
 /**
@@ -6522,6 +6791,43 @@ async function offerScaffold(ctx, prereqs) {
 	await ctx.require(deployPlugin).init({});
 	ctx.state.render.check(true, "wrangler.jsonc scaffolded");
 }
+/** The Cloudflare credentials the deploy needs, with the comment written above each in a scaffolded `.env`. */
+const ENV_CREDENTIALS = [{
+	key: "CLOUDFLARE_API_TOKEN",
+	comment: "# Cloudflare API token — https://dash.cloudflare.com/profile/api-tokens (template: Cloudflare Pages — Edit)"
+}, {
+	key: "CLOUDFLARE_ACCOUNT_ID",
+	comment: "# Cloudflare account id — dashboard → Workers & Pages → right-hand sidebar"
+}];
+/**
+* Offer to scaffold a `.env` with placeholders for whichever Cloudflare credentials are
+* missing — created when absent, appended to (never clobbering a key already present)
+* when it exists. The placeholders are empty, so the deploy still hard-gates until the
+* user fills them in; this just removes the "where do I even put these?" friction.
+*
+* @param ctx - The cli plugin context.
+* @param cwd - The project root (where `.env` lives).
+* @returns Resolves once any accepted scaffold has been written.
+* @example
+* await offerEnvScaffold(ctx, process.cwd());
+*/
+async function offerEnvScaffold(ctx, cwd) {
+	const missing = ENV_CREDENTIALS.filter(({ key }) => (process.env[key] ?? "") === "");
+	if (missing.length === 0) return;
+	const envPath = path.join(cwd, ".env");
+	const exists = existsSync(envPath);
+	const verb = exists ? "Add placeholders for the missing secret(s) to" : "Create";
+	if (!await ctx.state.confirm(`${verb} .env?`)) return;
+	const lines = exists ? readFileSync(envPath, "utf8").split(/\r?\n/) : [];
+	const toAdd = missing.filter(({ key }) => !lines.some((line) => line.trimStart().startsWith(`${key}=`)));
+	if (toAdd.length === 0) {
+		ctx.state.render.info(".env already lists those keys — fill in their values, then re-run.");
+		return;
+	}
+	appendFileSync(envPath, `${exists ? "\n" : "# Cloudflare Pages deploy credentials — fill these in (keep .env gitignored).\n"}${toAdd.map(({ key, comment }) => `${comment}\n${key}=`).join("\n\n")}\n`);
+	const names = toAdd.map(({ key }) => key).join(", ");
+	ctx.state.render.check(true, `${exists ? "added placeholders to" : "created"} .env`, `fill in ${names}, then re-run \`bun run deploy\`.`);
+}
 /**
 * 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.
@@ -6564,8 +6870,139 @@ async function offerWorkflowSetup(ctx) {
 	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" }`.
+* Read the taxonomy `code` off a thrown value, when present. Deploy errors carry a
+* `code` (e.g. `ERR_DEPLOY_PROJECT_NOT_FOUND`) so the wizard can tailor the fix hint.
+*
+* @param error - The thrown value.
+* @returns The `code` string, or `undefined` when absent.
+* @example
+* codeOf(deployError("ERR_DEPLOY_AUTH", "…")); // "ERR_DEPLOY_AUTH"
+*/
+function codeOf(error) {
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const { code } = error;
+		return typeof code === "string" ? code : void 0;
+	}
+}
+/**
+* A copy-pasteable "create the project yourself" hint, shown when the user declines the
+* offer to auto-create. Spells out that the remote project is what's missing (init only
+* scaffolds local config).
+*
+* @param name - The Cloudflare Pages project name (the deploy slug).
+* @returns The multi-line hint (newline-separated; rendered indented under a `›`).
+* @example
+* ctx.state.render.info(projectNotFoundHint("my-site"));
+*/
+function projectNotFoundHint(name) {
+	return [
+		"how to fix: the Cloudflare Pages project does not exist yet — create it once, then",
+		"re-run `bun run deploy`. (app.deploy.init() only scaffolds local config; it does not",
+		"create the remote project.)",
+		`  • CLI:       bunx wrangler pages project create ${name} --production-branch main`,
+		"  • Dashboard: Cloudflare → Workers & Pages → Create → Pages"
+	].join("\n");
+}
+/**
+* An actionable, error-specific "how to fix" hint for a failed deploy (other than the
+* project-not-found case, which the wizard handles interactively), so the user never
+* lands on a raw stack trace.
+*
+* @param error - The thrown deploy error.
+* @returns The fix hint line.
+* @example
+* ctx.state.render.info(deployFailureHint(err));
+*/
+function deployFailureHint$1(error) {
+	const code = codeOf(error);
+	if (code === "ERR_DEPLOY_AUTH" || code === "ERR_DEPLOY_AUTH_EXPIRED") return "how to fix: refresh CLOUDFLARE_API_TOKEN (scope: Account › Cloudflare Pages › Edit), then re-run `bun run deploy`.";
+	if (code === "ERR_DEPLOY_NETWORK") return "how to fix: a network error reached Cloudflare — check connectivity, then re-run `bun run deploy`.";
+	return "how to fix: resolve the error above, then re-run `bun run deploy`.";
+}
+/**
+* Render a styled deploy failure (✗ + fix hint) and return the `"failed"` outcome, so a
+* caught error surfaces consistently instead of as a raw throw.
+*
+* @param ctx - The cli plugin context.
+* @param error - The thrown deploy error.
+* @returns The `"failed"` deploy outcome.
+* @example
+* return renderFailure(ctx, error);
+*/
+function renderFailure(ctx, error) {
+	ctx.state.render.error("deploy failed", error);
+	ctx.state.render.info(deployFailureHint$1(error));
+	return {
+		deployed: false,
+		reason: "failed"
+	};
+}
+/**
+* Deploy once via the deploy plugin and wrap the result as a successful outcome. Throws
+* the classified deploy error on failure (the caller decides how to surface it).
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override).
+* @returns The successful deploy outcome.
+* @throws {Error} With a `code` from the deploy error taxonomy on any failure.
+* @example
+* const outcome = await deployOnce(ctx, { branch: "main" });
+*/
+async function deployOnce(ctx, options) {
+	return {
+		deployed: true,
+		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
+	};
+}
+/**
+* Handle a project-not-found deploy failure interactively: ask (a confirmation step)
+* before creating a real Cloudflare resource, create the Pages project via the deploy
+* plugin, then retry the deploy once. A declined offer (or a create failure) returns the
+* `"failed"` outcome with an actionable hint — never a raw stack trace.
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override).
+* @param originalError - The project-not-found error from the first attempt.
+* @returns The deploy outcome (deployed after a successful create + retry, else failed).
+* @example
+* return createProjectThenRetry(ctx, options, error);
+*/
+async function createProjectThenRetry(ctx, options, originalError) {
+	const deploy = ctx.require(deployPlugin);
+	const name = deploy.projectName();
+	ctx.state.render.warn(`The Cloudflare Pages project "${name}" does not exist yet.`);
+	if (!await ctx.state.confirm(`Create the Cloudflare Pages project "${name}" now?`)) {
+		ctx.state.render.error("deploy failed", originalError);
+		ctx.state.render.info(projectNotFoundHint(name));
+		return {
+			deployed: false,
+			reason: "failed"
+		};
+	}
+	try {
+		const created = await deploy.createProject();
+		ctx.state.render.check(true, `created Cloudflare Pages project "${created.name}"`);
+	} catch (error) {
+		ctx.state.render.error("could not create the Pages project", error);
+		ctx.state.render.info(deployFailureHint$1(error));
+		return {
+			deployed: false,
+			reason: "failed"
+		};
+	}
+	ctx.state.render.info("project created — retrying the deploy…");
+	try {
+		return await deployOnce(ctx, options);
+	} catch (error) {
+		return renderFailure(ctx, error);
+	}
+}
+/**
+* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin. A
+* declined confirm returns `{ deployed: false, reason: "declined" }`. A project-not-found
+* failure offers to create the project (with a confirmation step) and retries; any other
+* runtime failure is surfaced as a styled error + fix hint, returning
+* `{ deployed: false, reason: "failed" }` — never a raw stack trace.
 *
 * @param ctx - The cli plugin context.
 * @param options - The deploy options (branch override + `yes`).
@@ -6582,10 +7019,12 @@ async function runDeployStep(ctx, options) {
 			reason: "declined"
 		};
 	}
-	return {
-		deployed: true,
-		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
-	};
+	try {
+		return await deployOnce(ctx, options);
+	} catch (error) {
+		if (codeOf(error) === "ERR_DEPLOY_PROJECT_NOT_FOUND") return createProjectThenRetry(ctx, options, error);
+		return renderFailure(ctx, error);
+	}
 }
 /**
 * Run the guided deploy wizard end to end: diagnose prerequisites (offering to scaffold
@@ -6603,9 +7042,10 @@ async function runDeployStep(ctx, options) {
 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);
+	for (const item of diagnose(ctx, cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
+	await offerScaffold(ctx, diagnose(ctx, cwd));
+	await offerEnvScaffold(ctx, cwd);
+	const blockers = diagnose(ctx, 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);
@@ -6622,7 +7062,7 @@ async function runDeployWizard(ctx, options) {
 	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);
+	if (!(outcome.deployed === false && outcome.reason === "failed")) await offerWorkflowSetup(ctx);
 	return outcome;
 }
 //#endregion
@@ -6662,25 +7102,26 @@ function injectReloadClient(html) {
 * 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 - The rebuild dependencies + the changed file/paths.
+* @param input.runBuild - Runs one build (given the changed paths) 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.onReloaded - Called with the changed file + summary + the built `changed` set after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @param input.file - The changed file to report alongside the summary.
+* @param input.changed - The accumulated changed paths handed to `runBuild` (incremental).
 * @returns Resolves once the rebuild settles (always — errors are routed, not thrown).
 * @example
-* await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md" });
+* await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md", changed: ["a.md"] });
 */
 async function runOneRebuild(input) {
 	input.onRebuildStart?.(input.file);
 	try {
-		const summary = await input.runBuild();
+		const summary = await input.runBuild(input.changed);
 		input.onReloaded({
 			file: input.file,
 			pageCount: summary.pageCount,
 			durationMs: summary.durationMs
-		});
+		}, input.changed);
 	} catch (error) {
 		input.onError(error);
 	}
@@ -6694,9 +7135,9 @@ 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.runBuild - Runs one build (given the changed paths) 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.onReloaded - Called with the changed file + summary + the built `changed` set after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @returns The debounced rebuild driver.
 * @example
@@ -6705,12 +7146,13 @@ async function runOneRebuild(input) {
 function createRebuilder(input) {
 	let timer;
 	let pendingFile = "";
+	const pendingChanged = /* @__PURE__ */ new Set();
 	let building = false;
 	let dirty = false;
 	/**
-	* 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.
+	* Rebuild repeatedly until no change arrived mid-flight: each pass snapshots + clears
+	* the accumulated changed paths, runs one build over them, then loops again if a
+	* `schedule()` set `dirty` (and added more paths) while it ran, so no change is dropped.
 	*
 	* @returns Resolves once a pass completes with no pending change (errors are routed,
 	*   never thrown).
@@ -6720,12 +7162,15 @@ function createRebuilder(input) {
 	const drainPendingRebuilds = async () => {
 		do {
 			dirty = false;
+			const changed = [...pendingChanged];
+			pendingChanged.clear();
 			await runOneRebuild({
 				runBuild: input.runBuild,
 				...input.onRebuildStart ? { onRebuildStart: input.onRebuildStart } : {},
 				onReloaded: input.onReloaded,
 				onError: input.onError,
-				file: pendingFile
+				file: pendingFile,
+				changed
 			});
 		} while (dirty);
 	};
@@ -6752,14 +7197,15 @@ function createRebuilder(input) {
 	};
 	return {
 		/**
-		* Queue a rebuild for the given label (debounced + coalesced).
+		* Queue a rebuild for the given changed path (debounced + coalesced + accumulated).
 		*
-		* @param file - The label reported as `ReloadInfo.file` — the watched directory in `serve()`.
+		* @param file - The changed path reported as `ReloadInfo.file` and added to the changed set.
 		* @example
-		* rebuilder.schedule("content");
+		* rebuilder.schedule("content/intro/en.md");
 		*/
 		schedule(file) {
 			pendingFile = file;
+			pendingChanged.add(file);
 			if (timer) clearTimeout(timer);
 			timer = setTimeout(fire, input.debounceMs);
 		},
@@ -6789,26 +7235,33 @@ 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.
+* Create a {@link ChangeGate} that drops four 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), the stale duplicate/parent-dir echoes
+* macOS fires for one save (a build-start high-water mark — a change whose mtime is at or
+* before the last build we started was already captured), and — when a `fileHash` seam is
+* supplied — a NO-OP save whose bytes are identical to the last successfully-built version
+* (a double Ctrl-S, a `touch`, a format-on-save that reverts). The no-op baseline is
+* recorded ONLY by {@link ChangeGate.commitBuilt} on build SUCCESS, scoped to that build's
+* paths — so a failed build commits nothing (a retry save always rebuilds) and a file
+* edited mid-build is never falsely baselined by another file's success. A genuinely newer
+* edit (even mid-build) and a deletion (missing file) always pass.
 *
 * @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.
+* @param input.fileHash - Resolves a path's content hash (or `null` when missing). Optional;
+*   defaults to `() => null`, which disables the no-op-save short-circuit (every edit passes).
 * @returns The change gate.
 * @example
-* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock });
+* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock, fileHash: state.fileHash });
 */
 function createChangeGate(input) {
 	const outDirAbs = path.resolve(input.outDir);
+	const fileHash = input.fileHash ?? (() => null);
 	let lastBuildStartedAt = input.now();
+	const committedHash = /* @__PURE__ */ new Map();
 	return {
 		/**
 		* Decide whether a change beneath `dir` warrants a rebuild (see {@link ChangeGate.accept}).
@@ -6826,6 +7279,12 @@ function createChangeGate(input) {
 			if (changed === outDirAbs || changed.startsWith(`${outDirAbs}${path.sep}`)) return false;
 			const mtime = input.fileMtime(changed);
 			if (mtime !== null && mtime < lastBuildStartedAt) return false;
+			const hash = fileHash(changed);
+			if (hash === null) {
+				committedHash.delete(changed);
+				return true;
+			}
+			if (committedHash.get(changed) === hash) return false;
 			return true;
 		},
 		/**
@@ -6836,6 +7295,20 @@ function createChangeGate(input) {
 		*/
 		markBuildStart() {
 			lastBuildStartedAt = input.now();
+		},
+		/**
+		* Baseline exactly the paths the just-succeeded build consumed (see {@link ChangeGate.commitBuilt}).
+		*
+		* @param changed - The paths the just-succeeded build consumed.
+		* @example
+		* gate.commitBuilt(["content/intro/en.md"]);
+		*/
+		commitBuilt(changed) {
+			for (const file of changed) {
+				const key = path.resolve(file);
+				const hash = fileHash(key);
+				if (hash !== null) committedHash.set(key, hash);
+			}
 		}
 	};
 }
@@ -7028,19 +7501,46 @@ function createDevHandler(ctx, hub) {
 	};
 }
 /**
+* Build the per-run {@link BuildRunOverrides} for a dev build from the session feature
+* opt-ins: minification is always off in dev (no benefit, slower), and each expensive
+* output stays off unless its flag re-enables it (`ogImage: false` disables OG generation
+* regardless of the persisted config). The persisted plugin config is never mutated — the
+* overrides apply to the dev run only.
+*
+* @param features - The resolved per-session dev feature opt-ins.
+* @returns The config overrides merged into the dev build run.
+* @example
+* devBuildOverrides({ og: false, sitemap: false, feeds: false, localeRedirects: false });
+*/
+function devBuildOverrides(features) {
+	return {
+		minify: false,
+		...features.feeds ? {} : { feeds: false },
+		...features.sitemap ? {} : { sitemap: false },
+		...features.og ? {} : { ogImage: false },
+		...features.localeRedirects ? {} : { localeRedirects: false }
+	};
+}
+/**
 * 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.
+* which stops the server, closes the watchers, and cancels any pending rebuild. The dev
+* build disables minification + expensive outputs (per {@link devBuildOverrides}); every
+* rebuild also skips the clean so caches + unchanged assets survive (no mid-rebuild 404).
+* Because rebuilds skip the clean, a DELETED or renamed content slug's stale page lingers
+* (and is served) until you restart `serve` or run a production `build`.
 *
 * @param ctx - The cli plugin context (config, state seams, `require`).
 * @param port - The port to bind the dev server to.
+* @param features - Per-session dev feature opt-ins (`og`/`sitemap`/`feeds`/`localeRedirects`).
 * @returns Resolves once the server has been torn down by a termination signal.
 * @example
-* await runDevServer(ctx, 4173);
+* await runDevServer(ctx, 4173, { og: false, sitemap: false, feeds: false, localeRedirects: false });
 */
-async function runDevServer(ctx, port) {
-	await ctx.require(buildPlugin).run();
+async function runDevServer(ctx, port, features) {
+	const overrides = devBuildOverrides(features);
+	await ctx.require(buildPlugin).run({ overrides });
 	const hub = createReloadHub();
 	const server = ctx.state.serveStatic({
 		port,
@@ -7050,19 +7550,27 @@ async function runDevServer(ctx, port) {
 	const gate = createChangeGate({
 		outDir: ctx.config.outDir,
 		fileMtime: ctx.state.fileMtime,
-		now: ctx.state.clock
+		now: ctx.state.clock,
+		fileHash: ctx.state.fileHash
 	});
 	const rebuilder = createRebuilder({
 		debounceMs: ctx.config.debounceMs,
 		/**
-		* Re-run the SSG build for a rebuild.
+		* Re-run the SSG build for a rebuild: skip the clean so the prior assets + on-disk
+		* caches survive (and no in-flight request hits an empty outDir), with the dev
+		* overrides applied.
 		*
+		* @param changed - The paths changed since the last build (incremental rebuild hint).
 		* @returns The rebuild summary.
 		* @example
-		* await runBuild();
+		* await runBuild(["content/intro/en.md"]);
 		*/
-		runBuild() {
-			return ctx.require(buildPlugin).run();
+		runBuild(changed) {
+			return ctx.require(buildPlugin).run({
+				skipClean: true,
+				overrides,
+				changed
+			});
 		},
 		/**
 		* Show the compact in-place "rebuilding {label}" line before the build runs.
@@ -7079,15 +7587,18 @@ async function runDevServer(ctx, port) {
 		* 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.
+		* @param changed - The paths this successful build consumed (baselined for no-op drops).
 		* @example
-		* onReloaded({ file: "a.md", pageCount: 1, durationMs: 10 });
+		* onReloaded({ file: "a.md", pageCount: 1, durationMs: 10 }, ["content/a.md"]);
 		*/
-		onReloaded(info) {
+		onReloaded(info, changed) {
+			gate.commitBuilt(changed);
 			ctx.state.render.reload(info);
 			hub.reloadAll();
 		},
 		/**
-		* Render a rebuild failure (the dev loop keeps running).
+		* Render a rebuild failure (the dev loop keeps running). A failed build baselines
+		* nothing (commitBuilt only runs on success), so an identical retry save still rebuilds.
 		*
 		* @param error - The thrown rebuild error.
 		* @example
@@ -7098,7 +7609,8 @@ async function runDevServer(ctx, port) {
 		}
 	});
 	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, (filename) => {
-		if (gate.accept(dir, filename)) rebuilder.schedule(dir);
+		if (!gate.accept(dir, filename)) return;
+		rebuilder.schedule(filename === void 0 ? dir : path.join(dir, filename));
 	}));
 	ctx.state.render.serverReady({
 		local: `http://localhost:${port}`,
@@ -7110,6 +7622,7 @@ async function runDevServer(ctx, port) {
 		for (const watcher of watchers) watcher.close();
 		hub.close();
 		server.stop();
+		ctx.state.render.dispose();
 	});
 }
 //#endregion
@@ -7310,6 +7823,28 @@ async function confirmDeploy(ctx, yes) {
 	if (!confirmed) ctx.state.render.warn("deploy skipped");
 	return confirmed;
 }
+/** Matches the prerequisite/credential failures a direct deploy most often hits (missing token/account). */
+const PREREQUISITE_ERROR = /required variable|not defined|cloudflare|token|account|unauthor|wrangler/i;
+/**
+* A short, actionable "how to fix" hint for a failed deploy, rendered under the error so
+* the user is never left at a raw stack trace. A missing-credential/prerequisite failure
+* (the common case for a first direct deploy) gets the concrete secret-setup steps;
+* anything else points at the guided deploy, which diagnoses prerequisites step by step.
+*
+* @param error - The thrown deploy error.
+* @returns The multi-line hint (newline-separated; rendered indented under a `›`).
+* @example
+* render.info(deployFailureHint(err));
+*/
+function deployFailureHint(error) {
+	if (PREREQUISITE_ERROR.test(String(error))) return [
+		"how to fix:",
+		"1. run `bun run deploy` (without `--cli`) — the guided setup diagnoses prerequisites and offers to create a starter .env",
+		"2. or set them yourself in .env: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID",
+		"   token: https://dash.cloudflare.com/profile/api-tokens (template: Cloudflare Pages — Edit)"
+	].join("\n");
+	return "how to fix: run `bun run deploy` (without `--cli`) — the guided setup diagnoses prerequisites — then retry";
+}
 /**
 * Create the cli plugin API surface — exactly `build`, `serve`, `preview`, `deploy`.
 * Each method renders `state.render.header(<command>)` first, then does its work;
@@ -7342,17 +7877,25 @@ function createApi$1(ctx) {
 		},
 		/**
 		* Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
-		* `watchDirs`, debounced rebuild + reload. Resolves on SIGINT/SIGTERM.
+		* `watchDirs`, debounced + incremental rebuild + reload. For a fast rebuild the dev
+		* build disables minification + expensive, preview-irrelevant outputs (feeds /
+		* sitemap / og-images / locale-redirects); pass `og`/`sitemap`/`feeds`/
+		* `localeRedirects` to re-enable any of them for the session. Resolves on SIGINT/SIGTERM.
 		*
-		* @param options - Optional port override (defaults to `config.port`).
+		* @param options - Optional port override + per-session dev feature opt-ins.
 		* @returns Resolves once the server has been torn down.
 		* @example
-		* await api.serve({ port: 3000 });
+		* await api.serve({ port: 3000, og: true });
 		*/
 		serve(options = {}) {
 			const { port = ctx.config.port } = options;
 			ctx.state.render.header("serve");
-			return runDevServer(ctx, port);
+			return runDevServer(ctx, port, {
+				og: options.og ?? false,
+				sitemap: options.sitemap ?? false,
+				feeds: options.feeds ?? false,
+				localeRedirects: options.localeRedirects ?? false
+			});
 		},
 		/**
 		* Static preview of the built `dist/` with CF-Pages clean-URL resolution.
@@ -7384,15 +7927,21 @@ function createApi$1(ctx) {
 			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 (!await confirmDeploy(ctx, yes)) return {
-				deployed: false,
-				reason: "declined"
-			};
-			return {
-				deployed: true,
-				...await ctx.require(deployPlugin).run(branch === void 0 ? {} : { branch })
-			};
+			try {
+				await ctx.require(deployPlugin).init({ ci: true });
+				if (!await confirmDeploy(ctx, yes)) return {
+					deployed: false,
+					reason: "declined"
+				};
+				return {
+					deployed: true,
+					...await ctx.require(deployPlugin).run(branch === void 0 ? {} : { branch })
+				};
+			} catch (error) {
+				ctx.state.render.error("deploy failed", error);
+				ctx.state.render.info(deployFailureHint(error));
+				throw error;
+			}
 		}
 	};
 }
@@ -7483,6 +8032,28 @@ const ANSI = {
 	cyan: `${ESC}[36m`,
 	gray: `${ESC}[90m`
 };
+/**
+* The Moku brand pink (`#FF1E6F`) as an RGB triple, used for 24-bit truecolor output.
+* Degrades to {@link ANSI.magenta} on a 16-color TTY and to plain text off a TTY.
+*/
+const BRAND_PINK = {
+	r: 255,
+	g: 30,
+	b: 111
+};
+/**
+* Build a 24-bit (truecolor) SGR foreground escape for the given RGB triple.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The `ESC[38;2;r;g;bm` foreground sequence.
+* @example
+* fg24(255, 30, 111); // "\x1b[38;2;255;30;111m"
+*/
+function fg24(r, g, b) {
+	return `${ESC}[38;2;${r};${g};${b}m`;
+}
 /** 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). */
@@ -7554,6 +8125,36 @@ function supportsColor(stream = process.stdout, noColor = process.env.NO_COLOR)
 	return stream.isTTY === true && noColor === void 0;
 }
 /**
+* Whether the terminal advertises 24-bit (truecolor) support via `COLORTERM`, so the
+* renderer may emit the exact brand pink ({@link BRAND_PINK}) instead of the 16-color
+* `magenta` approximation. Always layered on top of {@link supportsColor} — truecolor
+* is never used when color itself is disabled.
+*
+* @param colorTerm - The `COLORTERM` value (defaults to `process.env.COLORTERM`).
+* @returns `true` when `COLORTERM` is `truecolor` or `24bit`.
+* @example
+* supportsTruecolor("truecolor"); // true
+*/
+function supportsTruecolor(colorTerm = process.env.COLORTERM) {
+	return colorTerm === "truecolor" || colorTerm === "24bit";
+}
+/**
+* The braille spinner glyph for a given elapsed time, advancing one frame per
+* `frameMs`. Deriving the frame from wall-clock elapsed (rather than a tick counter)
+* keeps the spinner correct even when the animation ticker is briefly starved by a
+* synchronous build phase and several ticks coalesce — the glyph still reflects real
+* elapsed time instead of freezing on a stale frame.
+*
+* @param elapsedMs - Milliseconds since the live region opened.
+* @param frameMs - Milliseconds per frame (defaults to `80`).
+* @returns The active spinner glyph.
+* @example
+* spinnerFrameAt(240); // "⠹" (the 4th frame at 80ms/frame)
+*/
+function spinnerFrameAt(elapsedMs, frameMs = 80) {
+	return SPINNER_FRAMES[Math.floor(Math.max(0, elapsedMs) / frameMs) % SPINNER_FRAMES.length] ?? "⠋";
+}
+/**
 * 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.
@@ -7581,12 +8182,14 @@ function visibleWidth(text) {
 * output in CI/pipes.
 *
 * @param color - Whether color is enabled (typically `supportsColor()`).
+* @param truecolor - Whether 24-bit output is enabled (typically `supportsTruecolor()`);
+*   only consulted by {@link Palette.pink}. Defaults to `false` (16-color magenta).
 * @returns The bound color palette.
 * @example
-* const palette = makePalette(supportsColor());
+* const palette = makePalette(supportsColor(), supportsTruecolor());
 * const line = palette.green("done");
 */
-function makePalette(color) {
+function makePalette(color, truecolor = false) {
 	return {
 		enabled: color,
 		/**
@@ -7666,23 +8269,39 @@ function makePalette(color) {
 		*/
 		cyan(text) {
 			return this.paint(ANSI.cyan, text);
+		},
+		/**
+		* Color the given text the Moku brand pink: exact `#FF1E6F` (24-bit) when truecolor
+		* is enabled, the 16-color `magenta` approximation otherwise, unchanged in plain mode.
+		*
+		* @param text - The text to colorize.
+		* @returns The pink (or unchanged) text.
+		* @example
+		* palette.pink("▟▙ moku web");
+		*/
+		pink(text) {
+			if (!color) return text;
+			if (truecolor) return `${fg24(BRAND_PINK.r, BRAND_PINK.g, BRAND_PINK.b)}${text}${ANSI.reset}`;
+			return this.paint(ANSI.magenta, 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.
+* widest visible line (or `minInnerWidth`, whichever is larger — so several boxes can be
+* forced to a shared width). 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).
+* @param minInnerWidth - Minimum inner (content) width to pad every row to. Defaults to `0`.
 * @returns The boxed lines (top border, content rows, bottom border).
 * @example
-* box(["Local:   http://localhost:4173"], true);
+* box(["Local:   http://localhost:4173"], true, 62);
 */
-function box(lines, color) {
+function box(lines, color, minInnerWidth = 0) {
 	const glyphs = boxGlyphs(color);
-	const inner = Math.max(0, ...lines.map((line) => visibleWidth(line)));
+	const inner = Math.max(0, minInnerWidth, ...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}`;
@@ -7697,13 +8316,70 @@ function box(lines, color) {
 }
 //#endregion
 //#region src/plugins/cli/render/panel.ts
-/** Per-command label shown in the header badge beside the logo. */
+/** Per-command label shown beside the lockup wordmark. */
 const COMMAND_LABEL = {
 	build: "build",
 	serve: "serve · dev",
 	preview: "preview",
 	deploy: "deploy"
 };
+/** Total visible width the header rule spans and the per-row timing column right-aligns to. */
+const RAIL_WIDTH = 66;
+/** Animation repaint cadence (ms) — how often the live region is redrawn when the loop is free. */
+const TICK_MS = 40;
+/** Spinner frame interval (ms) — one braille glyph advance per this many elapsed ms. */
+const SPIN_MS = 60;
+/** Inner (content) width of the BUILD/server boxes so their right edge lines up with the phase tree. */
+const BOX_INNER = RAIL_WIDTH - 4;
+/** The eight block glyphs the per-phase time-profile sparkline maps durations onto. */
+const SPARK_BARS = "▁▂▃▄▅▆▇█";
+/**
+* Build a sparkline from a list of values — one block glyph per value, height scaled to
+* the largest value so the tallest bar is `█`. A real micro-histogram (no fake data):
+* under the BUILD summary each bar is one phase's duration, so the slowest phase stands
+* out at a glance. Returns `""` for an empty list.
+*
+* @param values - The values to plot (e.g. per-phase durations in ms).
+* @returns The sparkline string.
+* @example
+* sparkline([12, 1701, 19698, 9]); // "▁▁█▁"
+*/
+function sparkline(values) {
+	if (values.length === 0) return "";
+	const max = Math.max(...values, 1);
+	return values.map((value) => {
+		return SPARK_BARS[Math.min(7, Math.floor(value / max * 7))] ?? SPARK_BARS[0];
+	}).join("");
+}
+/**
+* The structural glyph set for the active color mode: Unicode on a color-capable TTY,
+* ASCII fallbacks off it. Only the NEW Velocity chrome (cube, rule, tree, bar, live
+* dot) degrades here — the `✓ ✗ ~ ➜ ›` status marks stay as-is in both modes.
+*
+* @param color - Whether color/Unicode output is enabled.
+* @returns The matching glyph set.
+* @example
+* const g = glyphSet(true);
+*/
+function glyphSet(color) {
+	return color ? {
+		cube: "▟▙",
+		rule: "─",
+		tree: "├─",
+		barFill: "━",
+		barTrack: "╴",
+		liveOn: "◍",
+		liveOff: "○"
+	} : {
+		cube: "*",
+		rule: "-",
+		tree: "-",
+		barFill: "#",
+		barTrack: "-",
+		liveOn: "*",
+		liveOff: "*"
+	};
+}
 /**
 * Render one human-readable duration suffix (e.g. `· 84ms`).
 *
@@ -7718,15 +8394,49 @@ function durationSuffix(palette, durationMs) {
 	return ` ${palette.dim(`· ${durationMs}ms`)}`;
 }
 /**
+* Right-align `right` against `left` within {@link RAIL_WIDTH}, measuring visible width
+* so embedded ANSI never throws the timing column off.
+*
+* @param left - The left segment (may contain ANSI).
+* @param right - The right segment (may contain ANSI).
+* @param width - Total visible width to fill (defaults to {@link RAIL_WIDTH}).
+* @returns The padded line.
+* @example
+* railLine("  ├─ ✓ pages", "· 12ms");
+*/
+function railLine(left, right, width = RAIL_WIDTH) {
+	const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+	return `${left}${" ".repeat(gap)}${right}`;
+}
+/**
+* The runtime facts line shown under the banner: the pinned core version (when known)
+* plus the live Node/Bun versions + platform — the ACTUAL running runtime, not the
+* `engines` floor. Every value is real (read from `@moku-labs/core`'s pinned dependency
+* and `process.versions`), so nothing on this line is faked.
+*
+* @param coreVersion - The pinned `@moku-labs/core` version (appended last — it rarely
+*   matters — and omitted entirely when unknown).
+* @returns The facts string (e.g. `node 24.3.0 · bun 1.3.9 · darwin arm64 · core 0.1.0-alpha.6`).
+* @example
+* runtimeFacts("0.1.0-alpha.6");
+*/
+function runtimeFacts(coreVersion) {
+	const node = `node ${process.versions.node}`;
+	const bun = process.versions.bun ? ` · bun ${process.versions.bun}` : "";
+	const core = coreVersion ? ` · core ${coreVersion}` : "";
+	return `${node}${bun} · ${process.platform} ${process.arch}${core}`;
+}
+/**
 * 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.
+* (default `console.log`/`console.error`) and colorized only when color is enabled, so
+* the identical render path yields the animated, box-free Velocity UI on a TTY and
+* plain ASCII lines in CI/pipes.
 *
-* @param options - Optional sinks + a color override (see {@link PanelOptions}).
+* @param options - Optional sinks, color/truecolor overrides, clock, and version (see
+*   {@link PanelOptions}).
 * @returns The renderer mounted on `state.render` and driven by the API + hooks.
 * @example
-* const render = createPanelRenderer();
+* const render = createPanelRenderer({ version: "0.1.0-alpha" });
 * render.header("build");
 */
 function createPanelRenderer(options = {}) {
@@ -7737,26 +8447,24 @@ function createPanelRenderer(options = {}) {
 	});
 	const now = options.now ?? Date.now;
 	const color = options.color ?? supportsColor();
-	const palette = makePalette(color);
+	const palette = makePalette(color, options.truecolor ?? (color && supportsTruecolor()));
+	const version = options.version ?? "dev";
+	const coreVersion = options.coreVersion;
+	const g = glyphSet(color);
 	let phaseRows = [];
 	let phaseDrawn = 0;
 	let phaseOpen = false;
+	let blockStartedAt = 0;
 	let rebuilding = false;
 	let rebuildLabel = "";
 	let rebuildStartedAt = 0;
-	let spinnerFrame = 0;
+	let idle = false;
+	let idleStartedAt = 0;
+	let serveMode = false;
 	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.
+	* Render one phase-tree row: a spinning cyan glyph + dim name while running, or a green
+	* `✓` + name with the duration right-aligned in the dim timing column once done.
 	*
 	* @param row - The phase row to render.
 	* @returns The rendered row line (no trailing newline).
@@ -7764,12 +8472,34 @@ function createPanelRenderer(options = {}) {
 	* 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)}`;
+		const branch = palette.dim(g.tree);
+		if (row.done) return railLine(`  ${branch} ${palette.green("✓")} ${row.name}`, palette.dim(`· ${row.durationMs}ms`));
+		return `  ${branch} ${palette.cyan(spinnerFrameAt(now() - blockStartedAt, SPIN_MS))} ${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).
+	* Render the indeterminate "comet" build bar — a short pink fill window sweeping across
+	* a dim track — for the given elapsed time. Animated purely from wall-clock elapsed so
+	* it never needs a known phase total.
+	*
+	* @param elapsedMs - Milliseconds since the phase block opened.
+	* @returns The rendered bar row (no trailing newline).
+	* @example
+	* renderBuildBar(300);
+	*/
+	const renderBuildBar = (elapsedMs) => {
+		const length = 28;
+		const window = 6;
+		const head = Math.floor(elapsedMs / 28) % 34;
+		let bar = "";
+		for (let index = 0; index < length; index++) {
+			const lit = index <= head && index > head - window;
+			bar += lit ? palette.pink(g.barFill) : palette.dim(g.barTrack);
+		}
+		return `     ${bar}`;
+	};
+	/**
+	* Repaint the live phase block in place (tree rows + animated build bar): move up over
+	* the prior draw, rewrite each row, then the bar, clearing any stale trailing lines.
 	*
 	* @example
 	* paintPhaseBlock();
@@ -7777,8 +8507,9 @@ function createPanelRenderer(options = {}) {
 	const paintPhaseBlock = () => {
 		let frame = cursorUp(phaseDrawn);
 		for (const row of phaseRows) frame += `${CLEAR_LINE}${renderPhaseRow(row)}\n`;
+		frame += `${CLEAR_LINE}${renderBuildBar(now() - blockStartedAt)}\n`;
 		writeRaw(frame + CLEAR_BELOW);
-		phaseDrawn = phaseRows.length;
+		phaseDrawn = phaseRows.length + 1;
 	};
 	/**
 	* Repaint the single in-place rebuild line (spinner + label + live elapsed seconds).
@@ -7787,20 +8518,31 @@ function createPanelRenderer(options = {}) {
 	* 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}`);
+		const spinner = palette.cyan(spinnerFrameAt(now() - rebuildStartedAt, SPIN_MS));
+		const elapsed = palette.dim(`· ${((now() - rebuildStartedAt) / 1e3).toFixed(1)}s`);
+		writeRaw(`\r${CLEAR_LINE}  ${spinner} rebuilding ${rebuildLabel} ${elapsed}`);
 	};
 	/**
-	* Advance the spinner one frame and repaint whichever live region is active.
+	* Repaint the persistent in-place `◍ live` idle pulse beneath the serve panel — the
+	* dot breathes (pink → dim) on a calm ~0.6s cycle so a quiet dev session always reads
+	* as alive without strobing.
+	*
+	* @example
+	* paintIdleLine();
+	*/
+	const paintIdleLine = () => {
+		writeRaw(`\r${CLEAR_LINE}  ${Math.floor((now() - idleStartedAt) / 450) % 2 === 0 ? palette.pink(g.liveOn) : palette.dim(g.liveOff)} ${palette.dim("live · waiting for changes…")}`);
+	};
+	/**
+	* Advance whichever live region is active by one frame (driven by the shared ticker).
 	*
 	* @example
 	* onTick();
 	*/
 	const onTick = () => {
-		spinnerFrame += 1;
 		if (rebuilding) paintRebuildLine();
 		else if (phaseOpen) paintPhaseBlock();
+		else if (idle) paintIdleLine();
 	};
 	/**
 	* Start the animation ticker (TTY only; idempotent; `unref`'d so it never blocks exit).
@@ -7810,7 +8552,7 @@ function createPanelRenderer(options = {}) {
 	*/
 	const startTicker = () => {
 		if (!color || ticker) return;
-		ticker = setInterval(onTick, 80);
+		ticker = setInterval(onTick, TICK_MS);
 		ticker.unref?.();
 	};
 	/**
@@ -7833,22 +8575,47 @@ function createPanelRenderer(options = {}) {
 	const writeBlock = (lines) => {
 		for (const line of lines) write(line);
 	};
+	/**
+	* Resume the serve idle pulse on a fresh bottom line (TTY serve sessions only). A no-op
+	* outside serve so standalone rebuild/error calls in unit tests never leave a ticker
+	* running.
+	*
+	* @example
+	* resumeIdle();
+	*/
+	const resumeIdle = () => {
+		if (!(color && serveMode)) {
+			stopTicker();
+			return;
+		}
+		idle = true;
+		idleStartedAt = now();
+		paintIdleLine();
+		startTicker();
+	};
 	return {
 		/**
-		* Render the boxed `MOKU WEB` logo + command label.
+		* Render the `▟▙ moku web` lockup + per-command label, a dim rule, and the runtime
+		* facts line (live Node/Bun versions + platform). Called once per command (one
+		* command = one process), so it never repeats within a run.
 		*
-		* @param command - The command being run, shown beside the logo.
+		* @param command - The command being run, shown beside the wordmark.
 		* @example
 		* render.header("serve");
 		*/
 		header(command) {
-			writeBlock(box([`${palette.bold(palette.cyan("MOKU WEB"))}  ${palette.dim(COMMAND_LABEL[command])}`], color));
+			writeBlock([
+				railLine(` ${palette.pink(g.cube)} ${palette.pink(palette.bold("moku web"))}  ${palette.dim(COMMAND_LABEL[command])}`, palette.dim(version)),
+				` ${palette.dim(g.rule.repeat(RAIL_WIDTH - 1))}`,
+				` ${palette.dim(runtimeFacts(coreVersion))}`
+			]);
 		},
 		/**
-		* 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.
+		* Render a live per-phase row from a `build:phase` event. On a TTY each phase is ONE
+		* tree row that updates in place (spinning glyph while running → green ✓ + duration
+		* when done) beneath an animated indeterminate build bar; 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
@@ -7864,6 +8631,7 @@ function createPanelRenderer(options = {}) {
 				phaseRows = [];
 				phaseDrawn = 0;
 				phaseOpen = true;
+				blockStartedAt = now();
 			}
 			const done = phase.status === "done";
 			const existing = phaseRows.find((row) => row.name === phase.phase);
@@ -7879,7 +8647,9 @@ function createPanelRenderer(options = {}) {
 			startTicker();
 		},
 		/**
-		* Render the BUILD summary block from a `build:complete` event.
+		* Render the BUILD summary line + a one-shot throughput sparkline from a
+		* `build:complete` event, finalizing the live phase tree (dropping its animated bar)
+		* first.
 		*
 		* @param summary - The `build:complete` payload.
 		* @example
@@ -7887,33 +8657,52 @@ function createPanelRenderer(options = {}) {
 		*/
 		built(summary) {
 			if (rebuilding) return;
+			if (color && phaseOpen) {
+				let frame = cursorUp(phaseDrawn);
+				for (const row of phaseRows) frame += `${CLEAR_LINE}${renderPhaseRow(row)}\n`;
+				writeRaw(frame + CLEAR_BELOW);
+			}
+			const phaseDurations = phaseRows.map((row) => row.durationMs).filter((value) => value !== void 0);
 			phaseOpen = false;
 			phaseDrawn = 0;
 			stopTicker();
 			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));
+			const dot = palette.dim("·");
+			const lines = [railLine(`${palette.green("✓")} ${palette.bold("BUILD")} ${dot} ${pages} pages`, `${summary.durationMs}ms ${dot} ${summary.outDir}/`, BOX_INNER)];
+			if (color && summary.durationMs > 0) {
+				const rate = Math.max(1, Math.round(summary.pageCount / (summary.durationMs / 1e3)));
+				const spark = phaseDurations.length > 0 ? palette.pink(sparkline(phaseDurations)) : "";
+				const rateLabel = palette.dim(`${rate} pages/s`);
+				lines.push(railLine(spark, rateLabel, BOX_INNER));
+			}
+			writeBlock(box(lines, color, BOX_INNER));
 		},
 		/**
-		* Render the bordered server-ready panel (Local / Network URLs + watched dirs).
+		* Render the server-ready rail (Local / Network URLs + watched dirs) and, on a TTY,
+		* begin the persistent breathing `◍ live` idle pulse beneath it.
 		*
 		* @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));
+			const network = info.network ? palette.cyan(info.network) : palette.dim("unavailable");
+			const lines = [`${palette.green("➜")} ${palette.bold("Local")}    ${palette.cyan(info.local)}`, `${palette.green("➜")} ${palette.bold("Network")}  ${network}`];
+			if (info.watching && info.watching.length > 0) lines.push(`${palette.dim("watching")}   ${palette.dim(info.watching.join(", "))}`);
+			writeBlock(box(lines, color, BOX_INNER));
+			if (color) {
+				serveMode = true;
+				idle = true;
+				idleStartedAt = now();
+				paintIdleLine();
+				startTicker();
+			}
 		},
 		/**
 		* 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.
+		* spinner with live elapsed on a TTY; a plain "~ {label}" line otherwise), taking over
+		* the idle-pulse line, and mute the verbose phase tree + BUILD summary until
+		* {@link reload}/{@link error} settles it.
 		*
 		* @param label - The changed watch target shown in the line.
 		* @example
@@ -7921,9 +8710,9 @@ function createPanelRenderer(options = {}) {
 		*/
 		rebuildStart(label) {
 			rebuilding = true;
+			idle = false;
 			rebuildLabel = label;
 			rebuildStartedAt = now();
-			spinnerFrame = 0;
 			if (!color) {
 				write(`  ${palette.yellow("~")} ${label}`);
 				return;
@@ -7933,9 +8722,9 @@ function createPanelRenderer(options = {}) {
 		},
 		/**
 		* 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.
+		* "✓ rebuilt N pages · Xms · reloaded", then (in a serve session) resume the idle pulse
+		* on a fresh bottom line. 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
@@ -7944,30 +8733,26 @@ function createPanelRenderer(options = {}) {
 		reload(info) {
 			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`);
+				resumeIdle();
 				return;
 			}
 			if (!settledRebuild) write(`  ${palette.yellow("~")} ${info.file}`);
 			write(line);
 		},
 		/**
-		* Render the deploy result panel from a `deploy:complete` event.
+		* Render the deploy result from a `deploy:complete` event: a `✓ DEPLOYED → url` line
+		* with the URL the hero value, then a dim `branch · id · time` line beneath it.
 		*
 		* @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));
+			const meta = palette.dim(`branch ${result.branch} · ${result.deploymentId} · ${result.durationMs}ms`);
+			writeBlock([`  ${palette.green("✓")} ${palette.bold("DEPLOYED")}   ${palette.dim("→")}  ${palette.cyan(result.url)}`, `  ${meta}`]);
 		},
 		/**
 		* Render a neutral informational line.
@@ -7992,7 +8777,8 @@ function createPanelRenderer(options = {}) {
 			writeError(`  ${palette.yellow("⚠")} ${message}`);
 		},
 		/**
-		* Render an error line (to stderr), optionally with a cause.
+		* Render an error line (to stderr), optionally with a cause. A failing rebuild settles
+		* its in-place spinner line first; in a serve session the idle pulse then resumes.
 		*
 		* @param message - The error summary to print.
 		* @param cause - Optional underlying error/value to print beneath the summary.
@@ -8000,16 +8786,18 @@ function createPanelRenderer(options = {}) {
 		* render.error("build failed", err);
 		*/
 		error(message, cause) {
+			const wasRebuilding = rebuilding;
 			if (rebuilding) {
 				rebuilding = false;
-				stopTicker();
 				if (color) writeRaw(`\r${CLEAR_LINE}`);
 			}
 			writeError(`  ${palette.red("✗")} ${message}`);
 			if (cause !== void 0) writeError(String(cause));
+			if (wasRebuilding) resumeIdle();
+			else stopTicker();
 		},
 		/**
-		* Render a section heading (a blank line + a bold cyan label) for a multi-step flow.
+		* Render a section heading (a blank line + a bold pink label) for a multi-step flow.
 		*
 		* @param text - The heading label.
 		* @example
@@ -8017,7 +8805,7 @@ function createPanelRenderer(options = {}) {
 		*/
 		heading(text) {
 			write("");
-			write(`  ${palette.bold(palette.cyan(text))}`);
+			write(`  ${palette.bold(palette.pink(text))}`);
 		},
 		/**
 		* Render a diagnostic line: green `✓` (pass) or red `✗` (fail) + label, with optional
@@ -8032,6 +8820,19 @@ function createPanelRenderer(options = {}) {
 		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)}`);
+		},
+		/**
+		* Stop every animation and release the interval timer (serve()'s teardown calls this).
+		*
+		* @example
+		* render.dispose();
+		*/
+		dispose() {
+			stopTicker();
+			idle = false;
+			rebuilding = false;
+			phaseOpen = false;
+			serveMode = false;
 		}
 	};
 }
@@ -8177,6 +8978,23 @@ function defaultFileMtime(filePath) {
 	}
 }
 /**
+* Default file-content-hash probe — `sha256` of the file bytes, returning `null` for a
+* missing/unreadable path. serve()'s change gate compares this against the last
+* successfully-built bytes to drop a no-op save (a byte-identical double Ctrl-S).
+*
+* @param filePath - The absolute path to hash.
+* @returns The hex SHA-256 of the file's bytes, or `null` when it cannot be read.
+* @example
+* const hash = defaultFileHash("/abs/content/a.md");
+*/
+function defaultFileHash(filePath) {
+	try {
+		return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+	} 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.
 *
@@ -8188,6 +9006,101 @@ function defaultFileMtime(filePath) {
 function defaultNetworkUrl(port) {
 	return networkUrl(port);
 }
+/** Memoized banner facts — resolution touches the filesystem + git once, then caches. */
+let cachedBanner;
+/**
+* Run a read-only `git` command in `dir`, returning its trimmed stdout (`undefined` on
+* any failure — not a checkout, git missing, etc.). A thin wrapper so the version
+* resolver can issue a couple of git queries without repeating the spawn boilerplate.
+*
+* @param dir - The working directory to run git in.
+* @param args - The git arguments (no user input is ever interpolated).
+* @returns The trimmed command output, or `undefined` on failure.
+* @example
+* git("/Users/me/moku/web", ["tag", "--list", "v*"]);
+*/
+function git(dir, args) {
+	try {
+		return execFileSync("git", args, {
+			cwd: dir,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return;
+	}
+}
+/**
+* The framework's source/dev version, derived the SAME way the publish workflow computes
+* a release: the highest semver `v*` tag is the source of truth (`@moku-labs/web` is
+* released tag-only — the working-tree `package.json` deliberately carries no `version`).
+* A `-dev` suffix marks it as a local build off that release line (e.g. `v1.1.0-dev`), so
+* it never masquerades as the published release. Falls back to the short commit (then
+* `undefined`) only when no tags exist. `undefined` when `dir` is not a git checkout (a
+* published npm install — which carries its real `version` instead).
+*
+* @param dir - A directory inside the framework's own repository (the realpath of the
+*   package root, so a symlinked local checkout reports the framework's tag — not the
+*   consumer's).
+* @returns The dev version (e.g. `v1.1.0-dev`), or `undefined`.
+* @example
+* devVersion("/Users/me/moku/web"); // "v1.1.0-dev"
+*/
+function devVersion(dir) {
+	const latestTag = git(dir, [
+		"tag",
+		"--list",
+		"v*",
+		"--sort=-v:refname"
+	])?.split("\n")[0]?.trim();
+	if (latestTag) return `${latestTag}-dev`;
+	const sha = git(dir, [
+		"rev-parse",
+		"--short",
+		"HEAD"
+	]);
+	return sha ? `${sha}-dev` : void 0;
+}
+/**
+* Resolve the real version/runtime facts shown in the Panel banner (memoized). Reads the
+* `package.json` shipped beside the built bundle (`dist/../package.json`): a PUBLISHED
+* release carries a `version` and reports `v{version}`; a source/dev build (no `version`
+* field — `@moku-labs/web` is released tag-only) reports the latest semver tag + `-dev`
+* (e.g. `v1.1.0-dev`, the same tag the publish workflow treats as the version source), or
+* `"dev"` when git is unavailable. The pinned `@moku-labs/core` version comes from the
+* same file's `dependencies`.
+*
+* @returns The resolved {@link BannerFacts}.
+* @example
+* resolveBanner(); // { version: "v1.1.0-dev", coreVersion: "0.1.0-alpha.6" }
+*/
+function resolveBanner() {
+	if (cachedBanner) return cachedBanner;
+	let pkg = {};
+	let pkgDir;
+	try {
+		const pkgUrl = new URL("../package.json", import.meta.url);
+		pkgDir = realpathSync(path.dirname(fileURLToPath(pkgUrl)));
+		pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+	} catch {}
+	const coreVersion = (pkg.dependencies?.["@moku-labs/core"] ?? "").replace(/^\D*/, "") || "unknown";
+	const released = pkg.version;
+	let version = "dev";
+	if (released) version = `v${released}`;
+	else {
+		const dev = devVersion(pkgDir ?? process.cwd());
+		if (dev) version = dev;
+	}
+	cachedBanner = {
+		version,
+		coreVersion
+	};
+	return cachedBanner;
+}
 /**
 * Create the initial cli plugin state with the production seams wired. Every field is
 * an injectable seam (`render`, `confirm`, `clock`, `watch`, the server factories,
@@ -8201,8 +9114,12 @@ function defaultNetworkUrl(port) {
 * const state = createState({ global: {}, config });
 */
 function createState$1(_ctx) {
+	const banner = resolveBanner();
 	return {
-		render: createPanelRenderer(),
+		render: createPanelRenderer({
+			version: banner.version,
+			coreVersion: banner.coreVersion
+		}),
 		confirm: defaultConfirm,
 		select: defaultSelect,
 		clock: Date.now,
@@ -8210,7 +9127,8 @@ function createState$1(_ctx) {
 		serveStatic: defaultServeStatic,
 		fileResponse: defaultFileResponse,
 		networkUrl: defaultNetworkUrl,
-		fileMtime: defaultFileMtime
+		fileMtime: defaultFileMtime,
+		fileHash: defaultFileHash
 	};
 }
 //#endregion