@nifrajs/web 4.0.2 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web",
-  "version": "4.0.2",
+  "version": "5.1.0",
   "description": "Framework-agnostic SSR core for nifra - the render seam + HTML document orchestration.",
   "keywords": [
     "bun",
@@ -42,6 +42,11 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
+    "./seo": {
+      "bun": "./src/seo.ts",
+      "types": "./dist/seo.d.ts",
+      "default": "./dist/seo.js"
+    },
     "./vitals": {
       "bun": "./src/vitals.ts",
       "types": "./dist/vitals.d.ts",
@@ -227,6 +232,76 @@
       "bun": "./src/internal/matches-runtime.ts",
       "types": "./dist/internal/matches-runtime.d.ts",
       "default": "./dist/internal/matches-runtime.js"
+    },
+    "./server-components": {
+      "bun": "./src/server-components.ts",
+      "types": "./dist/server-components.d.ts",
+      "default": "./dist/server-components.js"
+    },
+    "./server-components/client": {
+      "bun": "./src/server-components/client.ts",
+      "types": "./dist/server-components/client.d.ts",
+      "default": "./dist/server-components/client.js"
+    },
+    "./server-components/vite": {
+      "bun": "./src/server-components/vite.ts",
+      "types": "./dist/server-components/vite.d.ts",
+      "default": "./dist/server-components/vite.js"
+    },
+    "./server-components/build": {
+      "bun": "./src/server-components/build.ts",
+      "types": "./dist/server-components/build.d.ts",
+      "default": "./dist/server-components/build.js"
+    },
+    "./server-components/source": {
+      "bun": "./src/server-components/source.ts",
+      "types": "./dist/server-components/source.d.ts",
+      "default": "./dist/server-components/source.js"
+    },
+    "./server-components/props": {
+      "bun": "./src/server-components/props.ts",
+      "types": "./dist/server-components/props.d.ts",
+      "default": "./dist/server-components/props.js"
+    },
+    "./server-components/stream": {
+      "bun": "./src/server-components/stream.ts",
+      "types": "./dist/server-components/stream.d.ts",
+      "default": "./dist/server-components/stream.js"
+    },
+    "./server-components/state": {
+      "bun": "./src/server-components/state.ts",
+      "types": "./dist/server-components/state.d.ts",
+      "default": "./dist/server-components/state.js"
+    },
+    "./server-components/native": {
+      "bun": "./src/server-components/native.ts",
+      "types": "./dist/server-components/native.d.ts",
+      "default": "./dist/server-components/native.js"
+    },
+    "./server-components/islands": {
+      "bun": "./src/server-components/islands.ts",
+      "types": "./dist/server-components/islands.d.ts",
+      "default": "./dist/server-components/islands.js"
+    },
+    "./server-components/range": {
+      "bun": "./src/server-components/range.ts",
+      "types": "./dist/server-components/range.d.ts",
+      "default": "./dist/server-components/range.js"
+    },
+    "./server-components/build-info": {
+      "bun": "./src/server-components/build-info.ts",
+      "types": "./dist/server-components/build-info.d.ts",
+      "default": "./dist/server-components/build-info.js"
+    },
+    "./server-components/portal": {
+      "bun": "./src/server-components/portal.ts",
+      "types": "./dist/server-components/portal.d.ts",
+      "default": "./dist/server-components/portal.js"
+    },
+    "./server-components/trusted-html": {
+      "bun": "./src/server-components/trusted-html.ts",
+      "types": "./dist/server-components/trusted-html.d.ts",
+      "default": "./dist/server-components/trusted-html.js"
     }
   },
   "files": [
@@ -244,8 +319,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "4.0.2",
-    "@nifrajs/island-trigger": "4.0.2"
+    "@nifrajs/core": "5.1.0",
+    "@nifrajs/island-trigger": "5.1.0",
+    "parse5": "8.0.1"
   },
   "peerDependencies": {
     "@babel/core": "^7.26.0",
@@ -255,7 +331,9 @@
     "@stylexjs/babel-plugin": "^0.19.0",
     "sass": "^1.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
-    "web-vitals": "^6.0.0"
+    "web-vitals": "^6.0.0",
+    "typescript": "^5.9.0 || ^6.0.0",
+    "@vitejs/plugin-rsc": "0.5.35"
   },
   "peerDependenciesMeta": {
     "@babel/core": {
@@ -281,6 +359,12 @@
     },
     "web-vitals": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "@vitejs/plugin-rsc": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -292,10 +376,24 @@
     "@nifrajs/schema": "workspace:*",
     "@nifrajs/test-utils": "workspace:*",
     "@nifrajs/web-react": "workspace:*",
+    "@preact/preset-vite": "2.10.5",
     "@stylexjs/babel-plugin": "^0.19.0",
     "@stylexjs/stylex": "^0.19.0",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "@types/react": "19.2.17",
+    "@vitejs/plugin-rsc": "0.5.35",
+    "@vitejs/plugin-vue": "6.0.9",
+    "playwright": "1.63.0",
+    "preact": "10.29.8",
+    "preact-render-to-string": "6.7.0",
     "sass": "^1.77.0",
+    "solid-js": "1.9.14",
+    "svelte": "5.56.8",
+    "svelte-check": "4.7.6",
     "vite": "^8.2.1",
+    "vite-plugin-solid": "2.11.14",
+    "vue": "3.5.40",
+    "vue-tsc": "3.3.12",
     "web-vitals": "^6.2.2"
   },
   "repository": {

package/src/build-vite.ts

@@ -17,8 +17,10 @@
  * error the Bun build raises. A second production pipeline without those guards is exactly the hole the
  * bundler-neutral module graph was built to close.
  */
+
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join, relative, resolve as resolvePath } from "node:path"
+import { singleCopyPackageNames } from "@nifrajs/core/single-copy"
 import {
   type BuildClientOptions,
   type BuildTargetOptions,
@@ -72,6 +74,7 @@ type ViteBuildManifest = Readonly<Record<string, ViteManifestEntry>>
 
 interface ViteModule {
   build(config: Record<string, unknown>): Promise<unknown>
+  loadEnv(mode: string, envDir: string, prefixes: string): Record<string, string>
 }
 
 /** Load the app's Vite. Resolved from `root` so it's the project's copy, not this package's. */
@@ -181,6 +184,8 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
       ...(routeManifest.notFound ? [routeManifest.notFound.file] : []),
       // A nested `_404` is an entry only for its stylesheet: it renders on the server, unhydrated.
       ...Object.values(routeManifest.notFounds ?? {}).map((page) => page.file),
+      // A `_loading` page is an entry for its stylesheet too: the bootstrap imports it lazily.
+      ...Object.values(routeManifest.loadings ?? {}).map((page) => page.file),
     ]),
   ].sort()
 
@@ -220,7 +225,11 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     generatedFiles: [entryFile],
     verified,
     ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
-    secrets: { env: buildEnv, ...(exemptions ? { exemptions } : {}) },
+    // Vite reads `.env.<mode>` files too; a value only there is still the app's secret to keep.
+    secrets: {
+      env: { ...vite.loadEnv(mode, root, ""), ...buildEnv },
+      ...(exemptions ? { exemptions } : {}),
+    },
   }
   // nifra copies `public/` after the build; the main guard scans it with the bundle.
   const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
@@ -251,7 +260,7 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
           // Same framework coverage as the Bun build's dedupe plugins, from the one policy table: one
           // physical copy of react/react-dom, preact, and svelte, or a hook-using route gets a second
           // dispatcher/options global. No-op per framework the app does not use.
-          dedupe: [...viteDedupePackages()],
+          dedupe: [...viteDedupePackages(), ...singleCopyPackageNames(root)],
           ...(options.conditions ? { conditions: [...options.conditions] } : {}),
         },
         css: {
@@ -352,14 +361,22 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     routes._404 = c !== undefined ? [c] : []
   }
 
-  // CSS per route - Vite's manifest `css` is the transitive stylesheet set for that entry.
+  // CSS per route. A manifest entry's `css` lists only that chunk's own stylesheets, so a page also
+  // needs those of every chunk it imports statically (a component two routes share gets a chunk of
+  // its own) and the bootstrap's, which every page loads (a stylesheet the client module imports).
+  // The bootstrap's come first: the whole-app stylesheet before any route-scoped one.
   const stylesFor = (files: readonly string[]): readonly string[] => {
     const urls = new Set<string>()
-    for (const file of files) {
-      const key = fileKey.get(file)
-      const entry = key !== undefined ? viteManifest[key] : undefined
+    const seen = new Set<string>()
+    const visit = (key: string | undefined): void => {
+      if (key === undefined || seen.has(key)) return
+      seen.add(key)
+      const entry = viteManifest[key]
       for (const css of entry?.css ?? []) urls.add(url(css))
+      for (const imported of entry?.imports ?? []) visit(imported)
     }
+    visit(entryKey)
+    for (const file of files) visit(fileKey.get(file))
     return [...urls]
   }
   // CSS aggregate - every stylesheet the app emits, the always-safe fallback. With native Vite
@@ -376,8 +393,13 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
   // A single aggregate stylesheet is deliberately the route fallback. A per-route `[]` map would
   // suppress it in `createWebApp` and produce unstyled SSR on every route.
   if (css.length > 0 && cssCodeSplit) {
-    for (const route of routeManifest.routes) routeStyles[route.id] = stylesFor(chainFiles(route))
-    if (routeManifest.notFound) routeStyles._404 = stylesFor([routeManifest.notFound.file])
+    // A `_loading` page can show on a navigation from ANY page, and a document links only its own
+    // route's stylesheets - so every page that can start a navigation carries the loading pages' too.
+    const loadingFiles = Object.values(routeManifest.loadings ?? {}).map((page) => page.file)
+    for (const route of routeManifest.routes)
+      routeStyles[route.id] = stylesFor([...chainFiles(route), ...loadingFiles])
+    if (routeManifest.notFound)
+      routeStyles._404 = stylesFor([routeManifest.notFound.file, ...loadingFiles])
     for (const [id, page] of Object.entries(routeManifest.notFounds ?? {})) {
       routeStyles[id] = stylesFor([
         ...page.layoutIds.map((layoutId) => routeManifest.layouts[layoutId]?.file ?? ""),
@@ -574,7 +596,7 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
           "globalThis.__NIFRA_EDGE_RUNTIME__": edge ? "true" : "false",
         },
         resolve: {
-          dedupe: ["react", "react-dom"],
+          dedupe: ["react", "react-dom", ...singleCopyPackageNames(root)],
           conditions: [...conditions],
         },
         plugins: [...(options.vitePlugins ?? [])],

package/src/build.ts

@@ -1,3 +1,7 @@
+import { publicEnvDefines } from "./internal/public-env.ts"
+
+export { publicEnvDefines } from "./internal/public-env.ts"
+
 /**
  * `@nifrajs/web/build` - the production build (Bun-only, build-time). `buildClient` codegens + bundles
  * the client entry (content-hashed, code-split); `buildServer` codegens the static-import server
@@ -9,6 +13,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { cp, lstat, mkdir, realpath } from "node:fs/promises"
 import {
   dirname,
+  isAbsolute,
   join,
   basename as pathBasename,
   posix,
@@ -25,6 +30,7 @@ import {
   aggregateSizeReport,
   type BuildManifest,
   type BuildTarget,
+  type BuildTargetPlan,
   type Bundler,
   type ChunkSize,
   detectNodeBuiltinsInClient,
@@ -44,6 +50,8 @@ import { sanitizeOutputNames } from "./chunk-names.ts"
 import { type CssLoadingMode, normalizeCssCodeSplit, normalizeCssLoading } from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
+import { assertDisposableDir } from "./internal/disposable-dir.ts"
+import { entryChunks } from "./internal/entry-chunks.ts"
 import { dedupePolicyFor } from "./internal/identity-policy.ts"
 import {
   assertDevelopmentProductionParity,
@@ -106,7 +114,14 @@ const entryName = (file: string): string => {
  * `fromBunMetafile`; this smaller view is only for the per-route stylesheet map. */
 interface BunMetafile {
   readonly outputs?: Readonly<
-    Record<string, { readonly entryPoint?: string; readonly cssBundle?: string }>
+    Record<
+      string,
+      {
+        readonly entryPoint?: string
+        readonly cssBundle?: string
+        readonly inputs?: Readonly<Record<string, unknown>>
+      }
+    >
   >
 }
 
@@ -180,20 +195,6 @@ export interface BuildClientOptions {
  * define resolves it to `undefined` in the client bundle. An empty `prefix` exposes nothing (the
  * opt-out). Pure + exported so the prefix/redaction contract is unit-testable without a real build.
  */
-export function publicEnvDefines(
-  prefix: string,
-  env: Readonly<Record<string, string | undefined>>,
-): Record<string, string> {
-  const defines: Record<string, string> = {}
-  if (prefix === "") return defines // opt-out: bake in nothing
-  for (const [name, value] of Object.entries(env)) {
-    // Skip `undefined` (a deleted/unset key can still enumerate) so we never bake in `"undefined"`.
-    if (name.startsWith(prefix) && value !== undefined) {
-      defines[`process.env.${name}`] = JSON.stringify(value)
-    }
-  }
-  return defines
-}
 
 /**
  * Cloudflare Pages rejects a `_routes.json` with more than 100 include+exclude rules combined, or any
@@ -629,21 +630,27 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   const renamed = sanitizeOutputNames(outputs)
   const toUrl = (path: string): string =>
     `${publicPath}${renamed.get(basename(path)) ?? basename(path)}`
-  // Entry-point outputs come back in entrypoint order: [bootstrap, ...routeFiles]. Map each route file
-  // to its chunk URL by that order (guarded against drift), then a route's chunks = its layout chain +
-  // own file.
+  // Each entry's chunk is the output the metafile names that entry's source for. The position among the
+  // entry-point outputs ([bootstrap, ...routeFiles]) is only the fallback, for an entry the metafile
+  // does not name by path (a `resolve` that returns a bare specifier). A route's chunks = its layout
+  // chain + own file.
   const entryPoints = outputs.filter((o) => o.kind === "entry-point")
-  const bootstrap = entryPoints[0]
-  if (bootstrap === undefined) throw new Error("[nifra/web] build produced no entry-point output")
   if (entryPoints.length !== routeFiles.length + 1) {
     throw new Error(
       `[nifra/web] expected ${routeFiles.length + 1} entry-point outputs (bootstrap + ${routeFiles.length} routes), got ${entryPoints.length}`,
     )
   }
+  const bySource = entryChunks(clientMeta?.outputs ?? {}, cwd)
+  const chunkOf = (source: string, position: number): string | undefined => {
+    const path = bySource.get(resolvePath(source)) ?? entryPoints[position]?.path
+    return path === undefined ? undefined : toUrl(path)
+  }
+  const entryUrl = chunkOf(entryFile, 0)
+  if (entryUrl === undefined) throw new Error("[nifra/web] build produced no entry-point output")
   const fileToChunk = new Map<string, string>()
   routeFiles.forEach((file, i) => {
-    const out = entryPoints[i + 1] // in range - length checked above
-    if (out !== undefined) fileToChunk.set(file, toUrl(out.path))
+    const url = chunkOf(resolve(file), i + 1)
+    if (url !== undefined) fileToChunk.set(file, url)
   })
   const chunksFor = (chainFiles: readonly string[]): string[] =>
     chainFiles.map((f) => fileToChunk.get(f)).filter((u): u is string => u !== undefined)
@@ -684,15 +691,30 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // links only its layout chain + own CSS (deduped); an empty array means the page needs no CSS at all.
   // Absent (→ aggregate fallback) only if Bun emits no metafile/cssBundle - never silently incomplete.
   const cssByEntry = new Map<string, string>()
+  const bootstrapEntry = resolvePath(entryFile)
+  let bootstrapSources: readonly string[] = []
+  const routeSources = new Set<string>()
   for (const out of Object.values(clientMeta?.outputs ?? {})) {
     if (out.entryPoint !== undefined && out.cssBundle !== undefined) {
-      cssByEntry.set(resolvePath(cwd, out.entryPoint), toUrl(out.cssBundle))
+      const entry = resolvePath(cwd, out.entryPoint)
+      cssByEntry.set(entry, toUrl(out.cssBundle))
+      const sources = Object.keys(clientMeta?.outputs?.[out.cssBundle]?.inputs ?? {})
+      if (entry === bootstrapEntry) bootstrapSources = sources
+      else for (const source of sources) routeSources.add(source)
     }
   }
+  // A stylesheet the client module imports is bundled only into the bootstrap's CSS, which also holds
+  // every route's (the bootstrap imports each route lazily). When it carries CSS no route entry owns,
+  // every page links that bundle first, the whole-app stylesheet before any route-scoped one, as a
+  // Vite page links the bootstrap's; otherwise the page renders without it.
+  const leadingCss = bootstrapSources.some((source) => !routeSources.has(source))
+    ? cssByEntry.get(bootstrapEntry)
+    : undefined
   const stylesFor = (chainFiles: readonly string[]): readonly string[] => {
     const urls = chainFiles
       .map((f) => (f ? cssByEntry.get(resolvePath(resolve(f))) : undefined))
       .filter((u): u is string => u !== undefined)
+    if (leadingCss !== undefined) urls.unshift(leadingCss)
     return [...new Set(urls)]
   }
   const routeStyles: Record<string, readonly string[]> = {}
@@ -700,7 +722,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // route entry (StyleX's atomic CSS is one example). In that shape there is no useful per-route map:
   // emitting `routeId: []` would suppress the aggregate `styles` fallback in `createWebApp` and render
   // SSR pages unstyled. Keep routeStyles absent until at least one authored route entry owns CSS.
-  const routeCssEntries = [...cssByEntry.keys()].filter((entry) => entry !== resolvePath(entryFile))
+  const routeCssEntries = [...cssByEntry.keys()].filter((entry) => entry !== bootstrapEntry)
   if (css.length > 0 && routeCssEntries.length > 0) {
     // A `_loading` page can show on a navigation from ANY page, and a document links only its own
     // route's stylesheets - so every page that can start a navigation carries the loading pages' too.
@@ -729,7 +751,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
 
   const manifest: BuildManifest = {
-    entry: toUrl(bootstrap.path),
+    entry: entryUrl,
     assets: outputs.map((o) => toUrl(o.path)),
     routes,
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
@@ -1009,11 +1031,22 @@ function withEmittedImports(
   return { ...graph, chunks }
 }
 
-/** Refusals the bundler stopped on before it produced a graph, so without import chains. */
+/**
+ * Refusals the bundler stopped on before it produced a graph, so without import chains. Files sharing
+ * one reason share one line: with no chain to tell them apart, 50 lines would say one thing 50 times.
+ */
 function formatRefusedFiles(refused: ReadonlyMap<string, string>, root: string): string {
-  const lines = [...refused].map(([file, reason]) => {
+  const byReason = new Map<string, string[]>()
+  for (const [file, reason] of refused) {
     const rel = relative(root, file).replaceAll("\\", "/")
-    return `  - ${rel.startsWith("..") ? file : rel}: ${reason}`
+    const shown = rel.startsWith("..") ? file : rel
+    const files = byReason.get(reason)
+    if (files === undefined) byReason.set(reason, [shown])
+    else files.push(shown)
+  }
+  const lines = [...byReason].map(([reason, files]) => {
+    const more = files.length > 5 ? ` and ${files.length - 5} more` : ""
+    return `  - ${files.slice(0, 5).join(", ")}${more}: ${reason}`
   })
   return `[nifra/web] the browser build reached code that may not ship to a browser:\n${lines.join("\n")}`
 }
@@ -1247,6 +1280,9 @@ export function generateServerEntry(options: {
   readonly title?: string
   /** Encoded root-relative public file paths copied into the deploy directory. */
   readonly publicFiles?: readonly string[]
+  /** URL paths of the content-hashed client outputs (the build manifest's `assets`). When given, a
+   * self-hosted entry caches only these immutably; otherwise every file under `/assets/` is. */
+  readonly hashedFiles?: readonly string[]
   /** Trust the edge platform's client-address header for `c.clientIp`. See {@link ServerEntryClientIp}. */
   readonly clientIp?: ServerEntryClientIp
 }): string {
@@ -1258,6 +1294,7 @@ export function generateServerEntry(options: {
     optionImports = {},
     title = "nifra",
     publicFiles = [],
+    hashedFiles,
     clientIp,
   } = options
   if (clientIp !== undefined && clientIp !== "platform") {
@@ -1355,6 +1392,9 @@ export function generateServerEntry(options: {
     "// The client bundle and public files live next to this entry; serve only manifest-approved paths.",
     'const STATIC_ROOT = new URL("./", import.meta.url)',
     `const PUBLIC_FILES = new Set(${JSON.stringify(publicFiles)})`,
+    ...(hashedFiles !== undefined
+      ? [`const HASHED_FILES = new Set(${JSON.stringify(hashedFiles)})`]
+      : []),
     "const staticPath = (pathname: string): string | undefined => {",
     "  if (PUBLIC_FILES.has(pathname)) return '.' + pathname",
     '  if (!pathname.startsWith("/assets/")) return undefined',
@@ -1371,7 +1411,7 @@ export function generateServerEntry(options: {
     `const TYPES: Record<string, string> = ${JSON.stringify(CONTENT_TYPES)}`,
     "const staticHeaders = (pathname: string): Record<string, string> => ({",
     '  "content-type": TYPES[pathname.slice(pathname.lastIndexOf(".")).toLowerCase()] ?? "application/octet-stream",',
-    `  "cache-control": pathname.startsWith("/assets/") ? ${JSON.stringify(IMMUTABLE)} : ${JSON.stringify(ONE_DAY)},`,
+    `  "cache-control": ${hashedFiles !== undefined ? "HASHED_FILES.has(pathname)" : 'pathname.startsWith("/assets/")'} ? ${JSON.stringify(IMMUTABLE)} : ${JSON.stringify(ONE_DAY)},`,
     '  "x-content-type-options": "nosniff",',
     "})",
   )
@@ -1467,10 +1507,12 @@ async function measureOutputs(paths: readonly string[]): Promise<ChunkSize[]> {
 export interface BuildTargetOptions {
   /** The `routes/` directory to discover (absolute path). */
   readonly routesDir: string
-  /** Output directory for the assembled deploy dir (absolute path). Cleared and recreated. */
+  /** Output directory for the assembled deploy dir (absolute path). Cleared and recreated, so the
+   * build refuses one that is a filesystem root or is or contains the routes directory, the public
+   * directory, an absolute entry module, or the working directory. */
   readonly outDir: string
   /** A scratch directory for intermediate codegen (the generated server entry + manifest) and the
-   * server bundle, cleaned up after. Absolute path. */
+   * server bundle, cleaned up after. Absolute path. Checked the same way as `outDir`. */
   readonly workDir: string
   /** The adapter's client runtime module (exports `mountRouter`), e.g. `"@nifrajs/web-react/client"`. */
   readonly clientModule: string
@@ -1597,6 +1639,26 @@ export const bunBundler: Bundler = {
     }),
 }
 
+/** Refuse a public file that shares a path with a file the target writes into the same directory: the
+ * build overwrites it, and the server would then answer that public path with its own bundle. */
+function assertNoPublicCollision(
+  plan: BuildTargetPlan,
+  publicFiles: readonly string[],
+  outDir: string,
+): void {
+  if (plan.kind !== "server" || plan.staticDir !== "") return
+  const owned = [`/${plan.outputFile}`]
+  if (plan.target === "cloudflare") owned.push("/_routes.json")
+  // Compared case-insensitively: on a case-insensitive filesystem `Server.js` is the same file.
+  const clashes = publicFiles.filter((file) => owned.includes(file.toLowerCase()))
+  if (clashes.length > 0) {
+    throw new Error(
+      `[nifra/web] public file(s) ${clashes.join(", ")} would be overwritten by the ${plan.target} ` +
+        `build's own output in ${outDir}. Rename or move them out of the public directory.`,
+    )
+  }
+}
+
 /** Build a full deploy dir for `target` using the default Bun bundler. See {@link buildTargetWith}. */
 export async function buildTarget(
   target: BuildTarget,
@@ -1622,6 +1684,20 @@ export async function buildTargetWith(
   const requestedCssLoading =
     options.cssLoading === undefined ? undefined : normalizeCssLoading(options.cssLoading)
   const targetPlan = planBuildTarget(parseBuildTarget(target), outDir)
+  const sources = [
+    routesDir,
+    process.cwd(),
+    resolvePath(
+      typeof options.publicDir === "string"
+        ? options.publicDir
+        : join(dirname(routesDir), "public"),
+    ),
+    ...[options.adapterImport, options.backendImport, options.useImport].filter(
+      (file): file is string => file !== undefined && isAbsolute(file),
+    ),
+  ]
+  assertDisposableDir("outDir", outDir, sources)
+  assertDisposableDir("workDir", workDir, sources)
   const { rmSync } = await import("node:fs")
   rmSync(outDir, { recursive: true, force: true })
   rmSync(workDir, { recursive: true, force: true })
@@ -1672,6 +1748,7 @@ export async function buildTargetWith(
     publicDir !== undefined && existsSync(publicDir)
       ? await copyPublicDir(publicDir, staticRoot)
       : []
+  assertNoPublicCollision(targetPlan, publicFiles, outDir)
   if (publicFiles.length > 0) {
     client = { ...client, publicFiles }
   }
@@ -1734,6 +1811,7 @@ export async function buildTargetWith(
       ...(options.backendImport !== undefined ? { backendImport: options.backendImport } : {}),
       ...(options.title !== undefined ? { title: options.title } : {}),
       ...(publicFiles.length > 0 ? { publicFiles } : {}),
+      hashedFiles: client.assets,
       ...(options.clientIp !== undefined ? { clientIp: options.clientIp } : {}),
     }),
   )

package/src/cdn.ts

@@ -11,6 +11,7 @@
  * for any other. Backend-only: a browser build that reaches this module fails.
  */
 import "@nifrajs/web/backend-only"
+import { writableResponse } from "@nifrajs/core/server"
 import { isDraftEnabled } from "./draft.ts"
 import type { CdnProvider } from "./internal/cdn/core.ts"
 import { pathTag } from "./internal/cdn/core.ts"
@@ -84,15 +85,9 @@ const isHtml = (res: Response): boolean =>
   (res.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
 
 function withHeaders(res: Response, set: Readonly<Record<string, string>>): Response {
-  try {
-    for (const [name, value] of Object.entries(set)) res.headers.set(name, value)
-    return res
-  } catch {
-    // A `fetch()` response has immutable headers: rebuild it around the same body instead.
-    const headers = new Headers(res.headers)
-    for (const [name, value] of Object.entries(set)) headers.set(name, value)
-    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
-  }
+  const target = writableResponse(res)
+  for (const [name, value] of Object.entries(set)) target.headers.set(name, value)
+  return target
 }
 
 /**
@@ -150,6 +145,12 @@ export interface InvalidatorOptions {
   readonly key?: (path: string) => string | null
   /** The `query` policy given to `withISR`. Default `"bypass"`. Ignored with `key`. */
   readonly query?: ISRQuery
+  /**
+   * Caches below the pages whose entries carry the same tags, such as a `@nifrajs/cache` holding
+   * loader data. Tags reach each of them before the store, so a page regenerated mid-purge cannot be
+   * rebuilt from stale data; a failure rejects before the store is touched. Paths do not reach them.
+   */
+  readonly dataCaches?: readonly { invalidateTag(tag: string): unknown }[]
 }
 
 export interface InvalidateResult {
@@ -196,11 +197,16 @@ export function createInvalidator(options: InvalidatorOptions): {
           throw new TypeError("[nifra/web/cdn] invalidate paths must start with /")
         }
       }
+      if (store !== undefined && tags.length > 0 && store.invalidateTag === undefined) {
+        throw new TypeError("[nifra/web/cdn] this store cannot invalidate by tag")
+      }
+      if (tags.length > 0) {
+        for (const cache of options.dataCaches ?? []) {
+          for (const tag of tags) await cache.invalidateTag(tag)
+        }
+      }
       let origin: InvalidateResult["origin"] = "skipped"
       if (store !== undefined) {
-        if (tags.length > 0 && store.invalidateTag === undefined) {
-          throw new TypeError("[nifra/web/cdn] this store cannot invalidate by tag")
-        }
         for (const path of paths) {
           const key = keyOf?.(path)
           if (key !== null && key !== undefined) await store.delete(key)