@moku-labs/web 1.7.0 → 1.8.1

package/dist/index.cjs

@@ -3169,6 +3169,26 @@ function composeHead(input) {
 	}), ...head.elements ?? []]);
 }
 /**
+* Resolve the FINAL document title for a route's head config — the same value
+* {@link composeHead} emits in its `<title>` element. A route-supplied `title`-keyed
+* element wins the keyed last-wins de-dupe over the templated base title (how a route
+* pins a bare title past `titleTemplate`), so it must win here too; otherwise the
+* template is applied to `head.title ?? site.name()`. Reused by `spa` for the client
+* DATA-path `document.title` sync, so client-side navigation matches the SSG output.
+*
+* @param head - The route's head config (may be `undefined` for head-less routes).
+* @param defaults - The normalized head defaults (provides `titleTemplate`).
+* @param site - The site slice (title fallback).
+* @returns The final document title string.
+* @example composeTitle({ title: "Page 2" }, defaults, site) // "Page 2 — Site"
+*/
+function composeTitle(head, defaults, site) {
+	const config = head ?? {};
+	const pinned = config.elements?.findLast((element) => element.key === "title");
+	if (pinned?.children !== void 0) return pinned.children;
+	return applyTemplate(config.title ?? site.name(), defaults.titleTemplate);
+}
+/**
 * Compose the SITE-LEVEL Open Graph / Twitter block for a bare-path redirect or landing
 * page that has no per-route head of its own. Returns `[]` UNLESS a `defaultOgImage` is
 * configured — so apps that opt out keep a bare redirect (no behavior change). The site
@@ -3338,6 +3358,21 @@ function createApi$4(ctx) {
 				url: site.canonical(input.url),
 				...ogLocale === void 0 ? {} : { ogLocale }
 			}));
+		},
+		/**
+		* Resolve the FINAL document title for a route's head config — the same value `render`
+		* emits in its `<title>` element. Pulled by `spa` on the client DATA path so a
+		* client-side navigation's `document.title` matches the SSG output.
+		*
+		* @param head - The route's head config (may be `undefined` for head-less routes).
+		* @returns The final document title string.
+		* @example
+		* ```ts
+		* api.composeTitle({ title: "Page 2" }); // "Page 2 — Site"
+		* ```
+		*/
+		composeTitle(head) {
+			return composeTitle(head, readDefaults(ctx.state), ctx.require(sitePlugin));
 		}
 	};
 }
@@ -3486,7 +3521,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 +3534,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 +3657,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 +3667,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 +3699,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 +4436,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 +4479,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 +4498,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 +5237,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 +5258,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 +5623,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 +5664,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 +5811,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 +6092,7 @@ const PHASE_ORDER = [
 	"public",
 	"not-found",
 	"locale-redirects",
+	"cache-headers",
 	"root-index"
 ];
 /**
@@ -5919,7 +6187,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 +6228,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");
 	});
@@ -10634,16 +10903,19 @@ function currentLocationUrl() {
 /**
 * Apply the matched route's `head` config to the live document (minimal client
 * head-sync for the DATA path: title only — the full meta sync runs on the
-* HTML-over-fetch path from the fetched `<head>`).
+* HTML-over-fetch path from the fetched `<head>`). The title is resolved through
+* `head.composeTitle` — the SAME composition `render` uses (`titleTemplate` applied;
+* a route-pinned `title` element wins) — so a client-side navigation's
+* `document.title` matches the SSG output instead of the raw route title.
 *
+* @param head - The head plugin API (resolves the final templated title).
 * @param route - The matched route definition.
 * @param routeContext - The render context (params/data/locale).
 * @example
-* syncDataHead(hit.route, { params, data, locale });
+* syncDataHead(deps.head, hit.route, { params, data, locale });
 */
-function syncDataHead(route, routeContext) {
-	const title = route._handlers.head?.(routeContext)?.title;
-	if (title !== void 0 && title !== "") document.title = title;
+function syncDataHead(head, route, routeContext) {
+	document.title = head.composeTitle(route._handlers.head?.(routeContext));
 }
 /**
 * Builds the single shared SPA kernel — a pure factory over state/config/emit.
@@ -10799,7 +11071,7 @@ function createSpaKernel(state, config, emit, deps) {
 		handleStart(pathname);
 		const { renderVNode } = await Promise.resolve().then(() => require("./render-DLZEOe4M.cjs"));
 		if (signal?.aborted) return;
-		syncDataHead(route, routeContext);
+		syncDataHead(deps.head, route, routeContext);
 		unmountPageSpecific(state, emit);
 		/**
 		* Render the VNode into the region and re-mount its islands in one paint — the