@moku-labs/web 1.2.0 → 1.3.1

package/dist/index.cjs

@@ -1295,18 +1295,24 @@ function isPublished(article, isProduction) {
 * locale collection: existing files only, drafts dropped in production, sorted
 * date-descending. The single load+filter+sort step behind {@link createContentApi.loadAll}.
 *
+* When a `cached` map is supplied (incremental dev rebuild), a slug already present in it
+* is reused as-is (skipping the re-read + Markdown/Shiki re-render); only slugs absent
+* from it — the ones a preceding `invalidate()` dropped, plus any never-loaded — are
+* resolved fresh. With no `cached` map every slug is resolved (the full load).
+*
 * @param ctx - Kernel-free domain context (provider + i18n helpers + stage).
 * @param slugs - Every known article slug from the provider.
 * @param locale - The locale to resolve and collect.
+* @param cached - Optional per-locale article cache to reuse for unchanged slugs.
 * @returns The published (date-descending) articles for this locale.
 * @example
 * ```ts
 * const present = await loadAndFilterArticles(ctx, slugs, "en");
 * ```
 */
-async function loadAndFilterArticles(ctx, slugs, locale) {
+async function loadAndFilterArticles(ctx, slugs, locale, cached) {
 	const isProduction = ctx.global.stage === "production";
-	return (await Promise.all(slugs.map((slug) => resolveArticle(ctx, slug, locale)))).filter((article) => article !== null).filter((article) => isPublished(article, isProduction)).toSorted(byDateDescending);
+	return (await Promise.all(slugs.map((slug) => cached?.get(slug) ?? resolveArticle(ctx, slug, locale)))).filter((article) => article !== null).filter((article) => isPublished(article, isProduction)).toSorted(byDateDescending);
 }
 /**
 * Derive the article slug from a source file path — the parent directory name
@@ -1343,19 +1349,31 @@ function createContentApi(ctx) {
 		* Load every article across every active locale (locale fallback, production
 		* draft exclusion, date sort, `contentId` after sort), cache them, emit `content:ready`.
 		*
+		* Cache-first by default: repeated calls return the per-build memo (list-route loaders
+		* call this once PER PAGE — without the memo every page would re-read + re-render every
+		* article, the dev-loop killer), and a rebuild after `invalidate()` re-resolves only the
+		* dropped slugs while reusing the cached articles for the rest (`contentId` ordinals are
+		* still recomputed across the FULL sorted set, so ids + order match a full load). Pass
+		* `{ reuse: false }` to force a FRESH full reload (cold build / an unclassifiable change
+		* where the caller cannot pinpoint what changed) — this bypasses the memo + per-slug cache.
+		*
+		* @param options - Optional load behaviour (`reuse`, default `true`).
 		* @returns A locale-keyed map of date-descending articles.
 		* @example
 		* ```ts
 		* const byLocale = await api.loadAll();
 		* ```
 		*/
-		async loadAll() {
+		async loadAll(options) {
+			const reuse = options?.reuse !== false;
+			const memo = ctx.state.loadedAll;
+			if (reuse && memo !== null) return memo;
 			const slugs = await ctx.provider.slugs();
 			const locales = ctx.locales();
 			const result = /* @__PURE__ */ new Map();
 			let total = 0;
 			for (const locale of locales) {
-				const present = await loadAndFilterArticles(ctx, slugs, locale);
+				const present = await loadAndFilterArticles(ctx, slugs, locale, reuse ? ctx.state.articles.get(locale) : void 0);
 				const cache = /* @__PURE__ */ new Map();
 				let index = 0;
 				for (const article of present) {
@@ -1367,6 +1385,7 @@ function createContentApi(ctx) {
 				result.set(locale, present);
 				total += present.length;
 			}
+			ctx.state.loadedAll = result;
 			ctx.emit("content:ready", {
 				locales,
 				articleCount: total
@@ -1430,6 +1449,7 @@ function createContentApi(ctx) {
 				if (slug === void 0) continue;
 				for (const cache of ctx.state.articles.values()) cache.delete(slug);
 			}
+			if (accepted.length > 0) ctx.state.loadedAll = null;
 			ctx.emit("content:invalidated", { paths: accepted });
 		},
 		/**
@@ -1499,14 +1519,17 @@ const contentEvents = (register) => ({
 * @param _ctx - Minimal context with global and config.
 * @param _ctx.global - Global plugin registry.
 * @param _ctx.config - Resolved plugin configuration.
-* @returns Fresh content shell state: an empty article cache.
+* @returns Fresh content shell state: an empty article cache + an empty loadAll memo.
 * @example
 * ```ts
 * const state = createContentState({ global: {}, config: { providers: [] } });
 * ```
 */
 function createContentState(_ctx) {
-	return { articles: /* @__PURE__ */ new Map() };
+	return {
+		articles: /* @__PURE__ */ new Map(),
+		loadedAll: null
+	};
 }
 //#endregion
 //#region src/plugins/content/validate.ts
@@ -3356,7 +3379,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 /**
 * Bundles CSS and JS into the output directory via two separate runner passes
 * (dodging Bun's mixed-entrypoint segfault), honoring `config.minify`, and caches
-* the resulting hashed asset paths in `state.buildCache` for downstream phases.
+* the resulting hashed asset paths in `state.buildCache` for downstream phases. The
+* two passes run CONCURRENTLY (`Promise.all`) — they target disjoint hashed outputs
+* and distinct `buildCache` keys (`css`/`js`), so overlapping them ~halves bundle
+* wall-time with no shared-state hazard. The CSS pass is still dispatched first, so
+* the runner's invocation order stays css-then-js.
 *
 * @param ctx - Plugin context (provides `state`, `config`, `log`).
 * @param options - Optional dependency-injection seam (runner + entrypoints).
@@ -3369,10 +3396,10 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const assetsDir = node_path$1.default.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await runOne(ctx, runner, "css", cssEntrypoints, outDir, node_path$1.default.join(outDir, "assets"), minify);
-	await runOne(ctx, runner, "js", jsEntrypoints, outDir, node_path$1.default.join(outDir, "assets"), minify);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
 }
 //#endregion
 //#region src/plugins/build/phases/content.ts
@@ -3389,15 +3416,24 @@ const CONTENT_CACHE_KEY = "content";
 * pages/feeds/og-images phases. Performs NO Markdown parsing itself — the
 * content plugin owns rendering (god-plugin invariant).
 *
+* On a dev incremental rebuild (`options.changed` set) it first `invalidate()`s the
+* changed Markdown so `loadAll({ reuse: true })` re-reads + re-renders ONLY those
+* articles, reusing the cached HTML for the rest. With no options it does a full load.
+*
 * @param ctx - Plugin context (provides `require`, `state`, `log`).
+* @param options - Optional incremental hints; omit for a full load.
+* @param options.reuse - Reuse cached content for slugs not invalidated (dev incremental rebuild).
+* @param options.changed - The changed Markdown paths to invalidate before loading.
 * @returns The locale-keyed article map returned by the content plugin.
 * @example
 * ```ts
 * const byLocale = await loadContent(ctx);
 * ```
 */
-async function loadContent(ctx) {
-	const byLocale = await ctx.require(contentPlugin).loadAll();
+async function loadContent(ctx, options) {
+	const content = ctx.require(contentPlugin);
+	if (options?.changed && options.changed.length > 0) content.invalidate(options.changed);
+	const byLocale = await content.loadAll({ reuse: options?.reuse ?? false });
 	ctx.state.buildCache.set(CONTENT_CACHE_KEY, byLocale);
 	ctx.log.debug("build:content", { locales: byLocale.size });
 	return byLocale;
@@ -4751,6 +4787,71 @@ function renderBody(definition, routeContext) {
 	return (0, preact_render_to_string.renderToString)(definition._handlers.layout ? definition._handlers.layout(layoutContext, vnode) : vnode);
 }
 /**
+* Hash a page's render inputs (its loaded data) for the render cache. `null` when the
+* data is not JSON-serializable — such a page is never cached and always re-renders.
+*
+* @param data - The route's loaded data (the only per-page input besides params/locale/code).
+* @returns The hex SHA-256 of the serialized data, or `null` when it cannot be serialized.
+* @example
+* ```ts
+* hashData({ title: "Hi" }); // "9f8e…"
+* ```
+*/
+function hashData(data) {
+	try {
+		const serialized = JSON.stringify(data) ?? "";
+		return (0, node_crypto.createHash)("sha256").update(serialized).digest("hex");
+	} catch {
+		return null;
+	}
+}
+/**
+* The render-cache key for one page instance: name + params + locale (the stable identity
+* that, together with the data hash, determines its body). NUL-joined so no value collides.
+*
+* @param instance - The page instance.
+* @returns The cache key string.
+* @example
+* ```ts
+* renderCacheKey(instance); // "article{\"slug\":\"x\"}en"
+* ```
+*/
+function renderCacheKey(instance) {
+	return `${instance.name}${JSON.stringify(instance.params)}${instance.locale}`;
+}
+/**
+* Render one page's body, reusing the cached body when this page's data is unchanged.
+* The body is the synchronous, dominant-cost step ({@link renderBody}); an incremental
+* dev rebuild (`reuse`, code unchanged) skips it for every page whose data hash matches
+* the cache, and a changed page (or a non-`reuse` run) renders + refreshes the cache.
+*
+* @param ctx - Plugin context (provides the cross-run `state.renderCache`).
+* @param instance - The page instance being rendered.
+* @param routeContext - The route context passed to `.render()`/`.layout()`.
+* @param data - The route's loaded data (hashed to detect a change).
+* @param reuse - Whether this run may reuse a cached body (incremental, no code change).
+* @returns The SSR-rendered body HTML.
+* @example
+* ```ts
+* const body = renderBodyCached(ctx, instance, routeContext, data, true);
+* ```
+*/
+function renderBodyCached(ctx, instance, routeContext, data, reuse) {
+	const cache = ctx.state.renderCache;
+	const key = renderCacheKey(instance);
+	const hash = hashData(data);
+	if (reuse && hash !== null) {
+		const hit = cache.get(key);
+		if (hit?.dataHash === hash) return hit.body;
+	}
+	const body = renderBody(instance.definition, routeContext);
+	if (hash !== null) cache.set(key, {
+		dataHash: hash,
+		body
+	});
+	return body;
+}
+/**
 * Write a rendered page document to its on-disk path. The path comes from the
 * compiled `TypedRoute.toFile(params)` (honoring any route-level `.toFile()`
 * override), resolved under the build `outDir`; parent directories are created first.
@@ -4779,13 +4880,14 @@ async function writeDocument(outDir, entry, params, html) {
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `has`).
 * @param instance - The concrete page instance to render.
 * @param shell - Per-build wiring shared across instances (asset tags + template).
+* @param reuse - Whether this run may reuse a cached body (incremental, no code change).
 * @returns The instance's URL, rendered HTML, loaded data, and client-nav flag.
 * @example
 * ```ts
-* await renderInstance(ctx, instance, { assets: "", template: null });
+* await renderInstance(ctx, instance, { assets: "", template: null }, false);
 * ```
 */
-async function renderInstance(ctx, instance, shell) {
+async function renderInstance(ctx, instance, shell, reuse) {
 	const { definition, entry, params, locale } = instance;
 	const router = ctx.require(routerPlugin);
 	const data = await loadRouteData(definition, params, locale, ctx);
@@ -4798,7 +4900,7 @@ async function renderInstance(ctx, instance, shell) {
 	};
 	const parts = {
 		head: composeHeadHtml(ctx, instance, url, routeContext, data),
-		body: renderBody(definition, routeContext),
+		body: renderBodyCached(ctx, instance, routeContext, data, reuse),
 		assets: shell.assets,
 		locale
 	};
@@ -4899,6 +5001,12 @@ function findRootHtml(rendered) {
 */
 const RENDER_BATCH_SIZE = 2;
 /**
+* Batch size for an incremental (`reuse`) rebuild. Most instances are cheap cache hits, so
+* a larger batch cuts the per-batch `setImmediate` round-trips (which would otherwise add
+* pure latency to an otherwise-fast rebuild) without starving the dev spinner.
+*/
+const INCREMENTAL_BATCH_SIZE = 32;
+/**
 * Render `items` through `worker` in bounded-size batches, yielding a macrotask
 * (`setImmediate`) between batches. Beyond bounding peak concurrency/memory for large
 * sites, the yield lets the single JS thread breathe: one un-yielded `Promise.all` over
@@ -4934,21 +5042,29 @@ async function renderInBatches(items, batchSize, worker) {
 * bounded batches ({@link renderInBatches}) → write data sidecars (hybrid/spa) →
 * capture the root page's HTML for the root-index phase.
 *
+* On an incremental rebuild (`options.reuse`) the cross-run render cache is kept and each
+* unchanged-data page reuses its cached body; a full render clears the cache first so a
+* removed/renamed route's stale body never lingers.
+*
 * @param ctx - Plugin context (provides `require`, `state`, `config`, `log`, `has`).
+* @param options - Optional incremental hint; omit for a full render.
+* @param options.reuse - Reuse cached page bodies for unchanged-data pages (dev incremental rebuild).
 * @returns The number of pages rendered and the captured default-page HTML.
 * @example
 * ```ts
 * const { pageCount, rootHtml } = await renderPages(ctx);
 * ```
 */
-async function renderPages(ctx) {
+async function renderPages(ctx, options) {
+	const reuse = options?.reuse === true;
 	const router = ctx.require(routerPlugin);
 	const manifest = router.manifest();
 	ctx.state.manifest = [...manifest];
 	const locales = ctx.require(i18nPlugin).locales();
 	const byPattern = makeEntryMap(router);
+	if (!reuse) ctx.state.renderCache.clear();
 	const shell = await prepareShell(ctx);
-	const rendered = await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell));
+	const rendered = await renderInBatches(await expandAllInstances(manifest, locales, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse));
 	await writeDataSidecars(ctx, rendered, router.mode());
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {
@@ -5156,6 +5272,40 @@ async function generateSitemap(ctx) {
 * @file build plugin — pipeline driver. Sequences the fixed multi-phase build,
 * emits `build:phase` boundaries, and runs intra-phase work via `Promise.all`.
 */
+/** Matches a Markdown source path (a content edit). */
+const MARKDOWN_PATH = /\.md$/;
+/** Matches a stylesheet path (a CSS edit — does not change rendered page bodies). */
+const STYLE_PATH = /\.css$/;
+/** Matches a code path (TS/JS/JSON — may change ANY page's render output). */
+const CODE_PATH = /\.(?:tsx?|jsx?|mjs|cjs|json)$/;
+/**
+* Derive the {@link ChangePlan} for a run from its changed-path set (see the type docs
+* for the rules).
+*
+* @param changed - Absolute/relative changed paths, or `undefined` for a full build.
+* @returns The reuse plan for this run.
+* @example
+* ```ts
+* const plan = planIncrementalRebuild(options?.changed);
+* ```
+*/
+function planIncrementalRebuild(changed) {
+	if (changed === void 0 || changed.length === 0) return {
+		contentChanged: [],
+		contentReuse: false,
+		renderReuse: false
+	};
+	if (!changed.every((file) => MARKDOWN_PATH.test(file) || STYLE_PATH.test(file) || CODE_PATH.test(file))) return {
+		contentChanged: [],
+		contentReuse: false,
+		renderReuse: false
+	};
+	return {
+		contentChanged: changed.filter((file) => MARKDOWN_PATH.test(file)),
+		contentReuse: true,
+		renderReuse: !changed.some((file) => CODE_PATH.test(file))
+	};
+}
 /**
 * The static ordered list of pipeline phase names.
 *
@@ -5269,8 +5419,7 @@ async function runOutputs(ctx) {
 * `build:phase` boundary per phase and `build:complete` once at the end.
 *
 * @param ctx - Plugin context (provides `require`, `emit`, `state`, `config`, `log`).
-* @param options - Optional run overrides.
-* @param options.outDir - Override the configured output directory for this run.
+* @param options - Optional per-run overrides ({@link RunOptions}).
 * @returns The build result (outDir, pageCount, durationMs).
 * @example
 * ```ts
@@ -5285,17 +5434,22 @@ async function runPipeline(ctx, options) {
 		...ctx,
 		config: {
 			...ctx.config,
-			outDir
+			outDir,
+			...options?.overrides
 		}
 	};
-	await (0, node_fs_promises.rm)(outDir, {
+	const plan = planIncrementalRebuild(options?.changed);
+	if (!options?.skipClean) await (0, node_fs_promises.rm)(outDir, {
 		recursive: true,
 		force: true
 	});
 	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 	await withPhase(phaseContext, "bundle", () => bundle(phaseContext));
-	await Promise.all([withPhase(phaseContext, "content", () => loadContent(phaseContext)), withPhase(phaseContext, "images", () => processImages(phaseContext))]);
-	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext));
+	await Promise.all([withPhase(phaseContext, "content", () => loadContent(phaseContext, {
+		reuse: plan.contentReuse,
+		changed: plan.contentChanged
+	})), withPhase(phaseContext, "images", () => processImages(phaseContext))]);
+	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext, { reuse: plan.renderReuse }));
 	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
 	await withPhase(phaseContext, "root-index", async () => {
@@ -5348,10 +5502,12 @@ const defaultConfig$2 = {
 function createApi$3(ctx) {
 	return {
 		/**
-		* Run the full SSG pipeline and write the site to disk.
+		* Run the full SSG pipeline and write the site to disk. With no options a full
+		* production build runs; dev callers pass `skipClean`/`overrides`/`changed` for a
+		* fast incremental rebuild (all gated behind opt-in fields — the default path is
+		* unchanged).
 		*
-		* @param options - Optional run overrides.
-		* @param options.outDir - Override the configured output directory for this run.
+		* @param options - Optional per-run overrides (outDir / skipClean / overrides / changed).
 		* @returns The build result (outDir, pageCount, durationMs).
 		* @example
 		* ```ts
@@ -5444,8 +5600,8 @@ function createEvents(register) {
 /**
 * Creates initial `build` plugin state: a frozen config snapshot plus empty
 * per-run caches (`manifest`, `buildCache`, `runId`) and the cross-run OG
-* content-hash cache. Holds caches and config only — no domain data is
-* duplicated here (pulled fresh via `ctx.require` each run).
+* content-hash + page-render caches. Holds caches and config only — no domain data
+* is duplicated here (pulled fresh via `ctx.require` each run).
 *
 * @param ctx - Minimal context with global and config.
 * @param ctx.global - Global plugin registry (unused; caches are config-driven).
@@ -5462,7 +5618,8 @@ function createState$3(ctx) {
 		manifest: null,
 		buildCache: /* @__PURE__ */ new Map(),
 		runId: null,
-		ogImageHashCache: /* @__PURE__ */ new Map()
+		ogImageHashCache: /* @__PURE__ */ new Map(),
+		renderCache: /* @__PURE__ */ new Map()
 	};
 }
 //#endregion
@@ -5686,12 +5843,37 @@ function buildWranglerArgs(input) {
 		branch
 	];
 }
+/**
+* Assemble the argv for `wrangler pages project create` (no shell). Guards the
+* production branch against flag injection; the slug is already a safe `toSlug` output.
+*
+* @param input - The resolved project-create inputs.
+* @param input.slug - Cloudflare project-name slug (`toSlug(site.name())`).
+* @param input.branch - Production branch (guarded by `/^[a-zA-Z0-9/_.-]+$/`).
+* @returns The wrangler argv array.
+* @throws {Error} `ERR_DEPLOY_INVALID_BRANCH` when the branch fails the guard.
+* @example
+* buildProjectCreateArgs({ slug: "my-site", branch: "main" });
+*/
+function buildProjectCreateArgs(input) {
+	const branch = guardBranch(input.branch);
+	return [
+		"bunx",
+		"wrangler",
+		"pages",
+		"project",
+		"create",
+		input.slug,
+		"--production-branch",
+		branch
+	];
+}
 /** Lowercased substring matchers for the wrangler error taxonomy. */
 const ERROR_SIGNATURES = [
 	{
 		match: ["could not find project", "project not found"],
 		kind: "ERR_DEPLOY_PROJECT_NOT_FOUND",
-		advice: "The Cloudflare Pages project does not exist. Run `app.deploy.init()` or create it in the dashboard, then retry."
+		advice: "The Cloudflare Pages project does not exist yet. Create it in the dashboard (Workers & Pages → Create → Pages) or with `bunx wrangler pages project create <name>`, then retry. (app.deploy.init() only scaffolds local config — it does not create the remote project.)"
 	},
 	{
 		match: [
@@ -6270,15 +6452,16 @@ function validateConfig$1(ctx) {
 * Run wrangler for the prepared argv and surface its scrubbed result, translating
 * a non-zero exit into the classified deploy error. The API token is read from env
 * here so it never crosses a logging boundary; only scrubbed output is returned.
+* Shared by `run()` (deploy) and `createProject()` (project create).
 *
 * @param ctx - Plugin context (provides `state.spawn`, `config`, `env`).
 * @param args - The fully-built, pre-validated wrangler argv.
 * @returns The wrangler `stdout` plus the scrubbed `stderr` to log on success.
 * @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
 * @example
-* const { stdout, scrubbedStderr } = await executeDeploy(ctx, args);
+* const { stdout, scrubbedStderr } = await executeWrangler(ctx, args);
 */
-async function executeDeploy(ctx, args) {
+async function executeWrangler(ctx, args) {
 	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
 	const { stdout, scrubbedStderr, exitCode } = await runWrangler({
 		spawn: ctx.state.spawn,
@@ -6350,7 +6533,7 @@ function createApi$2(ctx) {
 				root
 			});
 			const start = Date.now();
-			const { stdout, scrubbedStderr } = await executeDeploy(ctx, args);
+			const { stdout, scrubbedStderr } = await executeWrangler(ctx, args);
 			ctx.log.info(scrubbedStderr);
 			const result = buildDeployResult(stdout, branch, start);
 			ctx.state.lastDeployment = result;
@@ -6389,6 +6572,38 @@ function createApi$2(ctx) {
 				cwd: process.cwd(),
 				options
 			});
+		},
+		/**
+		* The Cloudflare Pages project name this app deploys to (`toSlug(site.name())`).
+		*
+		* @returns The project-name slug.
+		* @example
+		* api.projectName(); // "my-site"
+		*/
+		projectName() {
+			return toSlug(ctx.require(sitePlugin).name());
+		},
+		/**
+		* Create the remote Cloudflare Pages project via wrangler, so a first deploy has a
+		* target. Derives the slug from `site.name()` and the production branch from config.
+		*
+		* @returns The created project name + production branch.
+		* @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
+		* @example
+		* await api.createProject(); // { name: "my-site", branch: "main" }
+		*/
+		async createProject() {
+			const name = toSlug(ctx.require(sitePlugin).name());
+			const branch = ctx.config.productionBranch ?? "main";
+			const { scrubbedStderr } = await executeWrangler(ctx, buildProjectCreateArgs({
+				slug: name,
+				branch
+			}));
+			ctx.log.info(scrubbedStderr);
+			return {
+				name,
+				branch
+			};
 		}
 	};
 }
@@ -6522,21 +6737,56 @@ const ACCOUNT_HELP = [
 	"right-hand sidebar (also in the dashboard URL). Then make it available:",
 	"  export CLOUDFLARE_ACCOUNT_ID=…   or add it to .env."
 ].join("\n");
+/** Shown when a credential is in the raw environment but the app's env providers did not resolve it. */
+const PROVIDERS_HELP = [
+	"Found in your shell/.env but the app's env plugin did not resolve it — its providers",
+	"are not wired. Add the Node providers in createApp so the deploy can read it:",
+	"  pluginConfigs.env = { providers: [processEnv(), dotenv()] }   (import them from @moku-labs/web)."
+].join("\n");
 /** The GitHub repo secrets the generated workflow consumes. */
 const SECRETS_HELP = ["Add these repo secrets (GitHub → Settings → Secrets and variables → Actions):", "CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID"].join("\n");
 /**
+* Build one credential prerequisite by reading the SAME source the deploy reads — the
+* resolved `ctx.env` table — so a ✓ guarantees `ctx.env.require(key)` will succeed. When
+* the value is present in the raw `process.env` but unresolved by the app's providers
+* (the silent "deploy can't see it" trap a bare `process.env` check would mark green),
+* the fix hint points at wiring the providers instead of re-adding the value.
+*
+* @param ctx - The cli plugin context (provides the resolved `ctx.env`).
+* @param key - The credential variable name.
+* @param label - The diagnostic line label.
+* @param missingHelp - The fix hint when the credential is genuinely absent everywhere.
+* @returns The credential prerequisite check.
+* @example
+* credentialPrereq(ctx, "CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_TOKEN is set", TOKEN_HELP);
+*/
+function credentialPrereq(ctx, key, label, missingHelp) {
+	if ((ctx.env.get(key) ?? "") !== "") return {
+		ok: true,
+		label,
+		detail: void 0,
+		scaffoldable: false
+	};
+	return {
+		ok: false,
+		label,
+		detail: (process.env[key] ?? "") !== "" ? PROVIDERS_HELP : missingHelp,
+		scaffoldable: false
+	};
+}
+/**
 * Evaluate the three deploy prerequisites against the current project: the Cloudflare
-* wrangler config exists, and both Cloudflare credentials are present in the environment.
+* wrangler config exists, and both Cloudflare credentials resolve through `ctx.env` (the
+* deploy's own source of truth — not a bare `process.env` read that can diverge from it).
 *
+* @param ctx - The cli plugin context (provides the resolved `ctx.env`).
 * @param cwd - The project root (where `wrangler.jsonc` lives).
 * @returns The ordered prerequisite checks.
 * @example
-* const prereqs = diagnose(process.cwd());
+* const prereqs = diagnose(ctx, process.cwd());
 */
-function diagnose(cwd) {
+function diagnose(ctx, cwd) {
 	const wranglerOk = (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,
@@ -6544,18 +6794,8 @@ function diagnose(cwd) {
 			detail: wranglerOk ? void 0 : "Missing — scaffold it (offered below) or run app.deploy.init().",
 			scaffoldable: true
 		},
-		{
-			ok: tokenOk,
-			label: "CLOUDFLARE_API_TOKEN is set",
-			detail: tokenOk ? void 0 : TOKEN_HELP,
-			scaffoldable: false
-		},
-		{
-			ok: accountOk,
-			label: "CLOUDFLARE_ACCOUNT_ID is set",
-			detail: accountOk ? void 0 : ACCOUNT_HELP,
-			scaffoldable: false
-		}
+		credentialPrereq(ctx, "CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_TOKEN is set", TOKEN_HELP),
+		credentialPrereq(ctx, "CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_ACCOUNT_ID is set", ACCOUNT_HELP)
 	];
 }
 /**
@@ -6653,8 +6893,139 @@ async function offerWorkflowSetup(ctx) {
 	ctx.state.render.info(SECRETS_HELP);
 }
 /**
-* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin and
-* report the outcome. A declined confirm returns `{ deployed: false, reason: "declined" }`.
+* Read the taxonomy `code` off a thrown value, when present. Deploy errors carry a
+* `code` (e.g. `ERR_DEPLOY_PROJECT_NOT_FOUND`) so the wizard can tailor the fix hint.
+*
+* @param error - The thrown value.
+* @returns The `code` string, or `undefined` when absent.
+* @example
+* codeOf(deployError("ERR_DEPLOY_AUTH", "…")); // "ERR_DEPLOY_AUTH"
+*/
+function codeOf(error) {
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const { code } = error;
+		return typeof code === "string" ? code : void 0;
+	}
+}
+/**
+* A copy-pasteable "create the project yourself" hint, shown when the user declines the
+* offer to auto-create. Spells out that the remote project is what's missing (init only
+* scaffolds local config).
+*
+* @param name - The Cloudflare Pages project name (the deploy slug).
+* @returns The multi-line hint (newline-separated; rendered indented under a `›`).
+* @example
+* ctx.state.render.info(projectNotFoundHint("my-site"));
+*/
+function projectNotFoundHint(name) {
+	return [
+		"how to fix: the Cloudflare Pages project does not exist yet — create it once, then",
+		"re-run `bun run deploy`. (app.deploy.init() only scaffolds local config; it does not",
+		"create the remote project.)",
+		`  • CLI:       bunx wrangler pages project create ${name} --production-branch main`,
+		"  • Dashboard: Cloudflare → Workers & Pages → Create → Pages"
+	].join("\n");
+}
+/**
+* An actionable, error-specific "how to fix" hint for a failed deploy (other than the
+* project-not-found case, which the wizard handles interactively), so the user never
+* lands on a raw stack trace.
+*
+* @param error - The thrown deploy error.
+* @returns The fix hint line.
+* @example
+* ctx.state.render.info(deployFailureHint(err));
+*/
+function deployFailureHint$1(error) {
+	const code = codeOf(error);
+	if (code === "ERR_DEPLOY_AUTH" || code === "ERR_DEPLOY_AUTH_EXPIRED") return "how to fix: refresh CLOUDFLARE_API_TOKEN (scope: Account › Cloudflare Pages › Edit), then re-run `bun run deploy`.";
+	if (code === "ERR_DEPLOY_NETWORK") return "how to fix: a network error reached Cloudflare — check connectivity, then re-run `bun run deploy`.";
+	return "how to fix: resolve the error above, then re-run `bun run deploy`.";
+}
+/**
+* Render a styled deploy failure (✗ + fix hint) and return the `"failed"` outcome, so a
+* caught error surfaces consistently instead of as a raw throw.
+*
+* @param ctx - The cli plugin context.
+* @param error - The thrown deploy error.
+* @returns The `"failed"` deploy outcome.
+* @example
+* return renderFailure(ctx, error);
+*/
+function renderFailure(ctx, error) {
+	ctx.state.render.error("deploy failed", error);
+	ctx.state.render.info(deployFailureHint$1(error));
+	return {
+		deployed: false,
+		reason: "failed"
+	};
+}
+/**
+* Deploy once via the deploy plugin and wrap the result as a successful outcome. Throws
+* the classified deploy error on failure (the caller decides how to surface it).
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override).
+* @returns The successful deploy outcome.
+* @throws {Error} With a `code` from the deploy error taxonomy on any failure.
+* @example
+* const outcome = await deployOnce(ctx, { branch: "main" });
+*/
+async function deployOnce(ctx, options) {
+	return {
+		deployed: true,
+		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
+	};
+}
+/**
+* Handle a project-not-found deploy failure interactively: ask (a confirmation step)
+* before creating a real Cloudflare resource, create the Pages project via the deploy
+* plugin, then retry the deploy once. A declined offer (or a create failure) returns the
+* `"failed"` outcome with an actionable hint — never a raw stack trace.
+*
+* @param ctx - The cli plugin context.
+* @param options - The deploy options (branch override).
+* @param originalError - The project-not-found error from the first attempt.
+* @returns The deploy outcome (deployed after a successful create + retry, else failed).
+* @example
+* return createProjectThenRetry(ctx, options, error);
+*/
+async function createProjectThenRetry(ctx, options, originalError) {
+	const deploy = ctx.require(deployPlugin);
+	const name = deploy.projectName();
+	ctx.state.render.warn(`The Cloudflare Pages project "${name}" does not exist yet.`);
+	if (!await ctx.state.confirm(`Create the Cloudflare Pages project "${name}" now?`)) {
+		ctx.state.render.error("deploy failed", originalError);
+		ctx.state.render.info(projectNotFoundHint(name));
+		return {
+			deployed: false,
+			reason: "failed"
+		};
+	}
+	try {
+		const created = await deploy.createProject();
+		ctx.state.render.check(true, `created Cloudflare Pages project "${created.name}"`);
+	} catch (error) {
+		ctx.state.render.error("could not create the Pages project", error);
+		ctx.state.render.info(deployFailureHint$1(error));
+		return {
+			deployed: false,
+			reason: "failed"
+		};
+	}
+	ctx.state.render.info("project created — retrying the deploy…");
+	try {
+		return await deployOnce(ctx, options);
+	} catch (error) {
+		return renderFailure(ctx, error);
+	}
+}
+/**
+* Run the deploy step: confirm (unless `yes`), then deploy via the deploy plugin. A
+* declined confirm returns `{ deployed: false, reason: "declined" }`. A project-not-found
+* failure offers to create the project (with a confirmation step) and retries; any other
+* runtime failure is surfaced as a styled error + fix hint, returning
+* `{ deployed: false, reason: "failed" }` — never a raw stack trace.
 *
 * @param ctx - The cli plugin context.
 * @param options - The deploy options (branch override + `yes`).
@@ -6671,10 +7042,12 @@ async function runDeployStep(ctx, options) {
 			reason: "declined"
 		};
 	}
-	return {
-		deployed: true,
-		...await ctx.require(deployPlugin).run(options.branch === void 0 ? {} : { branch: options.branch })
-	};
+	try {
+		return await deployOnce(ctx, options);
+	} catch (error) {
+		if (codeOf(error) === "ERR_DEPLOY_PROJECT_NOT_FOUND") return createProjectThenRetry(ctx, options, error);
+		return renderFailure(ctx, error);
+	}
 }
 /**
 * Run the guided deploy wizard end to end: diagnose prerequisites (offering to scaffold
@@ -6692,10 +7065,10 @@ async function runDeployStep(ctx, options) {
 async function runDeployWizard(ctx, options) {
 	const cwd = process.cwd();
 	ctx.state.render.heading("Checking prerequisites");
-	for (const item of diagnose(cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
-	await offerScaffold(ctx, diagnose(cwd));
+	for (const item of diagnose(ctx, cwd)) ctx.state.render.check(item.ok, item.label, item.detail);
+	await offerScaffold(ctx, diagnose(ctx, cwd));
 	await offerEnvScaffold(ctx, cwd);
-	const blockers = diagnose(cwd).filter((item) => !item.ok);
+	const blockers = diagnose(ctx, cwd).filter((item) => !item.ok);
 	if (blockers.length > 0) {
 		ctx.state.render.heading("Not ready to deploy");
 		for (const item of blockers) ctx.state.render.check(false, item.label, item.detail);
@@ -6712,7 +7085,7 @@ async function runDeployWizard(ctx, options) {
 	ctx.state.render.check(notFoundOk, `${ctx.config.notFoundFile} present`, notFoundOk ? void 0 : "Set build.notFound so the SSG emits it (CF Pages else flips to SPA mode).");
 	ctx.state.render.info("Tip: run `bun run preview` to eyeball the built site before deploying.");
 	const outcome = await runDeployStep(ctx, options);
-	await offerWorkflowSetup(ctx);
+	if (!(outcome.deployed === false && outcome.reason === "failed")) await offerWorkflowSetup(ctx);
 	return outcome;
 }
 //#endregion
@@ -6752,25 +7125,26 @@ function injectReloadClient(html) {
 * Run one rebuild and report the result. Announces the start (`onRebuildStart`), then
 * routes success to `onReloaded` and failure to `onError`.
 *
-* @param input - The rebuild dependencies + the changed file.
-* @param input.runBuild - Runs one build and resolves with its summary.
+* @param input - The rebuild dependencies + the changed file/paths.
+* @param input.runBuild - Runs one build (given the changed paths) and resolves with its summary.
 * @param input.onRebuildStart - Called with the changed file just before the build runs.
-* @param input.onReloaded - Called with the changed file + summary after a rebuild.
+* @param input.onReloaded - Called with the changed file + summary + the built `changed` set after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @param input.file - The changed file to report alongside the summary.
+* @param input.changed - The accumulated changed paths handed to `runBuild` (incremental).
 * @returns Resolves once the rebuild settles (always — errors are routed, not thrown).
 * @example
-* await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md" });
+* await runOneRebuild({ runBuild, onReloaded, onError, file: "a.md", changed: ["a.md"] });
 */
 async function runOneRebuild(input) {
 	input.onRebuildStart?.(input.file);
 	try {
-		const summary = await input.runBuild();
+		const summary = await input.runBuild(input.changed);
 		input.onReloaded({
 			file: input.file,
 			pageCount: summary.pageCount,
 			durationMs: summary.durationMs
-		});
+		}, input.changed);
 	} catch (error) {
 		input.onError(error);
 	}
@@ -6784,9 +7158,9 @@ async function runOneRebuild(input) {
 *
 * @param input - The rebuild dependencies.
 * @param input.debounceMs - Debounce window in milliseconds.
-* @param input.runBuild - Runs one build and resolves with its summary.
+* @param input.runBuild - Runs one build (given the changed paths) and resolves with its summary.
 * @param input.onRebuildStart - Called with the changed file just before each build runs.
-* @param input.onReloaded - Called with the changed file + summary after a rebuild.
+* @param input.onReloaded - Called with the changed file + summary + the built `changed` set after a rebuild.
 * @param input.onError - Called when a rebuild throws.
 * @returns The debounced rebuild driver.
 * @example
@@ -6795,12 +7169,13 @@ async function runOneRebuild(input) {
 function createRebuilder(input) {
 	let timer;
 	let pendingFile = "";
+	const pendingChanged = /* @__PURE__ */ new Set();
 	let building = false;
 	let dirty = false;
 	/**
-	* Rebuild repeatedly until no change arrived mid-flight: each pass clears `dirty`,
-	* runs one build, then loops again if a `schedule()` set `dirty` while it ran, so
-	* no change is dropped.
+	* Rebuild repeatedly until no change arrived mid-flight: each pass snapshots + clears
+	* the accumulated changed paths, runs one build over them, then loops again if a
+	* `schedule()` set `dirty` (and added more paths) while it ran, so no change is dropped.
 	*
 	* @returns Resolves once a pass completes with no pending change (errors are routed,
 	*   never thrown).
@@ -6810,12 +7185,15 @@ function createRebuilder(input) {
 	const drainPendingRebuilds = async () => {
 		do {
 			dirty = false;
+			const changed = [...pendingChanged];
+			pendingChanged.clear();
 			await runOneRebuild({
 				runBuild: input.runBuild,
 				...input.onRebuildStart ? { onRebuildStart: input.onRebuildStart } : {},
 				onReloaded: input.onReloaded,
 				onError: input.onError,
-				file: pendingFile
+				file: pendingFile,
+				changed
 			});
 		} while (dirty);
 	};
@@ -6842,14 +7220,15 @@ function createRebuilder(input) {
 	};
 	return {
 		/**
-		* Queue a rebuild for the given label (debounced + coalesced).
+		* Queue a rebuild for the given changed path (debounced + coalesced + accumulated).
 		*
-		* @param file - The label reported as `ReloadInfo.file` — the watched directory in `serve()`.
+		* @param file - The changed path reported as `ReloadInfo.file` and added to the changed set.
 		* @example
-		* rebuilder.schedule("content");
+		* rebuilder.schedule("content/intro/en.md");
 		*/
 		schedule(file) {
 			pendingFile = file;
+			pendingChanged.add(file);
 			if (timer) clearTimeout(timer);
 			timer = setTimeout(fire, input.debounceMs);
 		},
@@ -6879,26 +7258,33 @@ function isNoisePath(filename) {
 	return filename.split(/[/\\]/).some((segment) => segment.startsWith(".")) || filename.endsWith("~");
 }
 /**
-* Create a {@link ChangeGate} that drops three kinds of spurious change events before
-* they reach the debounced rebuilder: editor/OS noise (dotfiles, backups), writes under
-* `outDir` (the build's own output — a loop guard), and the stale duplicate/parent-dir
-* echoes macOS fires for one save. Staleness is judged by a build-start high-water mark:
-* a change whose file mtime is at or before the last build we started was already
-* captured (or is a late echo), so it is ignored — while a genuinely newer edit (even
-* one made mid-build) and a deletion (missing file) always pass. The single timestamp
-* also means no per-path map grows over a long session.
+* Create a {@link ChangeGate} that drops four kinds of spurious change events before they
+* reach the debounced rebuilder: editor/OS noise (dotfiles, backups), writes under
+* `outDir` (the build's own output — a loop guard), the stale duplicate/parent-dir echoes
+* macOS fires for one save (a build-start high-water mark — a change whose mtime is at or
+* before the last build we started was already captured), and — when a `fileHash` seam is
+* supplied — a NO-OP save whose bytes are identical to the last successfully-built version
+* (a double Ctrl-S, a `touch`, a format-on-save that reverts). The no-op baseline is
+* recorded ONLY by {@link ChangeGate.commitBuilt} on build SUCCESS, scoped to that build's
+* paths — so a failed build commits nothing (a retry save always rebuilds) and a file
+* edited mid-build is never falsely baselined by another file's success. A genuinely newer
+* edit (even mid-build) and a deletion (missing file) always pass.
 *
 * @param input - The gate dependencies.
 * @param input.outDir - The build output directory whose writes must never re-trigger a build.
 * @param input.fileMtime - Resolves a path's mtime in ms (or `null` when missing).
 * @param input.now - Monotonic wall clock (ms) used for the build-start high-water mark.
+* @param input.fileHash - Resolves a path's content hash (or `null` when missing). Optional;
+*   defaults to `() => null`, which disables the no-op-save short-circuit (every edit passes).
 * @returns The change gate.
 * @example
-* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock });
+* const gate = createChangeGate({ outDir: "dist", fileMtime: state.fileMtime, now: state.clock, fileHash: state.fileHash });
 */
 function createChangeGate(input) {
 	const outDirAbs = node_path$1.default.resolve(input.outDir);
+	const fileHash = input.fileHash ?? (() => null);
 	let lastBuildStartedAt = input.now();
+	const committedHash = /* @__PURE__ */ new Map();
 	return {
 		/**
 		* Decide whether a change beneath `dir` warrants a rebuild (see {@link ChangeGate.accept}).
@@ -6916,6 +7302,12 @@ function createChangeGate(input) {
 			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;
+			const hash = fileHash(changed);
+			if (hash === null) {
+				committedHash.delete(changed);
+				return true;
+			}
+			if (committedHash.get(changed) === hash) return false;
 			return true;
 		},
 		/**
@@ -6926,6 +7318,20 @@ function createChangeGate(input) {
 		*/
 		markBuildStart() {
 			lastBuildStartedAt = input.now();
+		},
+		/**
+		* Baseline exactly the paths the just-succeeded build consumed (see {@link ChangeGate.commitBuilt}).
+		*
+		* @param changed - The paths the just-succeeded build consumed.
+		* @example
+		* gate.commitBuilt(["content/intro/en.md"]);
+		*/
+		commitBuilt(changed) {
+			for (const file of changed) {
+				const key = node_path$1.default.resolve(file);
+				const hash = fileHash(key);
+				if (hash !== null) committedHash.set(key, hash);
+			}
 		}
 	};
 }
@@ -7118,19 +7524,46 @@ function createDevHandler(ctx, hub) {
 	};
 }
 /**
+* Build the per-run {@link BuildRunOverrides} for a dev build from the session feature
+* opt-ins: minification is always off in dev (no benefit, slower), and each expensive,
+* NON-navigational output stays off unless its flag re-enables it (`ogImage: false`
+* disables OG generation regardless of the persisted config). Locale-redirects are NOT
+* overridden — they produce navigable pages (the bare `/` → `/{defaultLocale}/` redirect),
+* so they follow the app's own config. The persisted plugin config is never mutated.
+*
+* @param features - The resolved per-session dev feature opt-ins.
+* @returns The config overrides merged into the dev build run.
+* @example
+* devBuildOverrides({ og: false, sitemap: false, feeds: false });
+*/
+function devBuildOverrides(features) {
+	return {
+		minify: false,
+		...features.feeds ? {} : { feeds: false },
+		...features.sitemap ? {} : { sitemap: false },
+		...features.og ? {} : { ogImage: false }
+	};
+}
+/**
 * Run the dev loop: an initial build, an in-process static server that injects the
 * live-reload client, a recursive watcher over `config.watchDirs`, and a debounced
 * rebuild that re-renders and pushes a browser reload. Resolves on SIGINT/SIGTERM,
-* which stops the server, closes the watchers, and cancels any pending rebuild.
+* which stops the server, closes the watchers, and cancels any pending rebuild. The dev
+* build disables minification + expensive outputs (per {@link devBuildOverrides}); every
+* rebuild also skips the clean so caches + unchanged assets survive (no mid-rebuild 404).
+* Because rebuilds skip the clean, a DELETED or renamed content slug's stale page lingers
+* (and is served) until you restart `serve` or run a production `build`.
 *
 * @param ctx - The cli plugin context (config, state seams, `require`).
 * @param port - The port to bind the dev server to.
+* @param features - Per-session dev feature opt-ins (`og`/`sitemap`/`feeds`/`localeRedirects`).
 * @returns Resolves once the server has been torn down by a termination signal.
 * @example
-* await runDevServer(ctx, 4173);
+* await runDevServer(ctx, 4173, { og: false, sitemap: false, feeds: false, localeRedirects: false });
 */
-async function runDevServer(ctx, port) {
-	await ctx.require(buildPlugin).run();
+async function runDevServer(ctx, port, features) {
+	const overrides = devBuildOverrides(features);
+	await ctx.require(buildPlugin).run({ overrides });
 	const hub = createReloadHub();
 	const server = ctx.state.serveStatic({
 		port,
@@ -7140,19 +7573,27 @@ async function runDevServer(ctx, port) {
 	const gate = createChangeGate({
 		outDir: ctx.config.outDir,
 		fileMtime: ctx.state.fileMtime,
-		now: ctx.state.clock
+		now: ctx.state.clock,
+		fileHash: ctx.state.fileHash
 	});
 	const rebuilder = createRebuilder({
 		debounceMs: ctx.config.debounceMs,
 		/**
-		* Re-run the SSG build for a rebuild.
+		* Re-run the SSG build for a rebuild: skip the clean so the prior assets + on-disk
+		* caches survive (and no in-flight request hits an empty outDir), with the dev
+		* overrides applied.
 		*
+		* @param changed - The paths changed since the last build (incremental rebuild hint).
 		* @returns The rebuild summary.
 		* @example
-		* await runBuild();
+		* await runBuild(["content/intro/en.md"]);
 		*/
-		runBuild() {
-			return ctx.require(buildPlugin).run();
+		runBuild(changed) {
+			return ctx.require(buildPlugin).run({
+				skipClean: true,
+				overrides,
+				changed
+			});
 		},
 		/**
 		* Show the compact in-place "rebuilding {label}" line before the build runs.
@@ -7169,15 +7610,18 @@ async function runDevServer(ctx, port) {
 		* Render the reload line and push a browser reload after a rebuild.
 		*
 		* @param info - The changed file plus the rebuild's page count and duration.
+		* @param changed - The paths this successful build consumed (baselined for no-op drops).
 		* @example
-		* onReloaded({ file: "a.md", pageCount: 1, durationMs: 10 });
+		* onReloaded({ file: "a.md", pageCount: 1, durationMs: 10 }, ["content/a.md"]);
 		*/
-		onReloaded(info) {
+		onReloaded(info, changed) {
+			gate.commitBuilt(changed);
 			ctx.state.render.reload(info);
 			hub.reloadAll();
 		},
 		/**
-		* Render a rebuild failure (the dev loop keeps running).
+		* Render a rebuild failure (the dev loop keeps running). A failed build baselines
+		* nothing (commitBuilt only runs on success), so an identical retry save still rebuilds.
 		*
 		* @param error - The thrown rebuild error.
 		* @example
@@ -7188,7 +7632,8 @@ async function runDevServer(ctx, port) {
 		}
 	});
 	const watchers = ctx.config.watchDirs.map((dir) => ctx.state.watch(dir, (filename) => {
-		if (gate.accept(dir, filename)) rebuilder.schedule(dir);
+		if (!gate.accept(dir, filename)) return;
+		rebuilder.schedule(filename === void 0 ? dir : node_path$1.default.join(dir, filename));
 	}));
 	ctx.state.render.serverReady({
 		local: `http://localhost:${port}`,
@@ -7455,17 +7900,25 @@ function createApi$1(ctx) {
 		},
 		/**
 		* Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
-		* `watchDirs`, debounced rebuild + reload. Resolves on SIGINT/SIGTERM.
+		* `watchDirs`, debounced + incremental rebuild + reload. For a fast rebuild the dev
+		* build disables minification + expensive, NON-navigational outputs (feeds / sitemap /
+		* og-images); pass `og`/`sitemap`/`feeds` to re-enable any of them for the session.
+		* Locale-redirects are always built per the app config (they emit the navigable bare-path
+		* `/` → `/{defaultLocale}/` redirect). Resolves on SIGINT/SIGTERM.
 		*
-		* @param options - Optional port override (defaults to `config.port`).
+		* @param options - Optional port override + per-session dev feature opt-ins.
 		* @returns Resolves once the server has been torn down.
 		* @example
-		* await api.serve({ port: 3000 });
+		* await api.serve({ port: 3000, og: true });
 		*/
 		serve(options = {}) {
 			const { port = ctx.config.port } = options;
 			ctx.state.render.header("serve");
-			return runDevServer(ctx, port);
+			return runDevServer(ctx, port, {
+				og: options.og ?? false,
+				sitemap: options.sitemap ?? false,
+				feeds: options.feeds ?? false
+			});
 		},
 		/**
 		* Static preview of the built `dist/` with CF-Pages clean-URL resolution.
@@ -8548,6 +9001,23 @@ function defaultFileMtime(filePath) {
 	}
 }
 /**
+* Default file-content-hash probe — `sha256` of the file bytes, returning `null` for a
+* missing/unreadable path. serve()'s change gate compares this against the last
+* successfully-built bytes to drop a no-op save (a byte-identical double Ctrl-S).
+*
+* @param filePath - The absolute path to hash.
+* @returns The hex SHA-256 of the file's bytes, or `null` when it cannot be read.
+* @example
+* const hash = defaultFileHash("/abs/content/a.md");
+*/
+function defaultFileHash(filePath) {
+	try {
+		return (0, node_crypto.createHash)("sha256").update((0, node_fs.readFileSync)(filePath)).digest("hex");
+	} catch {
+		return null;
+	}
+}
+/**
 * Default LAN network-URL deriver — wraps {@link networkUrl} so the production seam
 * reads `node:os` interfaces while tests can inject a deterministic value.
 *
@@ -8680,7 +9150,8 @@ function createState$1(_ctx) {
 		serveStatic: defaultServeStatic,
 		fileResponse: defaultFileResponse,
 		networkUrl: defaultNetworkUrl,
-		fileMtime: defaultFileMtime
+		fileMtime: defaultFileMtime,
+		fileHash: defaultFileHash
 	};
 }
 //#endregion