@moku-labs/web 1.7.0 → 1.8.0

package/dist/index.cjs

@@ -3486,7 +3486,9 @@ const headPlugin = createPlugin$1("head", {
 //#region src/plugins/build/phases/bundle.ts
 /**
 * @file build phase 1 — bundle. Runs `Bun.build` for CSS and JS separately into
-* outDir (honoring `config.minify`); caches hashed asset paths for the pages phase.
+* outDir (honoring `config.minify`) with content-hashed output naming; caches the
+* fingerprinted asset paths for the pages phase and the complete output list for
+* the cache-headers phase.
 */
 /** Conventional CSS entry candidates (project-relative). */
 const CSS_ENTRY_CANDIDATES = ["src/client/styles.css", "src/styles/main.css"];
@@ -3497,18 +3499,38 @@ const JS_ENTRY_CANDIDATES = [
 	"src/main.ts"
 ];
 /**
+* `Bun.build` output naming with a content hash in EVERY filename (entry points
+* included — Bun's default only hashes chunks/assets). A bundle's URL therefore
+* changes whenever its bytes change, which is what lets the cache-headers phase
+* mark each bundle immutable: a CDN/browser may cache it forever, and a deploy
+* that changes the code ships a NEW URL instead of fighting a stale cached copy.
+* Pages always embed bundle URLs via the `state.buildCache` manifest, so hashed
+* names flow through with no app-side changes (hardcoded asset URLs must move to
+* the `<!--moku:assets-->` placeholders). Chunk naming keeps Bun's default
+* `chunk-` prefix (chunks were already hash-only named).
+*/
+const FINGERPRINT_NAMING = {
+	entry: "[dir]/[name]-[hash].[ext]",
+	chunk: "chunk-[hash].[ext]",
+	asset: "[name]-[hash].[ext]"
+};
+/**
 * The default bundler runner — adapts the built-in `Bun.build`.
 *
-* @param options - Entry/outdir/minify/splitting/target settings forwarded to `Bun.build`.
+* @param options - Entry/outdir/minify/splitting/target/naming settings forwarded to `Bun.build`.
 * @param options.entrypoints - Entry files for this build.
 * @param options.outdir - Output directory.
 * @param options.minify - Whether to minify.
 * @param options.splitting - Whether to split dynamic imports into lazy chunks.
 * @param options.target - The bundling target platform.
+* @param options.naming - Output naming templates (content-hashed filenames).
+* @param options.naming.entry - Naming template for entry-point outputs.
+* @param options.naming.chunk - Naming template for lazy split chunks.
+* @param options.naming.asset - Naming template for additional emitted assets.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser" });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING });
 * ```
 */
 async function defaultRunner(options) {
@@ -3600,7 +3622,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		outdir,
 		minify,
 		splitting: true,
-		target: "browser"
+		target: "browser",
+		naming: FINGERPRINT_NAMING
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -3609,6 +3632,7 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		hashed[node_path$1.default.basename(output.path)] = normalizeAssetPath(output.path, outDir);
 	}
 	ctx.state.buildCache.set(kind, hashed);
+	ctx.state.buildCache.set(`${kind}:outputs`, result.outputs.map((output) => normalizeAssetPath(output.path, outDir)));
 	ctx.log.debug("build:bundle", {
 		kind,
 		count: result.outputs.length
@@ -3640,6 +3664,269 @@ async function bundle(ctx, options = {}) {
 	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/asset-tags.ts
+/** Template placeholder for the injected asset tags (stylesheets + scripts). */
+const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
+/** Template placeholder for the injected stylesheet `<link>` tags ONLY. */
+const CSS_ASSETS_PLACEHOLDER = "<!--moku:assets:css-->";
+/** Template placeholder for the injected `<script>` tags ONLY. */
+const JS_ASSETS_PLACEHOLDER = "<!--moku:assets:js-->";
+/**
+* Read the bundle phase's fingerprinted asset manifest for one kind from
+* `state.buildCache` as a typed {@link BuildCacheEntry} (no `Map<string, unknown>`
+* reads at call sites).
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The fingerprinted-path manifest entry, or an empty object when absent.
+* @example
+* ```ts
+* readManifest(ctx, "css"); // { "main.css": "assets/main-abc123.css" }
+* ```
+*/
+function readManifest(ctx, kind) {
+	const entry = ctx.state.buildCache.get(kind);
+	return entry && typeof entry === "object" ? entry : {};
+}
+/**
+* Read the bundle phase's COMPLETE output list for one kind (entries + lazy split
+* chunks, web paths relative to the publish root) from `state.buildCache`. Unlike
+* {@link readManifest} this includes chunks — it feeds the cache-headers phase's
+* per-file immutable rules, where every fingerprinted file counts, not just the
+* eagerly embedded entries.
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The publish-root-relative output paths, or an empty array when absent.
+* @example
+* ```ts
+* readBundleOutputs(ctx, "js"); // ["assets/spa-abc123.js", "assets/chunk-9f8e.js"]
+* ```
+*/
+function readBundleOutputs(ctx, kind) {
+	const entry = ctx.state.buildCache.get(`${kind}:outputs`);
+	return Array.isArray(entry) ? entry : [];
+}
+/**
+* Render the stylesheet `<link>` tags for the fingerprinted CSS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<link rel="stylesheet">` tags (possibly `""`).
+* @example
+* ```ts
+* buildCssTags(ctx); // '<link rel="stylesheet" href="/assets/main-abc123.css">'
+* ```
+*/
+function buildCssTags(ctx) {
+	return Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`).join("");
+}
+/**
+* Render the module `<script>` tags for the fingerprinted JS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<script type="module">` tags (possibly `""`).
+* @example
+* ```ts
+* buildJsTags(ctx); // '<script type="module" src="/assets/spa-abc123.js"><\/script>'
+* ```
+*/
+function buildJsTags(ctx) {
+	return Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+}
+/**
+* Build the asset tag block from the fingerprinted manifests — both kinds by
+* default, or a single kind for the split `<!--moku:assets:css/js-->`
+* placeholders. Returns an empty string when `config.injectAssets === false`.
+* Asset paths are emitted as absolute (`/`-rooted) URLs.
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param kind - Restrict the block to one asset kind; omit for stylesheets + scripts.
+* @returns The injected asset tags, or `""` when injection is disabled.
+* @example
+* ```ts
+* buildAssetTags(ctx);        // <link …><script …><\/script>
+* buildAssetTags(ctx, "css"); // <link …> only
+* ```
+*/
+function buildAssetTags(ctx, kind) {
+	if (ctx.config.injectAssets === false) return "";
+	if (kind === "css") return buildCssTags(ctx);
+	if (kind === "js") return buildJsTags(ctx);
+	return buildCssTags(ctx) + buildJsTags(ctx);
+}
+/**
+* Substitute every `<!--moku:assets-->` family placeholder in a complete HTML
+* document: the combined block, the CSS-only block, and the JS-only block. A
+* document without placeholders passes through byte-identical — substitution is
+* strictly opt-in for app-owned pages (the not-found page).
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param html - The HTML document to substitute placeholders in.
+* @returns The document with all asset placeholders replaced.
+* @example
+* ```ts
+* substituteAssetPlaceholders(ctx, "<head><!--moku:assets:css--></head>");
+* ```
+*/
+function substituteAssetPlaceholders(ctx, html) {
+	return html.replaceAll(ASSETS_PLACEHOLDER, buildAssetTags(ctx)).replaceAll(CSS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "css")).replaceAll(JS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "js"));
+}
+/**
+* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
+* preserving the nested directory structure. Skips silently (returns `null`) when
+* the source directory does not exist.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The copy result, or `null` when the public directory is absent.
+* @example
+* ```ts
+* const result = await copyPublic(ctx);
+* ```
+*/
+async function copyPublic(ctx) {
+	const from = ctx.config.publicDir ?? "public";
+	if (!(0, node_fs.existsSync)(from)) {
+		ctx.log.debug("build:public", {
+			skipped: true,
+			from
+		});
+		return null;
+	}
+	await (0, node_fs_promises.cp)(from, ctx.config.outDir, { recursive: true });
+	ctx.log.debug("build:public", {
+		from,
+		dest: ctx.config.outDir
+	});
+	return {
+		from: node_path$1.default.normalize(from),
+		copied: 1
+	};
+}
+//#endregion
+//#region src/plugins/build/phases/cache-headers.ts
+/**
+* @file build phase — cache-headers. Emits `outDir/_headers` (Cloudflare Pages
+* header rules) so the CDN/browser cache can never serve a stale file: every
+* fingerprinted bundle gets a per-file immutable rule (its URL changes with its
+* content, so caching it forever is safe), and every OTHER URL — pages, content
+* images, feeds, data sidecars: stable URLs whose bytes may change between
+* deploys — gets a catch-all revalidation rule (an unchanged file still answers
+* `304 Not Modified` via its ETag, so it is effectively cached; a changed file is
+* picked up immediately). The app's own `<publicDir>/_headers` rules are appended
+* AFTER the generated ones so the app can override them. Gated by
+* `config.cacheHeaders` (`false` disables; default on).
+*/
+/**
+* `Cache-Control` for fingerprinted bundles: their URL embeds a content hash, so
+* the bytes behind a given URL can never change — cache them for a year, immutably.
+*/
+const DEFAULT_ASSETS_CACHE = "public, max-age=31536000, immutable";
+/**
+* `Cache-Control` for everything else (stable URLs): always revalidate with the
+* origin. Unchanged files still serve from cache via a `304` ETag round-trip;
+* changed files are fetched fresh — never stale, still cheap.
+*/
+const DEFAULT_PAGES_CACHE = "public, max-age=0, must-revalidate";
+/**
+* Cloudflare Pages caps `_headers` at 100 rules and silently ignores the rest —
+* a site whose bundle count pushes past the cap needs a warning, not silence.
+*/
+const CLOUDFLARE_RULE_LIMIT = 100;
+/**
+* Resolve the two `Cache-Control` values from `config.cacheHeaders` (`true` or an
+* object — `false` never reaches here; the pipeline gates the phase off).
+*
+* @param cacheHeaders - The `config.cacheHeaders` value.
+* @returns The `assets` (fingerprinted bundles) + `pages` (everything else) values.
+* @example
+* ```ts
+* resolvePolicy(true); // { assets: DEFAULT_ASSETS_CACHE, pages: DEFAULT_PAGES_CACHE }
+* ```
+*/
+function resolvePolicy(cacheHeaders) {
+	const policy = typeof cacheHeaders === "object" ? cacheHeaders : {};
+	return {
+		assets: policy.assets ?? DEFAULT_ASSETS_CACHE,
+		pages: policy.pages ?? DEFAULT_PAGES_CACHE
+	};
+}
+/**
+* Compose the generated rule blocks: the catch-all revalidation rule FIRST, then
+* one immutable rule per fingerprinted bundle file. Cloudflare applies every
+* matching rule and comma-joins duplicate headers (it does NOT override), so each
+* per-file rule must detach the catch-all's `Cache-Control` (`! Cache-Control`)
+* before attaching its own — otherwise a bundle would be served with two joined,
+* contradictory `Cache-Control` values.
+*
+* @param files - The fingerprinted bundle web paths (publish-root-relative).
+* @param policy - The resolved `Cache-Control` values.
+* @param policy.assets - The value for fingerprinted bundles.
+* @param policy.pages - The catch-all value for everything else.
+* @returns The generated rule blocks, in emission order.
+* @example
+* ```ts
+* composeRules(["assets/main-abc123.css"], { assets: "…", pages: "…" });
+* ```
+*/
+function composeRules(files, policy) {
+	return [`/*\n  Cache-Control: ${policy.pages}`, ...files.map((file) => `/${file}\n  ! Cache-Control\n  Cache-Control: ${policy.assets}`)];
+}
+/**
+* Read the app's own `<publicDir>/_headers` SOURCE file (not the copy the public
+* phase may have placed in outDir — composing from the source keeps this phase
+* idempotent and independent of phase ordering). Returns `""` when absent.
+*
+* @param publicDir - The configured public directory (or the default).
+* @returns The app's `_headers` content, or `""` when the file does not exist.
+* @example
+* ```ts
+* const appRules = await readAppHeaders("public");
+* ```
+*/
+async function readAppHeaders(publicDir) {
+	const source = node_path$1.default.join(publicDir, "_headers");
+	if (!(0, node_fs.existsSync)(source)) return "";
+	return (0, node_fs_promises.readFile)(source, "utf8");
+}
+/**
+* Emits `outDir/_headers`: the generated cache rules (catch-all revalidation +
+* per-file immutable bundle rules) followed by the app's own
+* `<publicDir>/_headers` content. App rules come LAST so they can override a
+* generated header — note Cloudflare comma-joins duplicates, so an app rule that
+* re-sets a generated header must detach it first (`! Cache-Control`). Overwrites
+* the verbatim copy the public phase made, which is why this phase must run after
+* the outputs phase group.
+*
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
+* @returns The written file path + generated rule count.
+* @example
+* ```ts
+* const result = await generateCacheHeaders(ctx);
+* ```
+*/
+async function generateCacheHeaders(ctx) {
+	const { outDir, publicDir, cacheHeaders } = ctx.config;
+	const policy = resolvePolicy(cacheHeaders);
+	const rules = composeRules([...readBundleOutputs(ctx, "css"), ...readBundleOutputs(ctx, "js")].toSorted(), policy);
+	const appHeaders = (await readAppHeaders(publicDir ?? "public")).trim();
+	const content = `${(appHeaders === "" ? rules : [...rules, appHeaders]).join("\n\n")}\n`;
+	if (rules.length > CLOUDFLARE_RULE_LIMIT) ctx.log.warn("build:cache-headers", {
+		rules: rules.length,
+		limit: CLOUDFLARE_RULE_LIMIT
+	});
+	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
+	const file = node_path$1.default.join(outDir, "_headers");
+	await (0, node_fs_promises.writeFile)(file, content, "utf8");
+	ctx.log.debug("build:cache-headers", {
+		path: file,
+		rules: rules.length
+	});
+	return {
+		path: file,
+		ruleCount: rules.length
+	};
+}
+//#endregion
 //#region src/plugins/build/phases/content.ts
 /**
 * @file build phase 2 — content. Delegates entirely to the content plugin via
@@ -4114,7 +4401,10 @@ async function generateLocaleRedirects(ctx) {
 //#region src/plugins/build/phases/not-found.ts
 /**
 * @file build phase — not-found. Emits `outDir/404.html` from configured route
-* content or a built-in default. Gated by `config.notFound` (false/unset disables).
+* content or a built-in default, substituting the `<!--moku:assets-->` family of
+* placeholders (the bundles are fingerprint-named, so an app-owned 404 page can
+* no longer hardcode a bundle URL). Gated by `config.notFound` (false/unset
+* disables).
 */
 /** The built-in default 404 page body when no custom route content is supplied. */
 const DEFAULT_BODY = "<h1>404</h1><p>The page you requested could not be found.</p>";
@@ -4154,11 +4444,13 @@ async function resolveHtml(notFound) {
 /**
 * Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
 * default page; `{ body }` writes the supplied HTML body content inside the
-* minimal document shell; `{ path }` writes the referenced HTML page file
-* verbatim (the app owns the whole document). No-op (returns `null`) when
-* `notFound` is false/unset.
+* minimal document shell; `{ path }` writes the referenced HTML page file (the
+* app owns the whole document). In every variant the `<!--moku:assets-->` /
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders are substituted
+* with the fingerprinted bundle tags — a page without placeholders passes through
+* byte-for-byte. No-op (returns `null`) when `notFound` is false/unset.
 *
-* @param ctx - Plugin context (provides `config`, `log`).
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
 * @returns The written file path, or `null` when disabled.
 * @example
 * ```ts
@@ -4171,7 +4463,7 @@ async function generateNotFound(ctx) {
 		ctx.log.debug("build:not-found", { skipped: true });
 		return null;
 	}
-	const html = await resolveHtml(notFound);
+	const html = substituteAssetPlaceholders(ctx, await resolveHtml(notFound));
 	await (0, node_fs_promises.mkdir)(outDir, { recursive: true });
 	const file = node_path$1.default.join(outDir, "404.html");
 	await (0, node_fs_promises.writeFile)(file, html, "utf8");
@@ -4910,45 +5202,9 @@ const dataPlugin = createPlugin$1("data", {
 const HEAD_PLACEHOLDER = "<!--moku:head-->";
 /** Template placeholder for the SSR-rendered body HTML. */
 const BODY_PLACEHOLDER = "<!--moku:body-->";
-/** Template placeholder for the injected asset `<link>`/`<script>` tags. */
-const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
 /** Template placeholder for the page's locale (`<html lang>`). */
 const LANG_PLACEHOLDER = "<!--moku:lang-->";
 /**
-* Read the bundle phase's hashed asset manifest for one kind from `state.buildCache`
-* as a typed {@link BuildCacheEntry} (no `Map<string, unknown>` reads).
-*
-* @param ctx - Plugin context (provides `state`).
-* @param kind - The asset kind key (`"css"` / `"js"`).
-* @returns The hashed-path manifest entry, or an empty object when absent.
-* @example
-* ```ts
-* readManifest(ctx, "css");
-* ```
-*/
-function readManifest(ctx, kind) {
-	const entry = ctx.state.buildCache.get(kind);
-	return entry && typeof entry === "object" ? entry : {};
-}
-/**
-* Build the asset `<link>`/`<script>` tag block from the hashed manifests. Returns
-* an empty string when `config.injectAssets === false`. Asset paths are emitted as
-* absolute (`/`-rooted) URLs.
-*
-* @param ctx - Plugin context (provides `state`, `config`).
-* @returns The injected asset tags, or `""` when injection is disabled.
-* @example
-* ```ts
-* buildAssetTags(ctx);
-* ```
-*/
-function buildAssetTags(ctx) {
-	if (ctx.config.injectAssets === false) return "";
-	const css = Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`);
-	const js = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`);
-	return [...css, ...js].join("");
-}
-/**
 * Compose the full static HTML document with the in-code shell, injecting the
 * build-id meta tag into `<head>` AFTER the head plugin's composed HTML (build
 * metadata, not content) and the asset tags at the end of `<head>`.
@@ -4967,18 +5223,21 @@ function renderDocument(parts) {
 * Fill a shell template's `<!--moku:lang-->` / `<!--moku:head-->` /
 * `<!--moku:body-->` / `<!--moku:assets-->` placeholders deterministically at build
 * time. `<!--moku:lang-->` carries the page locale (for `<html lang>`), so a single
-* shared template stays locale-correct across every locale.
+* shared template stays locale-correct across every locale. The split
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders inject one asset
+* kind each — for shells that, e.g., link stylesheets in `<head>` but place
+* scripts at the end of `<body>`.
 *
 * @param template - The raw shell template HTML.
 * @param parts - The composed head/body/assets/locale pieces.
 * @returns The filled document string.
 * @example
 * ```ts
-* fillTemplate(shell, { head, body, assets, locale: "en" });
+* fillTemplate(shell, { head, body, assets, assetsCss, assetsJs, locale: "en" });
 * ```
 */
 function fillTemplate(template, parts) {
-	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets);
+	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets).replaceAll(CSS_ASSETS_PLACEHOLDER, parts.assetsCss).replaceAll(JS_ASSETS_PLACEHOLDER, parts.assetsJs);
 }
 /**
 * Resolve the compiled entry for a manifest definition, asserting the router
@@ -5329,6 +5588,8 @@ async function renderInstance(ctx, instance, shell, reuse) {
 		head: composeHeadHtml(ctx, instance, url, routeContext, data),
 		body: renderBodyCached(ctx, instance, routeContext, data, reuse),
 		assets: shell.assets,
+		assetsCss: shell.assetsCss,
+		assetsJs: shell.assetsJs,
 		locale
 	};
 	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
@@ -5368,6 +5629,8 @@ async function prepareShell(ctx) {
 	const template = typeof templatePath === "string" && (0, node_fs.existsSync)(templatePath) ? await (0, node_fs_promises.readFile)(templatePath, "utf8") : null;
 	return {
 		assets: buildAssetTags(ctx),
+		assetsCss: buildAssetTags(ctx, "css"),
+		assetsJs: buildAssetTags(ctx, "js"),
 		template,
 		defaultLocale: ctx.require(i18nPlugin).defaultLocale()
 	};
@@ -5513,37 +5776,6 @@ async function renderPages(ctx, options) {
 		rootHtml: findRootHtml(rendered)
 	};
 }
-/**
-* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
-* preserving the nested directory structure. Skips silently (returns `null`) when
-* the source directory does not exist.
-*
-* @param ctx - Plugin context (provides `config`, `log`).
-* @returns The copy result, or `null` when the public directory is absent.
-* @example
-* ```ts
-* const result = await copyPublic(ctx);
-* ```
-*/
-async function copyPublic(ctx) {
-	const from = ctx.config.publicDir ?? "public";
-	if (!(0, node_fs.existsSync)(from)) {
-		ctx.log.debug("build:public", {
-			skipped: true,
-			from
-		});
-		return null;
-	}
-	await (0, node_fs_promises.cp)(from, ctx.config.outDir, { recursive: true });
-	ctx.log.debug("build:public", {
-		from,
-		dest: ctx.config.outDir
-	});
-	return {
-		from: node_path$1.default.normalize(from),
-		copied: 1
-	};
-}
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -5825,6 +6057,7 @@ const PHASE_ORDER = [
 	"public",
 	"not-found",
 	"locale-redirects",
+	"cache-headers",
 	"root-index"
 ];
 /**
@@ -5919,7 +6152,7 @@ async function runOutputs(ctx) {
 }
 /**
 * Executes the full SSG pipeline for one run: clean → bundle → content/images →
-* pages → feeds/sitemap/og-images → root-index. Orchestrates `ctx.require` pulls
+* pages → feeds/sitemap/og-images → cache-headers → root-index. Orchestrates `ctx.require` pulls
 * and `Promise.all` only — never inlines dependency domain logic. Emits a
 * `build:phase` boundary per phase and `build:complete` once at the end.
 *
@@ -5960,6 +6193,7 @@ async function runPipeline(ctx, options) {
 	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext, { reuse: plan.renderReuse }));
 	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
+	if (phaseContext.config.cacheHeaders !== false) await withPhase(phaseContext, "cache-headers", () => generateCacheHeaders(phaseContext));
 	await withPhase(phaseContext, "root-index", async () => {
 		if (pages.rootHtml !== null) await (0, node_fs_promises.writeFile)(node_path$1.default.join(outDir, "index.html"), pages.rootHtml, "utf8");
 	});

package/dist/index.d.cts

@@ -1667,8 +1667,13 @@ type Config$3 = {
    * - `true` — the built-in default page.
    * - `{ body }` — literal HTML body content, wrapped in a minimal document shell.
    * - `{ path }` — path to a complete HTML page file (resolved from the project
-   *   root), written out VERBATIM so the app owns the whole document (its own
-   *   `<head>`, asset links, and body).
+   *   root) so the app owns the whole document (its own `<head>`, asset links,
+   *   and body).
+   *
+   * In every variant the `<!--moku:assets-->` / `<!--moku:assets:css-->` /
+   * `<!--moku:assets:js-->` placeholders are substituted with the fingerprinted
+   * bundle tags (bundle filenames embed a content hash, so a 404 page cannot
+   * hardcode them); a page without placeholders is written byte-for-byte.
    *
    * `path` takes precedence over `body` when both are set. Default `false`.
    */
@@ -1685,10 +1690,31 @@ type Config$3 = {
    * `<!--moku:lang-->` (page locale for `<html lang>`),
    * `<!--moku:head-->` (composed `<head>` inner HTML),
    * `<!--moku:assets-->` (injected `<link>`/`<script>` tags),
+   * `<!--moku:assets:css-->` / `<!--moku:assets:js-->` (one asset kind each, for
+   * shells that link stylesheets in `<head>` but script tags elsewhere),
    * `<!--moku:body-->` (SSR body HTML).
    * When unset, the built-in shell is used (it emits charset + viewport by default).
    */
   template?: string;
+  /**
+   * Emit `outDir/_headers` (Cloudflare Pages header rules) for CDN/browser cache
+   * protection. Generated rules: every fingerprinted bundle output gets a
+   * per-file `Cache-Control: <assets>` rule (default immutable, 1 year — its URL
+   * embeds a content hash, so the bytes behind it can never change), and every
+   * other URL — pages, content images, feeds, data sidecars: stable URLs whose
+   * bytes MAY change between deploys — gets the catch-all
+   * `Cache-Control: <pages>` rule (default always-revalidate: unchanged files
+   * still answer `304 Not Modified` from their ETag, changed files are picked up
+   * immediately). The app's own `<publicDir>/_headers` content is appended AFTER
+   * the generated rules so the app can override them (detach a generated header
+   * first with `! Cache-Control` — Cloudflare comma-joins duplicate headers).
+   * `false` disables the phase; an object overrides one or both values.
+   * Default `true`.
+   */
+  cacheHeaders?: boolean | {
+    assets?: string;
+    pages?: string;
+  };
 };
 /**
  * A typed asset-manifest entry for one bundled asset kind (CSS or JS): a map of the
@@ -1755,7 +1781,7 @@ interface State$3 {
  * const phase: PhaseName = "bundle";
  * ```
  */
-type PhaseName = "bundle" | "content" | "images" | "pages" | "content-images" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "root-index";
+type PhaseName = "bundle" | "content" | "images" | "pages" | "content-images" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "cache-headers" | "root-index";
 /**
  * Result of a completed build run.
  *
@@ -1784,7 +1810,7 @@ interface BuildResult {
  * const dev: BuildRunOverrides = { minify: false, feeds: false, sitemap: false };
  * ```
  */
-type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound">>>;
+type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound" | "cacheHeaders">>>;
 /**
  * Options for a single {@link Api.run} call. All fields are optional; an absent/empty
  * options object runs the full production build (clean + every configured phase). The

package/dist/index.d.mts

@@ -1667,8 +1667,13 @@ type Config$3 = {
    * - `true` — the built-in default page.
    * - `{ body }` — literal HTML body content, wrapped in a minimal document shell.
    * - `{ path }` — path to a complete HTML page file (resolved from the project
-   *   root), written out VERBATIM so the app owns the whole document (its own
-   *   `<head>`, asset links, and body).
+   *   root) so the app owns the whole document (its own `<head>`, asset links,
+   *   and body).
+   *
+   * In every variant the `<!--moku:assets-->` / `<!--moku:assets:css-->` /
+   * `<!--moku:assets:js-->` placeholders are substituted with the fingerprinted
+   * bundle tags (bundle filenames embed a content hash, so a 404 page cannot
+   * hardcode them); a page without placeholders is written byte-for-byte.
    *
    * `path` takes precedence over `body` when both are set. Default `false`.
    */
@@ -1685,10 +1690,31 @@ type Config$3 = {
    * `<!--moku:lang-->` (page locale for `<html lang>`),
    * `<!--moku:head-->` (composed `<head>` inner HTML),
    * `<!--moku:assets-->` (injected `<link>`/`<script>` tags),
+   * `<!--moku:assets:css-->` / `<!--moku:assets:js-->` (one asset kind each, for
+   * shells that link stylesheets in `<head>` but script tags elsewhere),
    * `<!--moku:body-->` (SSR body HTML).
    * When unset, the built-in shell is used (it emits charset + viewport by default).
    */
   template?: string;
+  /**
+   * Emit `outDir/_headers` (Cloudflare Pages header rules) for CDN/browser cache
+   * protection. Generated rules: every fingerprinted bundle output gets a
+   * per-file `Cache-Control: <assets>` rule (default immutable, 1 year — its URL
+   * embeds a content hash, so the bytes behind it can never change), and every
+   * other URL — pages, content images, feeds, data sidecars: stable URLs whose
+   * bytes MAY change between deploys — gets the catch-all
+   * `Cache-Control: <pages>` rule (default always-revalidate: unchanged files
+   * still answer `304 Not Modified` from their ETag, changed files are picked up
+   * immediately). The app's own `<publicDir>/_headers` content is appended AFTER
+   * the generated rules so the app can override them (detach a generated header
+   * first with `! Cache-Control` — Cloudflare comma-joins duplicate headers).
+   * `false` disables the phase; an object overrides one or both values.
+   * Default `true`.
+   */
+  cacheHeaders?: boolean | {
+    assets?: string;
+    pages?: string;
+  };
 };
 /**
  * A typed asset-manifest entry for one bundled asset kind (CSS or JS): a map of the
@@ -1755,7 +1781,7 @@ interface State$3 {
  * const phase: PhaseName = "bundle";
  * ```
  */
-type PhaseName = "bundle" | "content" | "images" | "pages" | "content-images" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "root-index";
+type PhaseName = "bundle" | "content" | "images" | "pages" | "content-images" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "cache-headers" | "root-index";
 /**
  * Result of a completed build run.
  *
@@ -1784,7 +1810,7 @@ interface BuildResult {
  * const dev: BuildRunOverrides = { minify: false, feeds: false, sitemap: false };
  * ```
  */
-type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound">>>;
+type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound" | "cacheHeaders">>>;
 /**
  * Options for a single {@link Api.run} call. All fields are optional; an absent/empty
  * options object runs the full production build (clean + every configured phase). The

package/dist/index.mjs

@@ -3473,7 +3473,9 @@ const headPlugin = createPlugin$1("head", {
 //#region src/plugins/build/phases/bundle.ts
 /**
 * @file build phase 1 — bundle. Runs `Bun.build` for CSS and JS separately into
-* outDir (honoring `config.minify`); caches hashed asset paths for the pages phase.
+* outDir (honoring `config.minify`) with content-hashed output naming; caches the
+* fingerprinted asset paths for the pages phase and the complete output list for
+* the cache-headers phase.
 */
 /** Conventional CSS entry candidates (project-relative). */
 const CSS_ENTRY_CANDIDATES = ["src/client/styles.css", "src/styles/main.css"];
@@ -3484,18 +3486,38 @@ const JS_ENTRY_CANDIDATES = [
 	"src/main.ts"
 ];
 /**
+* `Bun.build` output naming with a content hash in EVERY filename (entry points
+* included — Bun's default only hashes chunks/assets). A bundle's URL therefore
+* changes whenever its bytes change, which is what lets the cache-headers phase
+* mark each bundle immutable: a CDN/browser may cache it forever, and a deploy
+* that changes the code ships a NEW URL instead of fighting a stale cached copy.
+* Pages always embed bundle URLs via the `state.buildCache` manifest, so hashed
+* names flow through with no app-side changes (hardcoded asset URLs must move to
+* the `<!--moku:assets-->` placeholders). Chunk naming keeps Bun's default
+* `chunk-` prefix (chunks were already hash-only named).
+*/
+const FINGERPRINT_NAMING = {
+	entry: "[dir]/[name]-[hash].[ext]",
+	chunk: "chunk-[hash].[ext]",
+	asset: "[name]-[hash].[ext]"
+};
+/**
 * The default bundler runner — adapts the built-in `Bun.build`.
 *
-* @param options - Entry/outdir/minify/splitting/target settings forwarded to `Bun.build`.
+* @param options - Entry/outdir/minify/splitting/target/naming settings forwarded to `Bun.build`.
 * @param options.entrypoints - Entry files for this build.
 * @param options.outdir - Output directory.
 * @param options.minify - Whether to minify.
 * @param options.splitting - Whether to split dynamic imports into lazy chunks.
 * @param options.target - The bundling target platform.
+* @param options.naming - Output naming templates (content-hashed filenames).
+* @param options.naming.entry - Naming template for entry-point outputs.
+* @param options.naming.chunk - Naming template for lazy split chunks.
+* @param options.naming.asset - Naming template for additional emitted assets.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser" });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING });
 * ```
 */
 async function defaultRunner(options) {
@@ -3587,7 +3609,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		outdir,
 		minify,
 		splitting: true,
-		target: "browser"
+		target: "browser",
+		naming: FINGERPRINT_NAMING
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -3596,6 +3619,7 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		hashed[path.basename(output.path)] = normalizeAssetPath(output.path, outDir);
 	}
 	ctx.state.buildCache.set(kind, hashed);
+	ctx.state.buildCache.set(`${kind}:outputs`, result.outputs.map((output) => normalizeAssetPath(output.path, outDir)));
 	ctx.log.debug("build:bundle", {
 		kind,
 		count: result.outputs.length
@@ -3627,6 +3651,269 @@ async function bundle(ctx, options = {}) {
 	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/asset-tags.ts
+/** Template placeholder for the injected asset tags (stylesheets + scripts). */
+const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
+/** Template placeholder for the injected stylesheet `<link>` tags ONLY. */
+const CSS_ASSETS_PLACEHOLDER = "<!--moku:assets:css-->";
+/** Template placeholder for the injected `<script>` tags ONLY. */
+const JS_ASSETS_PLACEHOLDER = "<!--moku:assets:js-->";
+/**
+* Read the bundle phase's fingerprinted asset manifest for one kind from
+* `state.buildCache` as a typed {@link BuildCacheEntry} (no `Map<string, unknown>`
+* reads at call sites).
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The fingerprinted-path manifest entry, or an empty object when absent.
+* @example
+* ```ts
+* readManifest(ctx, "css"); // { "main.css": "assets/main-abc123.css" }
+* ```
+*/
+function readManifest(ctx, kind) {
+	const entry = ctx.state.buildCache.get(kind);
+	return entry && typeof entry === "object" ? entry : {};
+}
+/**
+* Read the bundle phase's COMPLETE output list for one kind (entries + lazy split
+* chunks, web paths relative to the publish root) from `state.buildCache`. Unlike
+* {@link readManifest} this includes chunks — it feeds the cache-headers phase's
+* per-file immutable rules, where every fingerprinted file counts, not just the
+* eagerly embedded entries.
+*
+* @param ctx - Plugin context (provides `state`).
+* @param kind - The asset kind key (`"css"` / `"js"`).
+* @returns The publish-root-relative output paths, or an empty array when absent.
+* @example
+* ```ts
+* readBundleOutputs(ctx, "js"); // ["assets/spa-abc123.js", "assets/chunk-9f8e.js"]
+* ```
+*/
+function readBundleOutputs(ctx, kind) {
+	const entry = ctx.state.buildCache.get(`${kind}:outputs`);
+	return Array.isArray(entry) ? entry : [];
+}
+/**
+* Render the stylesheet `<link>` tags for the fingerprinted CSS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<link rel="stylesheet">` tags (possibly `""`).
+* @example
+* ```ts
+* buildCssTags(ctx); // '<link rel="stylesheet" href="/assets/main-abc123.css">'
+* ```
+*/
+function buildCssTags(ctx) {
+	return Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`).join("");
+}
+/**
+* Render the module `<script>` tags for the fingerprinted JS manifest.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The concatenated `<script type="module">` tags (possibly `""`).
+* @example
+* ```ts
+* buildJsTags(ctx); // '<script type="module" src="/assets/spa-abc123.js"><\/script>'
+* ```
+*/
+function buildJsTags(ctx) {
+	return Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+}
+/**
+* Build the asset tag block from the fingerprinted manifests — both kinds by
+* default, or a single kind for the split `<!--moku:assets:css/js-->`
+* placeholders. Returns an empty string when `config.injectAssets === false`.
+* Asset paths are emitted as absolute (`/`-rooted) URLs.
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param kind - Restrict the block to one asset kind; omit for stylesheets + scripts.
+* @returns The injected asset tags, or `""` when injection is disabled.
+* @example
+* ```ts
+* buildAssetTags(ctx);        // <link …><script …><\/script>
+* buildAssetTags(ctx, "css"); // <link …> only
+* ```
+*/
+function buildAssetTags(ctx, kind) {
+	if (ctx.config.injectAssets === false) return "";
+	if (kind === "css") return buildCssTags(ctx);
+	if (kind === "js") return buildJsTags(ctx);
+	return buildCssTags(ctx) + buildJsTags(ctx);
+}
+/**
+* Substitute every `<!--moku:assets-->` family placeholder in a complete HTML
+* document: the combined block, the CSS-only block, and the JS-only block. A
+* document without placeholders passes through byte-identical — substitution is
+* strictly opt-in for app-owned pages (the not-found page).
+*
+* @param ctx - Plugin context (provides `state`, `config`).
+* @param html - The HTML document to substitute placeholders in.
+* @returns The document with all asset placeholders replaced.
+* @example
+* ```ts
+* substituteAssetPlaceholders(ctx, "<head><!--moku:assets:css--></head>");
+* ```
+*/
+function substituteAssetPlaceholders(ctx, html) {
+	return html.replaceAll(ASSETS_PLACEHOLDER, buildAssetTags(ctx)).replaceAll(CSS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "css")).replaceAll(JS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "js"));
+}
+/**
+* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
+* preserving the nested directory structure. Skips silently (returns `null`) when
+* the source directory does not exist.
+*
+* @param ctx - Plugin context (provides `config`, `log`).
+* @returns The copy result, or `null` when the public directory is absent.
+* @example
+* ```ts
+* const result = await copyPublic(ctx);
+* ```
+*/
+async function copyPublic(ctx) {
+	const from = ctx.config.publicDir ?? "public";
+	if (!existsSync(from)) {
+		ctx.log.debug("build:public", {
+			skipped: true,
+			from
+		});
+		return null;
+	}
+	await cp(from, ctx.config.outDir, { recursive: true });
+	ctx.log.debug("build:public", {
+		from,
+		dest: ctx.config.outDir
+	});
+	return {
+		from: path.normalize(from),
+		copied: 1
+	};
+}
+//#endregion
+//#region src/plugins/build/phases/cache-headers.ts
+/**
+* @file build phase — cache-headers. Emits `outDir/_headers` (Cloudflare Pages
+* header rules) so the CDN/browser cache can never serve a stale file: every
+* fingerprinted bundle gets a per-file immutable rule (its URL changes with its
+* content, so caching it forever is safe), and every OTHER URL — pages, content
+* images, feeds, data sidecars: stable URLs whose bytes may change between
+* deploys — gets a catch-all revalidation rule (an unchanged file still answers
+* `304 Not Modified` via its ETag, so it is effectively cached; a changed file is
+* picked up immediately). The app's own `<publicDir>/_headers` rules are appended
+* AFTER the generated ones so the app can override them. Gated by
+* `config.cacheHeaders` (`false` disables; default on).
+*/
+/**
+* `Cache-Control` for fingerprinted bundles: their URL embeds a content hash, so
+* the bytes behind a given URL can never change — cache them for a year, immutably.
+*/
+const DEFAULT_ASSETS_CACHE = "public, max-age=31536000, immutable";
+/**
+* `Cache-Control` for everything else (stable URLs): always revalidate with the
+* origin. Unchanged files still serve from cache via a `304` ETag round-trip;
+* changed files are fetched fresh — never stale, still cheap.
+*/
+const DEFAULT_PAGES_CACHE = "public, max-age=0, must-revalidate";
+/**
+* Cloudflare Pages caps `_headers` at 100 rules and silently ignores the rest —
+* a site whose bundle count pushes past the cap needs a warning, not silence.
+*/
+const CLOUDFLARE_RULE_LIMIT = 100;
+/**
+* Resolve the two `Cache-Control` values from `config.cacheHeaders` (`true` or an
+* object — `false` never reaches here; the pipeline gates the phase off).
+*
+* @param cacheHeaders - The `config.cacheHeaders` value.
+* @returns The `assets` (fingerprinted bundles) + `pages` (everything else) values.
+* @example
+* ```ts
+* resolvePolicy(true); // { assets: DEFAULT_ASSETS_CACHE, pages: DEFAULT_PAGES_CACHE }
+* ```
+*/
+function resolvePolicy(cacheHeaders) {
+	const policy = typeof cacheHeaders === "object" ? cacheHeaders : {};
+	return {
+		assets: policy.assets ?? DEFAULT_ASSETS_CACHE,
+		pages: policy.pages ?? DEFAULT_PAGES_CACHE
+	};
+}
+/**
+* Compose the generated rule blocks: the catch-all revalidation rule FIRST, then
+* one immutable rule per fingerprinted bundle file. Cloudflare applies every
+* matching rule and comma-joins duplicate headers (it does NOT override), so each
+* per-file rule must detach the catch-all's `Cache-Control` (`! Cache-Control`)
+* before attaching its own — otherwise a bundle would be served with two joined,
+* contradictory `Cache-Control` values.
+*
+* @param files - The fingerprinted bundle web paths (publish-root-relative).
+* @param policy - The resolved `Cache-Control` values.
+* @param policy.assets - The value for fingerprinted bundles.
+* @param policy.pages - The catch-all value for everything else.
+* @returns The generated rule blocks, in emission order.
+* @example
+* ```ts
+* composeRules(["assets/main-abc123.css"], { assets: "…", pages: "…" });
+* ```
+*/
+function composeRules(files, policy) {
+	return [`/*\n  Cache-Control: ${policy.pages}`, ...files.map((file) => `/${file}\n  ! Cache-Control\n  Cache-Control: ${policy.assets}`)];
+}
+/**
+* Read the app's own `<publicDir>/_headers` SOURCE file (not the copy the public
+* phase may have placed in outDir — composing from the source keeps this phase
+* idempotent and independent of phase ordering). Returns `""` when absent.
+*
+* @param publicDir - The configured public directory (or the default).
+* @returns The app's `_headers` content, or `""` when the file does not exist.
+* @example
+* ```ts
+* const appRules = await readAppHeaders("public");
+* ```
+*/
+async function readAppHeaders(publicDir) {
+	const source = path.join(publicDir, "_headers");
+	if (!existsSync(source)) return "";
+	return readFile(source, "utf8");
+}
+/**
+* Emits `outDir/_headers`: the generated cache rules (catch-all revalidation +
+* per-file immutable bundle rules) followed by the app's own
+* `<publicDir>/_headers` content. App rules come LAST so they can override a
+* generated header — note Cloudflare comma-joins duplicates, so an app rule that
+* re-sets a generated header must detach it first (`! Cache-Control`). Overwrites
+* the verbatim copy the public phase made, which is why this phase must run after
+* the outputs phase group.
+*
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
+* @returns The written file path + generated rule count.
+* @example
+* ```ts
+* const result = await generateCacheHeaders(ctx);
+* ```
+*/
+async function generateCacheHeaders(ctx) {
+	const { outDir, publicDir, cacheHeaders } = ctx.config;
+	const policy = resolvePolicy(cacheHeaders);
+	const rules = composeRules([...readBundleOutputs(ctx, "css"), ...readBundleOutputs(ctx, "js")].toSorted(), policy);
+	const appHeaders = (await readAppHeaders(publicDir ?? "public")).trim();
+	const content = `${(appHeaders === "" ? rules : [...rules, appHeaders]).join("\n\n")}\n`;
+	if (rules.length > CLOUDFLARE_RULE_LIMIT) ctx.log.warn("build:cache-headers", {
+		rules: rules.length,
+		limit: CLOUDFLARE_RULE_LIMIT
+	});
+	await mkdir(outDir, { recursive: true });
+	const file = path.join(outDir, "_headers");
+	await writeFile(file, content, "utf8");
+	ctx.log.debug("build:cache-headers", {
+		path: file,
+		rules: rules.length
+	});
+	return {
+		path: file,
+		ruleCount: rules.length
+	};
+}
+//#endregion
 //#region src/plugins/build/phases/content.ts
 /**
 * @file build phase 2 — content. Delegates entirely to the content plugin via
@@ -4101,7 +4388,10 @@ async function generateLocaleRedirects(ctx) {
 //#region src/plugins/build/phases/not-found.ts
 /**
 * @file build phase — not-found. Emits `outDir/404.html` from configured route
-* content or a built-in default. Gated by `config.notFound` (false/unset disables).
+* content or a built-in default, substituting the `<!--moku:assets-->` family of
+* placeholders (the bundles are fingerprint-named, so an app-owned 404 page can
+* no longer hardcode a bundle URL). Gated by `config.notFound` (false/unset
+* disables).
 */
 /** The built-in default 404 page body when no custom route content is supplied. */
 const DEFAULT_BODY = "<h1>404</h1><p>The page you requested could not be found.</p>";
@@ -4141,11 +4431,13 @@ async function resolveHtml(notFound) {
 /**
 * Emits `outDir/404.html`. When `config.notFound` is `true`, writes the built-in
 * default page; `{ body }` writes the supplied HTML body content inside the
-* minimal document shell; `{ path }` writes the referenced HTML page file
-* verbatim (the app owns the whole document). No-op (returns `null`) when
-* `notFound` is false/unset.
+* minimal document shell; `{ path }` writes the referenced HTML page file (the
+* app owns the whole document). In every variant the `<!--moku:assets-->` /
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders are substituted
+* with the fingerprinted bundle tags — a page without placeholders passes through
+* byte-for-byte. No-op (returns `null`) when `notFound` is false/unset.
 *
-* @param ctx - Plugin context (provides `config`, `log`).
+* @param ctx - Plugin context (provides `state`, `config`, `log`).
 * @returns The written file path, or `null` when disabled.
 * @example
 * ```ts
@@ -4158,7 +4450,7 @@ async function generateNotFound(ctx) {
 		ctx.log.debug("build:not-found", { skipped: true });
 		return null;
 	}
-	const html = await resolveHtml(notFound);
+	const html = substituteAssetPlaceholders(ctx, await resolveHtml(notFound));
 	await mkdir(outDir, { recursive: true });
 	const file = path.join(outDir, "404.html");
 	await writeFile(file, html, "utf8");
@@ -4897,45 +5189,9 @@ const dataPlugin = createPlugin$1("data", {
 const HEAD_PLACEHOLDER = "<!--moku:head-->";
 /** Template placeholder for the SSR-rendered body HTML. */
 const BODY_PLACEHOLDER = "<!--moku:body-->";
-/** Template placeholder for the injected asset `<link>`/`<script>` tags. */
-const ASSETS_PLACEHOLDER = "<!--moku:assets-->";
 /** Template placeholder for the page's locale (`<html lang>`). */
 const LANG_PLACEHOLDER = "<!--moku:lang-->";
 /**
-* Read the bundle phase's hashed asset manifest for one kind from `state.buildCache`
-* as a typed {@link BuildCacheEntry} (no `Map<string, unknown>` reads).
-*
-* @param ctx - Plugin context (provides `state`).
-* @param kind - The asset kind key (`"css"` / `"js"`).
-* @returns The hashed-path manifest entry, or an empty object when absent.
-* @example
-* ```ts
-* readManifest(ctx, "css");
-* ```
-*/
-function readManifest(ctx, kind) {
-	const entry = ctx.state.buildCache.get(kind);
-	return entry && typeof entry === "object" ? entry : {};
-}
-/**
-* Build the asset `<link>`/`<script>` tag block from the hashed manifests. Returns
-* an empty string when `config.injectAssets === false`. Asset paths are emitted as
-* absolute (`/`-rooted) URLs.
-*
-* @param ctx - Plugin context (provides `state`, `config`).
-* @returns The injected asset tags, or `""` when injection is disabled.
-* @example
-* ```ts
-* buildAssetTags(ctx);
-* ```
-*/
-function buildAssetTags(ctx) {
-	if (ctx.config.injectAssets === false) return "";
-	const css = Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`);
-	const js = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`);
-	return [...css, ...js].join("");
-}
-/**
 * Compose the full static HTML document with the in-code shell, injecting the
 * build-id meta tag into `<head>` AFTER the head plugin's composed HTML (build
 * metadata, not content) and the asset tags at the end of `<head>`.
@@ -4954,18 +5210,21 @@ function renderDocument(parts) {
 * Fill a shell template's `<!--moku:lang-->` / `<!--moku:head-->` /
 * `<!--moku:body-->` / `<!--moku:assets-->` placeholders deterministically at build
 * time. `<!--moku:lang-->` carries the page locale (for `<html lang>`), so a single
-* shared template stays locale-correct across every locale.
+* shared template stays locale-correct across every locale. The split
+* `<!--moku:assets:css-->` / `<!--moku:assets:js-->` placeholders inject one asset
+* kind each — for shells that, e.g., link stylesheets in `<head>` but place
+* scripts at the end of `<body>`.
 *
 * @param template - The raw shell template HTML.
 * @param parts - The composed head/body/assets/locale pieces.
 * @returns The filled document string.
 * @example
 * ```ts
-* fillTemplate(shell, { head, body, assets, locale: "en" });
+* fillTemplate(shell, { head, body, assets, assetsCss, assetsJs, locale: "en" });
 * ```
 */
 function fillTemplate(template, parts) {
-	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets);
+	return template.replaceAll(LANG_PLACEHOLDER, parts.locale).replaceAll(HEAD_PLACEHOLDER, parts.head).replaceAll(BODY_PLACEHOLDER, parts.body).replaceAll(ASSETS_PLACEHOLDER, parts.assets).replaceAll(CSS_ASSETS_PLACEHOLDER, parts.assetsCss).replaceAll(JS_ASSETS_PLACEHOLDER, parts.assetsJs);
 }
 /**
 * Resolve the compiled entry for a manifest definition, asserting the router
@@ -5316,6 +5575,8 @@ async function renderInstance(ctx, instance, shell, reuse) {
 		head: composeHeadHtml(ctx, instance, url, routeContext, data),
 		body: renderBodyCached(ctx, instance, routeContext, data, reuse),
 		assets: shell.assets,
+		assetsCss: shell.assetsCss,
+		assetsJs: shell.assetsJs,
 		locale
 	};
 	const html = shell.template === null ? renderDocument(parts) : fillTemplate(shell.template, parts);
@@ -5355,6 +5616,8 @@ async function prepareShell(ctx) {
 	const template = typeof templatePath === "string" && existsSync(templatePath) ? await readFile(templatePath, "utf8") : null;
 	return {
 		assets: buildAssetTags(ctx),
+		assetsCss: buildAssetTags(ctx, "css"),
+		assetsJs: buildAssetTags(ctx, "js"),
 		template,
 		defaultLocale: ctx.require(i18nPlugin).defaultLocale()
 	};
@@ -5500,37 +5763,6 @@ async function renderPages(ctx, options) {
 		rootHtml: findRootHtml(rendered)
 	};
 }
-/**
-* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
-* preserving the nested directory structure. Skips silently (returns `null`) when
-* the source directory does not exist.
-*
-* @param ctx - Plugin context (provides `config`, `log`).
-* @returns The copy result, or `null` when the public directory is absent.
-* @example
-* ```ts
-* const result = await copyPublic(ctx);
-* ```
-*/
-async function copyPublic(ctx) {
-	const from = ctx.config.publicDir ?? "public";
-	if (!existsSync(from)) {
-		ctx.log.debug("build:public", {
-			skipped: true,
-			from
-		});
-		return null;
-	}
-	await cp(from, ctx.config.outDir, { recursive: true });
-	ctx.log.debug("build:public", {
-		from,
-		dest: ctx.config.outDir
-	});
-	return {
-		from: path.normalize(from),
-		copied: 1
-	};
-}
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -5812,6 +6044,7 @@ const PHASE_ORDER = [
 	"public",
 	"not-found",
 	"locale-redirects",
+	"cache-headers",
 	"root-index"
 ];
 /**
@@ -5906,7 +6139,7 @@ async function runOutputs(ctx) {
 }
 /**
 * Executes the full SSG pipeline for one run: clean → bundle → content/images →
-* pages → feeds/sitemap/og-images → root-index. Orchestrates `ctx.require` pulls
+* pages → feeds/sitemap/og-images → cache-headers → root-index. Orchestrates `ctx.require` pulls
 * and `Promise.all` only — never inlines dependency domain logic. Emits a
 * `build:phase` boundary per phase and `build:complete` once at the end.
 *
@@ -5947,6 +6180,7 @@ async function runPipeline(ctx, options) {
 	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext, { reuse: plan.renderReuse }));
 	await withPhase(phaseContext, "content-images", () => copyContentImages(phaseContext));
 	await runOutputs(phaseContext);
+	if (phaseContext.config.cacheHeaders !== false) await withPhase(phaseContext, "cache-headers", () => generateCacheHeaders(phaseContext));
 	await withPhase(phaseContext, "root-index", async () => {
 		if (pages.rootHtml !== null) await writeFile(path.join(outDir, "index.html"), pages.rootHtml, "utf8");
 	});

package/package.json

@@ -118,5 +118,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.7.0"
+  "version": "1.8.0"
 }