@moku-labs/web 1.0.1 → 1.2.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";
@@ -4877,10 +4879,47 @@ 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;
+/**
+* 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.
 *
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `log`, `has`).
 * @returns The number of pages rendered and the captured default-page HTML.
@@ -4896,8 +4935,7 @@ async function renderPages(ctx) {
 	const locales = ctx.require(i18nPlugin).locales();
 	const byPattern = makeEntryMap(router);
 	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), RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell));
 	await writeDataSidecars(ctx, rendered, router.mode());
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {
@@ -5761,6 +5799,19 @@ const CHECKOUT_SHA = "11bd71901bbe5b1630ceea73d27597364c9af683";
 const SETUP_BUN_SHA = "4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5";
 /** Pinned `cloudflare/wrangler-action` commit SHA. */
 const WRANGLER_ACTION_SHA = "f84a562284fc78278ff9052435d9526f9c718361";
+/** The `on:` block for each {@link WorkflowTrigger} (kept indentation-exact for YAML). */
+const TRIGGER_ON_BLOCKS = {
+	auto: `on:
+  push:
+    branches: [main]
+  workflow_dispatch:`,
+	"versioned-tag": `on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:`,
+	dispatch: `on:
+  workflow_dispatch:`
+};
 /**
 * Generate a SHA-pinned GitHub Actions workflow that builds and deploys to
 * Cloudflare Pages. Every action is pinned to a commit SHA (with a `# vX`
@@ -5770,9 +5821,10 @@ const WRANGLER_ACTION_SHA = "f84a562284fc78278ff9052435d9526f9c718361";
 *
 * @param input - The generator inputs.
 * @param input.slug - Cloudflare project-name slug used as the wrangler `--project-name`.
+* @param input.trigger - What fires the workflow (see {@link WorkflowTrigger}). Default `"auto"`.
 * @returns The workflow YAML.
 * @example
-* generateGithubWorkflow({ slug: "my-site" });
+* generateGithubWorkflow({ slug: "my-site", trigger: "versioned-tag" });
 */
 function generateGithubWorkflow(input) {
 	return `# .github/workflows/deploy.yml — generated by \`app.deploy.init({ ci: true })\`.
@@ -5780,10 +5832,7 @@ function generateGithubWorkflow(input) {
 
 name: Deploy
 
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
+${TRIGGER_ON_BLOCKS[input.trigger ?? "auto"]}
 
 permissions:
   contents: read
@@ -5915,7 +5964,10 @@ async function writeScaffolding(input) {
 	});
 	if (ci) await reconcile({
 		relativePath: WORKFLOW_PATH,
-		expected: generateGithubWorkflow({ slug }),
+		expected: generateGithubWorkflow({
+			slug,
+			...options.workflowTrigger ? { trigger: options.workflowTrigger } : {}
+		}),
 		existing: await readMaybe(cwd, WORKFLOW_PATH),
 		cwd,
 		check,
@@ -6433,6 +6485,224 @@ const deployPlugin = createPlugin$1("deploy", {
 	api: createApi$2
 });
 //#endregion
+//#region src/plugins/cli/deploy-wizard.ts
+/**
+* @file cli plugin — the guided deploy wizard (`cli.deploy({ guided: true })`, 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 = [
+	"Create one at https://dash.cloudflare.com/profile/api-tokens → Create Token →",
+	"use the \"Cloudflare Pages — Edit\" template (or a custom token with the",
+	"Account › Cloudflare Pages › Edit permission). Then make it available:",
+	"  export CLOUDFLARE_API_TOKEN=…   (shell)   or add it to .env (gitignored)."
+].join("\n");
+/** Where to find the Cloudflare account id + where to make it available locally. */
+const ACCOUNT_HELP = [
+	"Find it on the Cloudflare dashboard → Workers & Pages: the Account ID is in the",
+	"right-hand sidebar (also in the dashboard URL). Then make it available:",
+	"  export CLOUDFLARE_ACCOUNT_ID=…   or add it to .env."
+].join("\n");
+/** The GitHub repo secrets the generated workflow consumes. */
+const SECRETS_HELP = ["Add these repo secrets (GitHub → Settings → Secrets and variables → Actions):", "CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID"].join("\n");
+/**
+* Evaluate the three deploy prerequisites against the current project: the Cloudflare
+* wrangler config exists, and both Cloudflare credentials are present in the environment.
+*
+* @param cwd - The project root (where `wrangler.jsonc` lives).
+* @returns The ordered prerequisite checks.
+* @example
+* const prereqs = diagnose(process.cwd());
+*/
+function diagnose(cwd) {
+	const wranglerOk = existsSync(path.join(cwd, "wrangler.jsonc"));
+	const tokenOk = (process.env.CLOUDFLARE_API_TOKEN ?? "") !== "";
+	const accountOk = (process.env.CLOUDFLARE_ACCOUNT_ID ?? "") !== "";
+	return [
+		{
+			ok: wranglerOk,
+			label: "wrangler.jsonc (Cloudflare project config)",
+			detail: wranglerOk ? void 0 : "Missing — scaffold it (offered below) or run app.deploy.init().",
+			scaffoldable: true
+		},
+		{
+			ok: tokenOk,
+			label: "CLOUDFLARE_API_TOKEN is set",
+			detail: tokenOk ? void 0 : TOKEN_HELP,
+			scaffoldable: false
+		},
+		{
+			ok: accountOk,
+			label: "CLOUDFLARE_ACCOUNT_ID is set",
+			detail: accountOk ? void 0 : ACCOUNT_HELP,
+			scaffoldable: false
+		}
+	];
+}
+/**
+* Offer to scaffold a missing `wrangler.jsonc` (the only auto-fixable prerequisite),
+* generating it via the deploy plugin when the user accepts.
+*
+* @param ctx - The cli plugin context.
+* @param prereqs - The current prerequisite checks.
+* @returns Resolves once any accepted fix has run.
+* @example
+* await offerScaffold(ctx, diagnose(cwd));
+*/
+async function offerScaffold(ctx, prereqs) {
+	if (!prereqs.some((item) => item.scaffoldable && !item.ok)) return;
+	if (!await ctx.state.confirm("Scaffold wrangler.jsonc now?")) return;
+	await ctx.require(deployPlugin).init({});
+	ctx.state.render.check(true, "wrangler.jsonc scaffolded");
+}
+/** 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.
+*
+* @param ctx - The cli plugin context (for the follow-up sub-choice prompt).
+* @param choice - The selected zero-based index of the top-level options.
+* @returns The resolved trigger, or `null` to skip.
+* @example
+* const trigger = await resolveTrigger(ctx, 1);
+*/
+async function resolveTrigger(ctx, choice) {
+	if (choice === 2) return null;
+	if (choice === 0) return "auto";
+	return await ctx.state.select("How should the versioned deploy be triggered?", ["On a version tag push (v*) + the manual Run-workflow button", "Manual Run-workflow button only (workflow_dispatch)"]) === 0 ? "versioned-tag" : "dispatch";
+}
+/**
+* Offer to scaffold a GitHub Actions deploy workflow, letting the user choose how it is
+* triggered, then remind them which repo secrets to add. A no-op past a "skip" choice.
+*
+* @param ctx - The cli plugin context.
+* @returns Resolves once any chosen workflow has been scaffolded.
+* @example
+* await offerWorkflowSetup(ctx);
+*/
+async function offerWorkflowSetup(ctx) {
+	ctx.state.render.heading("Automate future deploys (GitHub Actions)");
+	const trigger = await resolveTrigger(ctx, await ctx.state.select("Set up a deploy workflow?", [
+		"Auto-deploy on every push to main",
+		"Manual / versioned deploy (choose trigger)",
+		"Skip for now"
+	]));
+	if (trigger === null) return;
+	const result = await ctx.require(deployPlugin).init({
+		ci: true,
+		workflowTrigger: trigger
+	});
+	const workflowPath = ".github/workflows/deploy.yml";
+	const wrote = result.written.includes(workflowPath);
+	ctx.state.render.check(true, wrote ? `wrote ${workflowPath}` : `${workflowPath} already exists (left unchanged)`);
+	ctx.state.render.info(SECRETS_HELP);
+}
+/**
+* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin and
+* report the outcome. A declined confirm returns `{ deployed: false, reason: "declined" }`.
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override + `yes`).
+* @returns The deploy outcome.
+* @example
+* const outcome = await runDeployStep(ctx, { yes: true });
+*/
+async function runDeployStep(ctx, options) {
+	ctx.state.render.heading("Deploy");
+	if (!(options.yes === true || await ctx.state.confirm(`Deploy ${ctx.config.outDir}/ to Cloudflare Pages now?`))) {
+		ctx.state.render.warn("deploy skipped");
+		return {
+			deployed: false,
+			reason: "declined"
+		};
+	}
+	return {
+		deployed: true,
+		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
+	};
+}
+/**
+* Run the guided deploy wizard end to end: diagnose prerequisites (offering to scaffold
+* the wrangler config), HARD-GATE on the remaining blockers, run a local build smoke
+* test, deploy (with confirmation), then offer to scaffold a CI workflow. Returns
+* `{ deployed: false, reason: "blocked" }` when prerequisites are unmet, so a thin script
+* can exit non-zero. Assumes the caller already rendered the `deploy` header.
+*
+* @param ctx - The cli plugin context (state seams + `require` + config).
+* @param options - The deploy options (branch override, `yes`, `guided`).
+* @returns The deploy outcome (`deployed`, or a `declined`/`blocked` skip).
+* @example
+* const outcome = await runDeployWizard(ctx, { guided: true });
+*/
+async function runDeployWizard(ctx, options) {
+	const cwd = process.cwd();
+	ctx.state.render.heading("Checking prerequisites");
+	for (const item of diagnose(cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
+	await offerScaffold(ctx, diagnose(cwd));
+	await offerEnvScaffold(ctx, cwd);
+	const blockers = diagnose(cwd).filter((item) => !item.ok);
+	if (blockers.length > 0) {
+		ctx.state.render.heading("Not ready to deploy");
+		for (const item of blockers) ctx.state.render.check(false, item.label, item.detail);
+		ctx.state.render.warn(`Fix the ${blockers.length} item(s) above, then re-run \`bun run deploy\`.`);
+		return {
+			deployed: false,
+			reason: "blocked"
+		};
+	}
+	ctx.state.render.heading("Local test");
+	const summary = await ctx.require(buildPlugin).run();
+	ctx.state.render.check(true, `built ${summary.pageCount} pages → ${summary.outDir}/`);
+	const notFoundOk = existsSync(path.join(ctx.config.outDir, ctx.config.notFoundFile));
+	ctx.state.render.check(notFoundOk, `${ctx.config.notFoundFile} present`, notFoundOk ? void 0 : "Set build.notFound so the SSG emits it (CF Pages else flips to SPA mode).");
+	ctx.state.render.info("Tip: run `bun run preview` to eyeball the built site before deploying.");
+	const outcome = await runDeployStep(ctx, options);
+	await offerWorkflowSetup(ctx);
+	return outcome;
+}
+//#endregion
 //#region src/plugins/cli/errors.ts
 /** Error prefix for cli config/validation/runtime failures (spec/11 Part-3). */
 const ERROR_PREFIX$3 = "[web] cli";
@@ -6466,11 +6736,12 @@ function injectReloadClient(html) {
 	return index === -1 ? html + RELOAD_CLIENT : html.slice(0, index) + RELOAD_CLIENT + html.slice(index);
 }
 /**
-* Run one rebuild and report the result. Skips re-entrancy via the shared `building`
-* flag and routes success to `onReloaded`, failure to `onError`.
+* Run one rebuild and report the result. Announces the start (`onRebuildStart`), then
+* routes success to `onReloaded` and failure to `onError`.
 *
 * @param input - The rebuild dependencies + the changed file.
 * @param input.runBuild - Runs one build and resolves with its summary.
+* @param input.onRebuildStart - Called with the changed file just before the build runs.
 * @param input.onReloaded - Called with the changed file + summary after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @param input.file - The changed file to report alongside the summary.
@@ -6479,6 +6750,7 @@ function injectReloadClient(html) {
 * await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md" });
 */
 async function runOneRebuild(input) {
+	input.onRebuildStart?.(input.file);
 	try {
 		const summary = await input.runBuild();
 		input.onReloaded({
@@ -6500,6 +6772,7 @@ async function runOneRebuild(input) {
 * @param input - The rebuild dependencies.
 * @param input.debounceMs - Debounce window in milliseconds.
 * @param input.runBuild - Runs one build and resolves with its summary.
+* @param input.onRebuildStart - Called with the changed file just before each build runs.
 * @param input.onReloaded - Called with the changed file + summary after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @returns The debounced rebuild driver.
@@ -6526,6 +6799,7 @@ function createRebuilder(input) {
 			dirty = false;
 			await runOneRebuild({
 				runBuild: input.runBuild,
+				...input.onRebuildStart ? { onRebuildStart: input.onRebuildStart } : {},
 				onReloaded: input.onReloaded,
 				onError: input.onError,
 				file: pendingFile
@@ -6579,6 +6853,70 @@ function createRebuilder(input) {
 	};
 }
 /**
+* Whether a changed path (relative to a watched dir) is editor/OS noise that is never a
+* page source: any hidden segment (`.DS_Store`, anything under `.git/` or `.cache/`,
+* vim `.*.swp`) or a `~` backup file. Checks every segment, not just the basename.
+*
+* @param filename - The changed path relative to its watched directory.
+* @returns `true` when the change should be ignored as noise.
+* @example
+* isNoisePath(".git/HEAD"); // true
+*/
+function isNoisePath(filename) {
+	return filename.split(/[/\\]/).some((segment) => segment.startsWith(".")) || filename.endsWith("~");
+}
+/**
+* Create a {@link ChangeGate} that drops three kinds of spurious change events before
+* they reach the debounced rebuilder: editor/OS noise (dotfiles, backups), writes under
+* `outDir` (the build's own output — a loop guard), and the stale duplicate/parent-dir
+* echoes macOS fires for one save. Staleness is judged by a build-start high-water mark:
+* a change whose file mtime is at or before the last build we started was already
+* captured (or is a late echo), so it is ignored — while a genuinely newer edit (even
+* one made mid-build) and a deletion (missing file) always pass. The single timestamp
+* also means no per-path map grows over a long session.
+*
+* @param input - The gate dependencies.
+* @param input.outDir - The build output directory whose writes must never re-trigger a build.
+* @param input.fileMtime - Resolves a path's mtime in ms (or `null` when missing).
+* @param input.now - Monotonic wall clock (ms) used for the build-start high-water mark.
+* @returns The change gate.
+* @example
+* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock });
+*/
+function createChangeGate(input) {
+	const outDirAbs = path.resolve(input.outDir);
+	let lastBuildStartedAt = input.now();
+	return {
+		/**
+		* Decide whether a change beneath `dir` warrants a rebuild (see {@link ChangeGate.accept}).
+		*
+		* @param dir - The watched directory the event fired on.
+		* @param filename - The changed path relative to `dir` (or `undefined`).
+		* @returns `true` to schedule a rebuild, `false` to ignore.
+		* @example
+		* gate.accept("content", "post/en.md");
+		*/
+		accept(dir, filename) {
+			if (filename === void 0) return true;
+			if (isNoisePath(filename)) return false;
+			const changed = path.resolve(dir, filename);
+			if (changed === outDirAbs || changed.startsWith(`${outDirAbs}${path.sep}`)) return false;
+			const mtime = input.fileMtime(changed);
+			if (mtime !== null && mtime < lastBuildStartedAt) return false;
+			return true;
+		},
+		/**
+		* Advance the high-water mark to now (see {@link ChangeGate.markBuildStart}).
+		*
+		* @example
+		* gate.markBuildStart();
+		*/
+		markBuildStart() {
+			lastBuildStartedAt = input.now();
+		}
+	};
+}
+/**
 * Install SIGINT/SIGTERM handlers that run `teardown()` and resolve the returned
 * promise, so a long-running command (`serve`/`preview`) unblocks its `await` on
 * Ctrl-C / termination and detaches its own listeners. Used by both servers.
@@ -6610,18 +6948,45 @@ function installSignalTeardown(teardown) {
 const SSE_OPEN = ": connected\n\n";
 /** The SSE frame pushed to reload a connected browser. */
 const SSE_RELOAD = "event: reload\ndata: 1\n\n";
+/** The SSE comment frame sent on the heartbeat to keep an idle stream warm. */
+const SSE_PING = ": ping\n\n";
+/** Default heartbeat interval (ms): one ping well under any 30s+ proxy idle window. */
+const DEFAULT_HEARTBEAT_MS = 15e3;
 /**
 * Create a {@link ReloadHub} backed by `ReadableStream` controllers. Each `connect()`
 * enqueues into a new stream; `reloadAll()` writes the reload frame to every live
-* controller (dropping any that have closed).
+* controller (dropping any that have closed). A periodic heartbeat comment keeps idle
+* streams warm — belt-and-suspenders alongside the dev server's `idleTimeout: 0`, so a
+* quiet connection is never severed (which the browser surfaces as
+* `ERR_INCOMPLETE_CHUNKED_ENCODING` and then reconnects in a storm).
 *
+* @param options - Optional heartbeat tuning.
+* @param options.heartbeatMs - Heartbeat interval in ms (`0` disables). Default `15000`.
 * @returns The reload hub.
 * @example
 * const hub = createReloadHub();
 */
-function createReloadHub() {
+function createReloadHub(options = {}) {
 	const encoder = new TextEncoder();
 	const clients = /* @__PURE__ */ new Set();
+	/**
+	* Enqueue one frame to every live controller, dropping any that have closed.
+	*
+	* @param frame - The SSE wire text to broadcast.
+	* @example
+	* broadcast(SSE_RELOAD);
+	*/
+	const broadcast = (frame) => {
+		const bytes = encoder.encode(frame);
+		for (const controller of clients) try {
+			controller.enqueue(bytes);
+		} catch {
+			clients.delete(controller);
+		}
+	};
+	const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+	const heartbeat = heartbeatMs > 0 ? setInterval(() => broadcast(SSE_PING), heartbeatMs) : void 0;
+	heartbeat?.unref?.();
 	return {
 		/**
 		* Open one SSE connection, register its controller, and return the streaming
@@ -6669,11 +7034,7 @@ function createReloadHub() {
 		* hub.reloadAll();
 		*/
 		reloadAll() {
-			for (const controller of clients) try {
-				controller.enqueue(encoder.encode(SSE_RELOAD));
-			} catch {
-				clients.delete(controller);
-			}
+			broadcast(SSE_RELOAD);
 		},
 		/**
 		* The number of currently-connected clients.
@@ -6684,6 +7045,19 @@ function createReloadHub() {
 		*/
 		size() {
 			return clients.size;
+		},
+		/**
+		* Stop the heartbeat and close every live SSE stream (SIGINT/SIGTERM teardown).
+		*
+		* @example
+		* hub.close();
+		*/
+		close() {
+			if (heartbeat !== void 0) clearInterval(heartbeat);
+			for (const controller of clients) try {
+				controller.close();
+			} catch {}
+			clients.clear();
 		}
 	};
 }
@@ -6747,8 +7121,14 @@ async function runDevServer(ctx, port) {
 	const hub = createReloadHub();
 	const server = ctx.state.serveStatic({
 		port,
+		idleTimeout: 0,
 		fetch: createDevHandler(ctx, hub)
 	});
+	const gate = createChangeGate({
+		outDir: ctx.config.outDir,
+		fileMtime: ctx.state.fileMtime,
+		now: ctx.state.clock
+	});
 	const rebuilder = createRebuilder({
 		debounceMs: ctx.config.debounceMs,
 		/**
@@ -6762,6 +7142,17 @@ async function runDevServer(ctx, port) {
 			return ctx.require(buildPlugin).run();
 		},
 		/**
+		* Show the compact in-place "rebuilding {label}" line before the build runs.
+		*
+		* @param file - The changed watch target shown in the line.
+		* @example
+		* onRebuildStart("content");
+		*/
+		onRebuildStart(file) {
+			gate.markBuildStart();
+			ctx.state.render.rebuildStart(file);
+		},
+		/**
 		* Render the reload line and push a browser reload after a rebuild.
 		*
 		* @param info - The changed file plus the rebuild's page count and duration.
@@ -6783,7 +7174,9 @@ async function runDevServer(ctx, port) {
 			ctx.state.render.error("rebuild failed", error);
 		}
 	});
-	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, () => rebuilder.schedule(dir)));
+	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, (filename) => {
+		if (gate.accept(dir, filename)) rebuilder.schedule(dir);
+	}));
 	ctx.state.render.serverReady({
 		local: `http://localhost:${port}`,
 		network: ctx.state.networkUrl(port),
@@ -6792,7 +7185,9 @@ async function runDevServer(ctx, port) {
 	return installSignalTeardown(() => {
 		rebuilder.cancel();
 		for (const watcher of watchers) watcher.close();
+		hub.close();
 		server.stop();
+		ctx.state.render.dispose();
 	});
 }
 //#endregion
@@ -6993,6 +7388,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;
@@ -7051,29 +7468,37 @@ function createApi$1(ctx) {
 			return runPreviewServer(ctx, port);
 		},
 		/**
-		* Scaffold, then deploy. A y/N confirm is shown only when a human is present (an
-		* interactive TTY, with `CI` unset). Non-interactive runs (CI, or any non-TTY)
-		* skip the prompt and deploy, so the consumer scripts never hang a pipeline.
-		* `options.yes` forces the skip anywhere. An interactive "no" returns
-		* `{ deployed: false, reason: "declined" }`.
+		* Deploy to Cloudflare Pages. Two modes: `{ guided: true }` runs the interactive
+		* setup wizard (diagnose prerequisites, guide fixes, gate, local test, deploy, offer
+		* a CI workflow); the default direct path scaffolds, gates on a y/N confirm (shown
+		* only to an interactive TTY with `CI` unset — non-interactive runs proceed so a
+		* pipeline never hangs), then deploys. `options.yes` forces the skip. A "no" returns
+		* `{ deployed: false, reason: "declined" }`; the wizard may return `"blocked"`.
 		*
-		* @param options - Optional branch override and `yes` flag.
-		* @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+		* @param options - Optional branch override, `yes` flag, and `guided` toggle.
+		* @returns The deploy outcome (completed details, or a `declined`/`blocked` skip).
 		* @example
-		* await api.deploy({ branch: "preview/x", yes: true });
+		* await api.deploy({ guided: true });
 		*/
 		async deploy(options = {}) {
 			const { branch, yes = false } = options;
 			ctx.state.render.header("deploy");
-			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 })
-			};
+			if (options.guided === true) return runDeployWizard(ctx, options);
+			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;
+			}
 		}
 	};
 }
@@ -7164,6 +7589,61 @@ 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). */
+const CLEAR_BELOW = `${ESC}[0J`;
+/**
+* Braille spinner frames for live "working…" indicators on a TTY (advance one per tick).
+* Off a TTY the Panel never animates, so this is unused in plain/CI output.
+*/
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/**
+* The ANSI sequence to move the cursor up `n` lines (empty string for `n <= 0`). The
+* Panel uses it to repaint a live block in place — move up over the previous draw, then
+* rewrite each row — so progress updates a fixed region instead of scrolling new lines.
+*
+* @param n - Number of lines to move the cursor up.
+* @returns The cursor-up escape sequence, or `""` when `n <= 0`.
+* @example
+* cursorUp(3); // "\x1b[3A"
+*/
+function cursorUp(n) {
+	return n > 0 ? `${ESC}[${n}A` : "";
+}
 /** Unicode rounded box glyphs used when output is a color-capable TTY. */
 const UNICODE_BOX = {
 	topLeft: "╭",
@@ -7202,6 +7682,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.
@@ -7229,12 +7739,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,
 		/**
@@ -7314,23 +7826,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}`;
@@ -7345,13 +7873,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`).
 *
@@ -7366,22 +7951,177 @@ 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 = {}) {
 	const write = options.write ?? ((line) => console.log(line));
 	const writeError = options.writeError ?? ((line) => console.error(line));
+	const writeRaw = options.writeRaw ?? ((chunk) => {
+		process.stdout.write(chunk);
+	});
+	const now = options.now ?? Date.now;
 	const color = options.color ?? supportsColor();
-	const palette = makePalette(color);
+	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 idle = false;
+	let idleStartedAt = 0;
+	let serveMode = false;
+	let ticker;
+	/**
+	* 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).
+	* @example
+	* renderPhaseRow({ name: "pages", done: true, durationMs: 12 });
+	*/
+	const renderPhaseRow = (row) => {
+		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)}`;
+	};
+	/**
+	* 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();
+	*/
+	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 + 1;
+	};
+	/**
+	* Repaint the single in-place rebuild line (spinner + label + live elapsed seconds).
+	*
+	* @example
+	* paintRebuildLine();
+	*/
+	const paintRebuildLine = () => {
+		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}`);
+	};
+	/**
+	* 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 = () => {
+		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).
+	*
+	* @example
+	* startTicker();
+	*/
+	const startTicker = () => {
+		if (!color || ticker) return;
+		ticker = setInterval(onTick, TICK_MS);
+		ticker.unref?.();
+	};
+	/**
+	* Stop the animation ticker if running.
+	*
+	* @example
+	* stopTicker();
+	*/
+	const stopTicker = () => {
+		if (ticker) clearInterval(ticker);
+		ticker = void 0;
+	};
 	/**
 	* Write each line of a multi-line block through the stdout sink.
 	*
@@ -7392,82 +8132,184 @@ 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 live per-phase row from a `build:phase` event.
+		* 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
 		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
 		*/
 		phase(phase) {
+			if (rebuilding) return;
+			if (!color) {
+				if (phase.status === "done") write(`  ${palette.green("✓")} ${phase.phase}${durationSuffix(palette, phase.durationMs)}`);
+				return;
+			}
+			if (!phaseOpen) {
+				phaseRows = [];
+				phaseDrawn = 0;
+				phaseOpen = true;
+				blockStartedAt = now();
+			}
 			const done = phase.status === "done";
-			write(`  ${done ? palette.green("✓") : palette.dim("•")} ${done ? phase.phase : palette.dim(phase.phase)}${durationSuffix(palette, phase.durationMs)}`);
+			const existing = phaseRows.find((row) => row.name === phase.phase);
+			if (existing) {
+				existing.done = done;
+				existing.durationMs = phase.durationMs;
+			} else phaseRows.push({
+				name: phase.phase,
+				done,
+				durationMs: phase.durationMs
+			});
+			paintPhaseBlock();
+			startTicker();
 		},
 		/**
-		* Render the BUILD summary block from a `build:complete` event.
+		* 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
 		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
 		*/
 		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();
+			}
 		},
 		/**
-		* Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+		* Begin a serve() rebuild: show ONE compact "rebuilding {label}" line (an animated
+		* spinner with live elapsed on a TTY; a plain "~ {label}" line otherwise), 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
+		* render.rebuildStart("content");
+		*/
+		rebuildStart(label) {
+			rebuilding = true;
+			idle = false;
+			rebuildLabel = label;
+			rebuildStartedAt = now();
+			if (!color) {
+				write(`  ${palette.yellow("~")} ${label}`);
+				return;
+			}
+			paintRebuildLine();
+			startTicker();
+		},
+		/**
+		* Settle the current rebuild: replace the in-place "rebuilding…" line with a compact
+		* "✓ rebuilt N pages · Xms · reloaded", 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
 		* render.reload({ file: "content/a.md", pageCount: 12, durationMs: 84 });
 		*/
 		reload(info) {
-			write(`  ${palette.yellow("~")} ${info.file}`);
-			write(`  ${palette.green("✓")} rebuilt ${palette.bold(String(info.pageCount))} pages ${palette.dim(`· ${info.durationMs}ms · browser reloaded`)}`);
+			const settledRebuild = rebuilding;
+			rebuilding = false;
+			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.
@@ -7477,7 +8319,9 @@ function createPanelRenderer(options = {}) {
 		* render.info("watching for changes…");
 		*/
 		info(message) {
-			write(`  ${palette.cyan("›")} ${message}`);
+			const [first = "", ...rest] = message.split("\n");
+			write(`  ${palette.cyan("›")} ${first}`);
+			for (const line of rest) write(`    ${line}`);
 		},
 		/**
 		* Render a warning line (to stderr).
@@ -7490,7 +8334,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.
@@ -7498,8 +8343,53 @@ function createPanelRenderer(options = {}) {
 		* render.error("build failed", err);
 		*/
 		error(message, cause) {
+			const wasRebuilding = rebuilding;
+			if (rebuilding) {
+				rebuilding = false;
+				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 pink label) for a multi-step flow.
+		*
+		* @param text - The heading label.
+		* @example
+		* render.heading("Diagnostics");
+		*/
+		heading(text) {
+			write("");
+			write(`  ${palette.bold(palette.pink(text))}`);
+		},
+		/**
+		* Render a diagnostic line: green `✓` (pass) or red `✗` (fail) + label, with optional
+		* dim, indented detail beneath (e.g. a fix hint for a failing check).
+		*
+		* @param ok - Whether the check passed.
+		* @param label - The check label.
+		* @param detail - Optional multi-line guidance shown indented under the line.
+		* @example
+		* render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
+		*/
+		check(ok, label, detail) {
+			write(`  ${ok ? palette.green("✓") : palette.red("✗")} ${label}`);
+			if (detail !== void 0) for (const line of detail.split("\n")) write(`      ${palette.dim(line)}`);
+		},
+		/**
+		* 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;
 		}
 	};
 }
@@ -7578,18 +8468,44 @@ function defaultConfirm(question) {
 	});
 }
 /**
+* Default stdin single-choice prompt. Prints the choices numbered from 1, reads a line
+* via `node:readline`, and resolves the chosen zero-based index (empty / out-of-range
+* falls back to 0). Tests inject a canned selection so no real TTY interaction occurs.
+*
+* @param question - The prompt to display.
+* @param choices - The selectable option labels.
+* @returns Resolves the chosen zero-based index.
+* @example
+* await defaultSelect("Trigger?", ["Auto on push", "Manual only"]);
+*/
+function defaultSelect(question, choices) {
+	return new Promise((resolve) => {
+		const readline = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		for (const [index, choice] of choices.entries()) console.log(`  ${index + 1}) ${choice}`);
+		readline.question(`${question} [1-${choices.length}] `, (answer) => {
+			readline.close();
+			const picked = Number.parseInt(answer.trim(), 10);
+			resolve(Number.isInteger(picked) && picked >= 1 && picked <= choices.length ? picked - 1 : 0);
+		});
+	});
+}
+/**
 * Default recursive directory watcher — wraps `node:fs.watch` with `{ recursive: true }`
 * and adapts its handle to {@link WatchHandle}. Tests inject a fake emitter so no real
 * FS watch is registered.
 *
 * @param dir - The directory to watch recursively.
-* @param onChange - Invoked on any change beneath `dir`.
+* @param onChange - Invoked on any change beneath `dir`, forwarding the changed path
+*   relative to `dir` when `node:fs.watch` reports it (`undefined` otherwise).
 * @returns A handle whose `close()` detaches the watcher.
 * @example
-* const handle = defaultWatch("content", () => rebuild());
+* const handle = defaultWatch("content", file => rebuild(file));
 */
 function defaultWatch(dir, onChange) {
-	const watcher = watch(dir, { recursive: true }, () => onChange());
+	const watcher = watch(dir, { recursive: true }, (_event, filename) => onChange(typeof filename === "string" ? filename : void 0));
 	return { 
 	/**
 	* Detach the underlying `node:fs.watch` listener.
@@ -7602,6 +8518,23 @@ close() {
 	} };
 }
 /**
+* Default file-mtime probe — `node:fs.statSync(path).mtimeMs`, returning `null` for a
+* missing path (so a deleted file still reads as a change). serve() compares this
+* across `fs.watch` events to drop the duplicate notifications macOS fires per save.
+*
+* @param filePath - The absolute path to stat.
+* @returns The modification time in epoch milliseconds, or `null` when absent.
+* @example
+* const mtime = defaultFileMtime("/abs/content/a.md");
+*/
+function defaultFileMtime(filePath) {
+	try {
+		return statSync(filePath).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+/**
 * Default LAN network-URL deriver — wraps {@link networkUrl} so the production seam
 * reads `node:os` interfaces while tests can inject a deterministic value.
 *
@@ -7613,6 +8546,101 @@ close() {
 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,
@@ -7626,14 +8654,20 @@ 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,
 		watch: defaultWatch,
 		serveStatic: defaultServeStatic,
 		fileResponse: defaultFileResponse,
-		networkUrl: defaultNetworkUrl
+		networkUrl: defaultNetworkUrl,
+		fileMtime: defaultFileMtime
 	};
 }
 //#endregion