@moku-labs/web 1.0.1 → 1.1.0

package/dist/index.cjs

@@ -5774,6 +5774,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`
@@ -5783,9 +5796,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 })\`.
@@ -5793,10 +5807,7 @@ function generateGithubWorkflow(input) {
 
 name: Deploy
 
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
+${TRIGGER_ON_BLOCKS[input.trigger ?? "auto"]}
 
 permissions:
   contents: read
@@ -5928,7 +5939,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,
@@ -6446,6 +6460,185 @@ const deployPlugin = createPlugin$1("deploy", {
 	api: createApi$2
 });
 //#endregion
+//#region src/plugins/cli/deploy-wizard.ts
+/**
+* @file cli plugin — the guided deploy wizard (`cli.deploy({ guided: true })`). Walks a
+* human through a Cloudflare Pages deploy: checks prerequisites (wrangler config + the
+* Cloudflare credentials) with concrete fix guidance, offers to scaffold/build what is
+* missing, HARD-GATES the deploy on everything being green, runs a local build smoke
+* test, confirms, deploys, then offers to scaffold a GitHub Actions workflow (auto on
+* push to main, or a versioned/manual trigger). The non-guided `--cli` path stays in
+* `api.ts`. Every prompt + line of output flows through injectable `state` seams.
+*/
+/** How to create a Cloudflare API token + where to make it available locally. */
+const TOKEN_HELP = [
+	"Create one at https://dash.cloudflare.com/profile/api-tokens → Create Token →",
+	"use the \"Cloudflare Pages — Edit\" template (or a custom token with the",
+	"Account › Cloudflare Pages › Edit permission). Then make it available:",
+	"  export CLOUDFLARE_API_TOKEN=…   (shell)   or add it to .env (gitignored)."
+].join("\n");
+/** Where to find the Cloudflare account id + where to make it available locally. */
+const ACCOUNT_HELP = [
+	"Find it on the Cloudflare dashboard → Workers & Pages: the Account ID is in the",
+	"right-hand sidebar (also in the dashboard URL). Then make it available:",
+	"  export CLOUDFLARE_ACCOUNT_ID=…   or add it to .env."
+].join("\n");
+/** The GitHub repo secrets the generated workflow consumes. */
+const SECRETS_HELP = ["Add these repo secrets (GitHub → Settings → Secrets and variables → Actions):", "CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID"].join("\n");
+/**
+* Evaluate the three deploy prerequisites against the current project: the Cloudflare
+* wrangler config exists, and both Cloudflare credentials are present in the environment.
+*
+* @param cwd - The project root (where `wrangler.jsonc` lives).
+* @returns The ordered prerequisite checks.
+* @example
+* const prereqs = diagnose(process.cwd());
+*/
+function diagnose(cwd) {
+	const wranglerOk = (0, node_fs.existsSync)(node_path$1.default.join(cwd, "wrangler.jsonc"));
+	const tokenOk = (process.env.CLOUDFLARE_API_TOKEN ?? "") !== "";
+	const accountOk = (process.env.CLOUDFLARE_ACCOUNT_ID ?? "") !== "";
+	return [
+		{
+			ok: wranglerOk,
+			label: "wrangler.jsonc (Cloudflare project config)",
+			detail: wranglerOk ? void 0 : "Missing — scaffold it (offered below) or run app.deploy.init().",
+			scaffoldable: true
+		},
+		{
+			ok: tokenOk,
+			label: "CLOUDFLARE_API_TOKEN is set",
+			detail: tokenOk ? void 0 : TOKEN_HELP,
+			scaffoldable: false
+		},
+		{
+			ok: accountOk,
+			label: "CLOUDFLARE_ACCOUNT_ID is set",
+			detail: accountOk ? void 0 : ACCOUNT_HELP,
+			scaffoldable: false
+		}
+	];
+}
+/**
+* Offer to scaffold a missing `wrangler.jsonc` (the only auto-fixable prerequisite),
+* generating it via the deploy plugin when the user accepts.
+*
+* @param ctx - The cli plugin context.
+* @param prereqs - The current prerequisite checks.
+* @returns Resolves once any accepted fix has run.
+* @example
+* await offerScaffold(ctx, diagnose(cwd));
+*/
+async function offerScaffold(ctx, prereqs) {
+	if (!prereqs.some((item) => item.scaffoldable && !item.ok)) return;
+	if (!await ctx.state.confirm("Scaffold wrangler.jsonc now?")) return;
+	await ctx.require(deployPlugin).init({});
+	ctx.state.render.check(true, "wrangler.jsonc scaffolded");
+}
+/**
+* Map a top-level workflow choice (and, for the versioned option, a sub-choice) to the
+* concrete {@link WorkflowTrigger}, or `null` when the user chose to skip setup.
+*
+* @param ctx - The cli plugin context (for the follow-up sub-choice prompt).
+* @param choice - The selected zero-based index of the top-level options.
+* @returns The resolved trigger, or `null` to skip.
+* @example
+* const trigger = await resolveTrigger(ctx, 1);
+*/
+async function resolveTrigger(ctx, choice) {
+	if (choice === 2) return null;
+	if (choice === 0) return "auto";
+	return await ctx.state.select("How should the versioned deploy be triggered?", ["On a version tag push (v*) + the manual Run-workflow button", "Manual Run-workflow button only (workflow_dispatch)"]) === 0 ? "versioned-tag" : "dispatch";
+}
+/**
+* Offer to scaffold a GitHub Actions deploy workflow, letting the user choose how it is
+* triggered, then remind them which repo secrets to add. A no-op past a "skip" choice.
+*
+* @param ctx - The cli plugin context.
+* @returns Resolves once any chosen workflow has been scaffolded.
+* @example
+* await offerWorkflowSetup(ctx);
+*/
+async function offerWorkflowSetup(ctx) {
+	ctx.state.render.heading("Automate future deploys (GitHub Actions)");
+	const trigger = await resolveTrigger(ctx, await ctx.state.select("Set up a deploy workflow?", [
+		"Auto-deploy on every push to main",
+		"Manual / versioned deploy (choose trigger)",
+		"Skip for now"
+	]));
+	if (trigger === null) return;
+	const result = await ctx.require(deployPlugin).init({
+		ci: true,
+		workflowTrigger: trigger
+	});
+	const workflowPath = ".github/workflows/deploy.yml";
+	const wrote = result.written.includes(workflowPath);
+	ctx.state.render.check(true, wrote ? `wrote ${workflowPath}` : `${workflowPath} already exists (left unchanged)`);
+	ctx.state.render.info(SECRETS_HELP);
+}
+/**
+* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin and
+* report the outcome. A declined confirm returns `{ deployed: false, reason: "declined" }`.
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override + `yes`).
+* @returns The deploy outcome.
+* @example
+* const outcome = await runDeployStep(ctx, { yes: true });
+*/
+async function runDeployStep(ctx, options) {
+	ctx.state.render.heading("Deploy");
+	if (!(options.yes === true || await ctx.state.confirm(`Deploy ${ctx.config.outDir}/ to Cloudflare Pages now?`))) {
+		ctx.state.render.warn("deploy skipped");
+		return {
+			deployed: false,
+			reason: "declined"
+		};
+	}
+	return {
+		deployed: true,
+		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
+	};
+}
+/**
+* Run the guided deploy wizard end to end: diagnose prerequisites (offering to scaffold
+* the wrangler config), HARD-GATE on the remaining blockers, run a local build smoke
+* test, deploy (with confirmation), then offer to scaffold a CI workflow. Returns
+* `{ deployed: false, reason: "blocked" }` when prerequisites are unmet, so a thin script
+* can exit non-zero. Assumes the caller already rendered the `deploy` header.
+*
+* @param ctx - The cli plugin context (state seams + `require` + config).
+* @param options - The deploy options (branch override, `yes`, `guided`).
+* @returns The deploy outcome (`deployed`, or a `declined`/`blocked` skip).
+* @example
+* const outcome = await runDeployWizard(ctx, { guided: true });
+*/
+async function runDeployWizard(ctx, options) {
+	const cwd = process.cwd();
+	ctx.state.render.heading("Checking prerequisites");
+	for (const item of diagnose(cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
+	await offerScaffold(ctx, diagnose(cwd));
+	const blockers = diagnose(cwd).filter((item) => !item.ok);
+	if (blockers.length > 0) {
+		ctx.state.render.heading("Not ready to deploy");
+		for (const item of blockers) ctx.state.render.check(false, item.label, item.detail);
+		ctx.state.render.warn(`Fix the ${blockers.length} item(s) above, then re-run \`bun run deploy\`.`);
+		return {
+			deployed: false,
+			reason: "blocked"
+		};
+	}
+	ctx.state.render.heading("Local test");
+	const summary = await ctx.require(buildPlugin).run();
+	ctx.state.render.check(true, `built ${summary.pageCount} pages → ${summary.outDir}/`);
+	const notFoundOk = (0, node_fs.existsSync)(node_path$1.default.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";
@@ -6479,11 +6672,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.
@@ -6492,6 +6686,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({
@@ -6513,6 +6708,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.
@@ -6539,6 +6735,7 @@ function createRebuilder(input) {
 			dirty = false;
 			await runOneRebuild({
 				runBuild: input.runBuild,
+				...input.onRebuildStart ? { onRebuildStart: input.onRebuildStart } : {},
 				onReloaded: input.onReloaded,
 				onError: input.onError,
 				file: pendingFile
@@ -6592,6 +6789,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 = node_path$1.default.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 = node_path$1.default.resolve(dir, filename);
+			if (changed === outDirAbs || changed.startsWith(`${outDirAbs}${node_path$1.default.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.
@@ -6623,18 +6884,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
@@ -6682,11 +6970,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.
@@ -6697,6 +6981,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();
 		}
 	};
 }
@@ -6760,8 +7057,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,
 		/**
@@ -6775,6 +7078,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.
@@ -6796,7 +7110,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),
@@ -6805,6 +7121,7 @@ async function runDevServer(ctx, port) {
 	return installSignalTeardown(() => {
 		rebuilder.cancel();
 		for (const watcher of watchers) watcher.close();
+		hub.close();
 		server.stop();
 	});
 }
@@ -7064,20 +7381,22 @@ function createApi$1(ctx) {
 			return runPreviewServer(ctx, port);
 		},
 		/**
-		* Scaffold, then deploy. A y/N confirm is shown only when a human is present (an
-		* interactive TTY, with `CI` unset). Non-interactive runs (CI, or any non-TTY)
-		* skip the prompt and deploy, so the consumer scripts never hang a pipeline.
-		* `options.yes` forces the skip anywhere. An interactive "no" returns
-		* `{ deployed: false, reason: "declined" }`.
+		* Deploy to Cloudflare Pages. Two modes: `{ guided: true }` runs the interactive
+		* setup wizard (diagnose prerequisites, guide fixes, gate, local test, deploy, offer
+		* a CI workflow); the default direct path scaffolds, gates on a y/N confirm (shown
+		* only to an interactive TTY with `CI` unset — non-interactive runs proceed so a
+		* pipeline never hangs), then deploys. `options.yes` forces the skip. A "no" returns
+		* `{ deployed: false, reason: "declined" }`; the wizard may return `"blocked"`.
 		*
-		* @param options - Optional branch override and `yes` flag.
-		* @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+		* @param options - Optional branch override, `yes` flag, and `guided` toggle.
+		* @returns The deploy outcome (completed details, or a `declined`/`blocked` skip).
 		* @example
-		* await api.deploy({ branch: "preview/x", yes: true });
+		* await api.deploy({ guided: true });
 		*/
 		async deploy(options = {}) {
 			const { branch, yes = false } = options;
 			ctx.state.render.header("deploy");
+			if (options.guided === true) return runDeployWizard(ctx, options);
 			await ctx.require(deployPlugin).init({ ci: true });
 			if (!await confirmDeploy(ctx, yes)) return {
 				deployed: false,
@@ -7177,6 +7496,39 @@ const ANSI = {
 	cyan: `${ESC}[36m`,
 	gray: `${ESC}[90m`
 };
+/** ANSI: erase the entire current line, leaving the cursor where it is. */
+const CLEAR_LINE = `${ESC}[2K`;
+/** ANSI: erase from the cursor to the end of the screen (drops stale trailing rows). */
+const CLEAR_BELOW = `${ESC}[0J`;
+/**
+* Braille spinner frames for live "working…" indicators on a TTY (advance one per tick).
+* Off a TTY the Panel never animates, so this is unused in plain/CI output.
+*/
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/**
+* The ANSI sequence to move the cursor up `n` lines (empty string for `n <= 0`). The
+* Panel uses it to repaint a live block in place — move up over the previous draw, then
+* rewrite each row — so progress updates a fixed region instead of scrolling new lines.
+*
+* @param n - Number of lines to move the cursor up.
+* @returns The cursor-up escape sequence, or `""` when `n <= 0`.
+* @example
+* cursorUp(3); // "\x1b[3A"
+*/
+function cursorUp(n) {
+	return n > 0 ? `${ESC}[${n}A` : "";
+}
 /** Unicode rounded box glyphs used when output is a color-capable TTY. */
 const UNICODE_BOX = {
 	topLeft: "╭",
@@ -7393,8 +7745,97 @@ function durationSuffix(palette, durationMs) {
 function createPanelRenderer(options = {}) {
 	const write = options.write ?? ((line) => console.log(line));
 	const writeError = options.writeError ?? ((line) => console.error(line));
+	const writeRaw = options.writeRaw ?? ((chunk) => {
+		process.stdout.write(chunk);
+	});
+	const now = options.now ?? Date.now;
 	const color = options.color ?? supportsColor();
 	const palette = makePalette(color);
+	let phaseRows = [];
+	let phaseDrawn = 0;
+	let phaseOpen = false;
+	let rebuilding = false;
+	let rebuildLabel = "";
+	let rebuildStartedAt = 0;
+	let spinnerFrame = 0;
+	let ticker;
+	/**
+	* The current spinner glyph (with a static fallback under `noUncheckedIndexedAccess`).
+	*
+	* @returns The active braille spinner frame.
+	* @example
+	* frameGlyph(); // "⠙"
+	*/
+	const frameGlyph = () => SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length] ?? "⠋";
+	/**
+	* Render one phase row: a green `✓ name · time` when done, else a spinning cyan glyph
+	* before the dim name.
+	*
+	* @param row - The phase row to render.
+	* @returns The rendered row line (no trailing newline).
+	* @example
+	* renderPhaseRow({ name: "pages", done: true, durationMs: 12 });
+	*/
+	const renderPhaseRow = (row) => {
+		if (row.done) return `  ${palette.green("✓")} ${row.name}${durationSuffix(palette, row.durationMs)}`;
+		return `  ${palette.cyan(frameGlyph())} ${palette.dim(row.name)}`;
+	};
+	/**
+	* Repaint the live phase block in place: move up over the prior draw, then rewrite each
+	* row (clearing any stale trailing lines).
+	*
+	* @example
+	* paintPhaseBlock();
+	*/
+	const paintPhaseBlock = () => {
+		let frame = cursorUp(phaseDrawn);
+		for (const row of phaseRows) frame += `${CLEAR_LINE}${renderPhaseRow(row)}\n`;
+		writeRaw(frame + CLEAR_BELOW);
+		phaseDrawn = phaseRows.length;
+	};
+	/**
+	* Repaint the single in-place rebuild line (spinner + label + live elapsed seconds).
+	*
+	* @example
+	* paintRebuildLine();
+	*/
+	const paintRebuildLine = () => {
+		const elapsed = ((now() - rebuildStartedAt) / 1e3).toFixed(1);
+		const meta = palette.dim(`· ${elapsed}s`);
+		writeRaw(`\r${CLEAR_LINE}  ${palette.cyan(frameGlyph())} rebuilding ${rebuildLabel} ${meta}`);
+	};
+	/**
+	* Advance the spinner one frame and repaint whichever live region is active.
+	*
+	* @example
+	* onTick();
+	*/
+	const onTick = () => {
+		spinnerFrame += 1;
+		if (rebuilding) paintRebuildLine();
+		else if (phaseOpen) paintPhaseBlock();
+	};
+	/**
+	* Start the animation ticker (TTY only; idempotent; `unref`'d so it never blocks exit).
+	*
+	* @example
+	* startTicker();
+	*/
+	const startTicker = () => {
+		if (!color || ticker) return;
+		ticker = setInterval(onTick, 80);
+		ticker.unref?.();
+	};
+	/**
+	* Stop the animation ticker if running.
+	*
+	* @example
+	* stopTicker();
+	*/
+	const stopTicker = () => {
+		if (ticker) clearInterval(ticker);
+		ticker = void 0;
+	};
 	/**
 	* Write each line of a multi-line block through the stdout sink.
 	*
@@ -7417,15 +7858,38 @@ function createPanelRenderer(options = {}) {
 			writeBlock(box([`${palette.bold(palette.cyan("MOKU WEB"))}  ${palette.dim(COMMAND_LABEL[command])}`], color));
 		},
 		/**
-		* Render a live per-phase row from a `build:phase` event.
+		* Render a per-phase row from a `build:phase` event. On a TTY each phase is ONE row
+		* that updates in place (spinning glyph while running → green ✓ + duration when done);
+		* off a TTY one line is printed per completed phase (no start/done duplication). A
+		* no-op while a serve() rebuild is in flight — those show the compact rebuild line.
 		*
 		* @param phase - The `build:phase` payload.
 		* @example
 		* render.phase({ phase: "pages", status: "done", durationMs: 12 });
 		*/
 		phase(phase) {
+			if (rebuilding) return;
+			if (!color) {
+				if (phase.status === "done") write(`  ${palette.green("✓")} ${phase.phase}${durationSuffix(palette, phase.durationMs)}`);
+				return;
+			}
+			if (!phaseOpen) {
+				phaseRows = [];
+				phaseDrawn = 0;
+				phaseOpen = true;
+			}
 			const done = phase.status === "done";
-			write(`  ${done ? palette.green("✓") : palette.dim("•")} ${done ? phase.phase : palette.dim(phase.phase)}${durationSuffix(palette, phase.durationMs)}`);
+			const existing = phaseRows.find((row) => row.name === phase.phase);
+			if (existing) {
+				existing.done = done;
+				existing.durationMs = phase.durationMs;
+			} else phaseRows.push({
+				name: phase.phase,
+				done,
+				durationMs: phase.durationMs
+			});
+			paintPhaseBlock();
+			startTicker();
 		},
 		/**
 		* Render the BUILD summary block from a `build:complete` event.
@@ -7435,6 +7899,10 @@ function createPanelRenderer(options = {}) {
 		* render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
 		*/
 		built(summary) {
+			if (rebuilding) return;
+			phaseOpen = false;
+			phaseDrawn = 0;
+			stopTicker();
 			const pages = palette.bold(String(summary.pageCount));
 			writeBlock(box([
 				`${palette.green("✓")} ${palette.bold("BUILD")} complete`,
@@ -7456,15 +7924,47 @@ function createPanelRenderer(options = {}) {
 			writeBlock(box(lines, color));
 		},
 		/**
-		* Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+		* Begin a serve() rebuild: show ONE compact "rebuilding {label}" line (an animated
+		* spinner with live elapsed on a TTY; a plain "~ {label}" line otherwise) and mute
+		* the verbose phase rows + BUILD box until {@link reload}/{@link error} settles it.
+		*
+		* @param label - The changed watch target shown in the line.
+		* @example
+		* render.rebuildStart("content");
+		*/
+		rebuildStart(label) {
+			rebuilding = true;
+			rebuildLabel = label;
+			rebuildStartedAt = now();
+			spinnerFrame = 0;
+			if (!color) {
+				write(`  ${palette.yellow("~")} ${label}`);
+				return;
+			}
+			paintRebuildLine();
+			startTicker();
+		},
+		/**
+		* Settle the current rebuild: replace the in-place "rebuilding…" line with a compact
+		* "✓ rebuilt N pages · Xms · reloaded" (on a TTY) and re-enable verbose build output.
+		* Called standalone (no preceding {@link rebuildStart}) it also prints the "~ file"
+		* line so the changed target stays visible.
 		*
 		* @param info - The changed file plus the rebuild's page count and duration.
 		* @example
 		* render.reload({ file: "content/a.md", pageCount: 12, durationMs: 84 });
 		*/
 		reload(info) {
-			write(`  ${palette.yellow("~")} ${info.file}`);
-			write(`  ${palette.green("✓")} rebuilt ${palette.bold(String(info.pageCount))} pages ${palette.dim(`· ${info.durationMs}ms · browser reloaded`)}`);
+			const settledRebuild = rebuilding;
+			rebuilding = false;
+			stopTicker();
+			const line = `  ${palette.green("✓")} rebuilt ${palette.bold(String(info.pageCount))} pages ${palette.dim(`· ${info.durationMs}ms · reloaded`)}`;
+			if (settledRebuild && color) {
+				writeRaw(`\r${CLEAR_LINE}${line}\n`);
+				return;
+			}
+			if (!settledRebuild) write(`  ${palette.yellow("~")} ${info.file}`);
+			write(line);
 		},
 		/**
 		* Render the deploy result panel from a `deploy:complete` event.
@@ -7490,7 +7990,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).
@@ -7511,8 +8013,38 @@ function createPanelRenderer(options = {}) {
 		* render.error("build failed", err);
 		*/
 		error(message, cause) {
+			if (rebuilding) {
+				rebuilding = false;
+				stopTicker();
+				if (color) writeRaw(`\r${CLEAR_LINE}`);
+			}
 			writeError(`  ${palette.red("✗")} ${message}`);
 			if (cause !== void 0) writeError(String(cause));
+		},
+		/**
+		* Render a section heading (a blank line + a bold cyan label) for a multi-step flow.
+		*
+		* @param text - The heading label.
+		* @example
+		* render.heading("Diagnostics");
+		*/
+		heading(text) {
+			write("");
+			write(`  ${palette.bold(palette.cyan(text))}`);
+		},
+		/**
+		* Render a diagnostic line: green `✓` (pass) or red `✗` (fail) + label, with optional
+		* dim, indented detail beneath (e.g. a fix hint for a failing check).
+		*
+		* @param ok - Whether the check passed.
+		* @param label - The check label.
+		* @param detail - Optional multi-line guidance shown indented under the line.
+		* @example
+		* render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
+		*/
+		check(ok, label, detail) {
+			write(`  ${ok ? palette.green("✓") : palette.red("✗")} ${label}`);
+			if (detail !== void 0) for (const line of detail.split("\n")) write(`      ${palette.dim(line)}`);
 		}
 	};
 }
@@ -7591,18 +8123,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 = (0, node_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 = (0, node_fs.watch)(dir, { recursive: true }, () => onChange());
+	const watcher = (0, node_fs.watch)(dir, { recursive: true }, (_event, filename) => onChange(typeof filename === "string" ? filename : void 0));
 	return { 
 	/**
 	* Detach the underlying `node:fs.watch` listener.
@@ -7615,6 +8173,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 (0, node_fs.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.
 *
@@ -7642,11 +8217,13 @@ function createState$1(_ctx) {
 	return {
 		render: createPanelRenderer(),
 		confirm: defaultConfirm,
+		select: defaultSelect,
 		clock: Date.now,
 		watch: defaultWatch,
 		serveStatic: defaultServeStatic,
 		fileResponse: defaultFileResponse,
-		networkUrl: defaultNetworkUrl
+		networkUrl: defaultNetworkUrl,
+		fileMtime: defaultFileMtime
 	};
 }
 //#endregion