@moku-labs/web 1.1.0 → 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 {
@@ -6449,13 +6487,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 = [
@@ -6522,6 +6561,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.
@@ -6605,6 +6681,7 @@ async function runDeployWizard(ctx, options) {
 	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");
@@ -7110,6 +7187,7 @@ async function runDevServer(ctx, port) {
 		for (const watcher of watchers) watcher.close();
 		hub.close();
 		server.stop();
+		ctx.state.render.dispose();
 	});
 }
 //#endregion
@@ -7310,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;
@@ -7384,15 +7484,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 +7589,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 +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.
@@ -7581,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,
 		/**
@@ -7666,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}`;
@@ -7697,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`).
 *
@@ -7718,15 +7951,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 +8004,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 +8029,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 +8064,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 +8075,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}`);
+	};
+	/**
+	* 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 the spinner one frame and repaint whichever live region is active.
+	* 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 +8109,7 @@ function createPanelRenderer(options = {}) {
 	*/
 	const startTicker = () => {
 		if (!color || ticker) return;
-		ticker = setInterval(onTick, 80);
+		ticker = setInterval(onTick, TICK_MS);
 		ticker.unref?.();
 	};
 	/**
@@ -7833,22 +8132,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 +8188,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 +8204,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 +8214,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 +8267,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 +8279,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 +8290,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 +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.
@@ -8000,16 +8343,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 +8362,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 +8377,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;
 		}
 	};
 }
@@ -8188,6 +8546,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 +8654,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,