@nifrajs/web 5.3.0 → 5.5.0

package/src/dev.ts

@@ -65,6 +65,7 @@ import {
   isLoopbackHost,
 } from "./dev-session.ts"
 import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
+import { formatBuildLog } from "./diagnostic.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
 import { DEV_ENTRY_FILE } from "./internal/dev-reserved.ts"
@@ -634,11 +635,6 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
  * Overlapping runs are collapsed - a save during a bundle queues exactly one re-run, so a burst of edits
  * cannot pile up builds behind each other.
  */
-/**
- * Format a client-build rejection for the guard's report. Bun.build rejects with an AggregateError
- * whose message is just "Bundle failed" - the actionable part (which file, which import) lives in
- * `.errors`. Surface it, or the guard reports a failure while hiding the reason.
- */
 /** A Host header's name: lowercased, without its port or IPv6 brackets. */
 function hostName(host: string): string {
   const name = host.trim().toLowerCase()
@@ -648,9 +644,14 @@ function hostName(host: string): string {
   return colon === -1 ? name : name.slice(0, colon)
 }
 
+/**
+ * Format a client-build rejection for the guard's report. Bun.build rejects with an AggregateError
+ * whose message is just "Bundle failed" - the actionable part (which file, which import) lives in
+ * `.errors`. Surface it, or the guard reports a failure while hiding the reason.
+ */
 export function buildFailureDetail(err: unknown): string {
   return err instanceof AggregateError && err.errors.length > 0
-    ? err.errors.map((e) => `  ${e instanceof Error ? e.message : String(e)}`).join("\n")
+    ? err.errors.map((e) => `  ${formatBuildLog(e).replaceAll("\n", "\n  ")}`).join("\n")
     : `  ${err instanceof Error ? err.message : String(err)}`
 }
 

package/src/diagnostic.ts

@@ -34,6 +34,49 @@ export {
 /** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */
 export const LAST_ERROR_PATH = "/__nifra/last-error"
 
+/** `file` relative to `root` when it sits inside it (the bundler reports real paths, so a symlinked
+ * root is compared by its real path too), else `file` as given. */
+function pathUnder(root: string, file: string): string {
+  const inside = (base: string): string | undefined => {
+    const rel = relative(base, file).replaceAll("\\", "/")
+    return rel === ".." || rel.startsWith("../") || isAbsolute(rel) ? undefined : rel
+  }
+  let real: string | undefined
+  try {
+    real = realpathSync(root)
+  } catch {
+    real = undefined
+  }
+  return inside(root) ?? (real === undefined ? undefined : inside(real)) ?? file
+}
+
+/**
+ * One bundler log as `file:line:column: message`, the source line it points at underneath. Bun's
+ * `BuildMessage`/`ResolveMessage` carry the place in `position`, which their `String()` drops: a
+ * failed build said "Could not resolve: ./db" without naming the module that imported it.
+ */
+export function formatBuildLog(log: unknown, root: string = process.cwd()): string {
+  const message =
+    typeof log === "object" && log !== null && "message" in log && typeof log.message === "string"
+      ? log.message
+      : String(log)
+  const position =
+    typeof log === "object" && log !== null && "position" in log ? log.position : undefined
+  if (typeof position !== "object" || position === null || !("file" in position)) return message
+  const file = typeof position.file === "string" ? position.file : ""
+  if (file === "") return message
+  const where = [
+    pathUnder(root, file),
+    "line" in position && typeof position.line === "number" ? position.line : undefined,
+    "column" in position && typeof position.column === "number" ? position.column : undefined,
+  ]
+    .filter((part) => part !== undefined)
+    .join(":")
+  const text =
+    "lineText" in position && typeof position.lineText === "string" ? position.lineText.trim() : ""
+  return text === "" ? `${where}: ${message}` : `${where}: ${message}\n    ${text}`
+}
+
 /** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */
 export interface DiagnosticFrame {
   readonly raw: string

package/src/host-policy.ts

@@ -0,0 +1,219 @@
+/**
+ * Host-scoped surfaces: which pages and files each host may serve.
+ *
+ * An app that answers on more than one host often must not show all of itself on each: a domain
+ * someone else points at the app should not render its sign-in page under that domain's certificate.
+ * A gate that knows only page paths gets the files wrong instead, because a page is not just its path:
+ * its document pulls the client bundle, its stylesheets and whatever `public/` files it links, and a
+ * gate that refuses those serves the page unstyled and never hydrates it. So a rule names its pages by
+ * route pattern and takes the build's own files by token: `buildAssets` is the exact set the build
+ * emitted (`buildAssets` from the generated server manifest), never a guess at its naming scheme.
+ *
+ * Pure and runtime-free, so the same policy can refuse a soft navigation in the browser.
+ */
+import { Router as CoreRouter } from "@nifrajs/core/router"
+import type { Middleware, NodeRequestContext } from "@nifrajs/core/server"
+import { requestPattern } from "./internal/route-path.ts"
+
+/** The files a build emitted, by request path: the generated server manifest's `buildAssets`. */
+export interface BuildAssetSet {
+  has(pathname: string): boolean
+}
+
+/** One host's surface. A request on a host no rule names is not restricted. */
+export interface HostPolicyRule {
+  /**
+   * The hosts this rule restricts: names compared without case, port or trailing dot, or a predicate
+   * given that lowercase name (`(host) => !ownHosts.has(host)` for "every host that is not ours").
+   */
+  readonly hosts: readonly string[] | ((hostname: string) => boolean)
+  /** Page routes these hosts render, as route patterns (`/`, `/p/:id`, `/share/*`). */
+  readonly pages: readonly string[]
+  /**
+   * Serve the build's own files on these hosts (default `true`): the client bundle and the files the
+   * build copied from `public/`, exactly as the build emitted them.
+   */
+  readonly buildAssets?: boolean
+  /** Other paths these hosts serve, as route patterns: an API the pages call, a server function. */
+  readonly paths?: readonly string[]
+}
+
+export interface HostPolicyOptions {
+  readonly rules: readonly HostPolicyRule[]
+  /**
+   * The answer to a path a rule refuses. Default: a bare `404` with `cache-control: no-store`, so a
+   * restricted host does not even confirm the refused page exists.
+   */
+  readonly refuse?: (refused: { readonly host: string; readonly pathname: string }) => Response
+}
+
+export interface HostPolicy {
+  readonly rules: readonly HostPolicyRule[]
+  /**
+   * Whether `pathname` (as requested, percent-encoded, without the query) may be served on `host` (a
+   * Host header value; its port and case are ignored). `buildAssets` is the build's file set; without
+   * it a rule's `buildAssets` matches nothing.
+   */
+  allows(host: string, pathname: string, buildAssets?: BuildAssetSet): boolean
+  /** The refusal for `pathname` on `host`, or `undefined` to serve it. */
+  refusal(host: string, pathname: string, buildAssets?: BuildAssetSet): Response | undefined
+  /** {@link HostPolicy.refusal} for a request: its Host header (else its URL's host) and path. */
+  check(request: Request, buildAssets?: BuildAssetSet): Response | undefined
+}
+
+const HOST_POLICY = Symbol.for("nifra.web.host-policy")
+
+interface CompiledRule {
+  readonly covers: (hostname: string) => boolean
+  readonly matches: (pathname: string) => boolean
+  readonly buildAssets: boolean
+}
+
+/** A Host header value's name: lowercase, without its port, IPv6 brackets or trailing dots. */
+export function hostnameOf(host: string): string {
+  const name = host.trim().toLowerCase()
+  if (name.startsWith("[")) {
+    const end = name.indexOf("]")
+    return end === -1 ? name.slice(1) : name.slice(1, end)
+  }
+  const colon = name.lastIndexOf(":")
+  const bare = colon === -1 || name.indexOf(":") !== colon ? name : name.slice(0, colon)
+  // `partner.example.` is the same host as `partner.example`; kept, it escapes the rule listing it.
+  let end = bare.length
+  while (end > 0 && bare.charCodeAt(end - 1) === 46 /* . */) end--
+  return end === bare.length ? bare : bare.slice(0, end)
+}
+
+function compilePatterns(
+  patterns: readonly string[],
+  label: string,
+): (pathname: string) => boolean {
+  const router = new CoreRouter<true>()
+  for (const pattern of patterns) {
+    if (typeof pattern !== "string" || !pattern.startsWith("/")) {
+      throw new TypeError(
+        `[nifra/web] hostPolicy: ${label} entries are route patterns starting with "/", got ${JSON.stringify(pattern)}`,
+      )
+    }
+    router.add("GET", requestPattern(pattern), true)
+  }
+  return (pathname) => router.find("GET", pathname).found
+}
+
+function compileRule(rule: HostPolicyRule, index: number): CompiledRule {
+  const label = `rules[${index}]`
+  if (typeof rule !== "object" || rule === null) {
+    throw new TypeError(`[nifra/web] hostPolicy: ${label} must be an object`)
+  }
+  let covers: (hostname: string) => boolean
+  if (typeof rule.hosts === "function") {
+    covers = rule.hosts
+  } else if (Array.isArray(rule.hosts) && rule.hosts.every((host) => typeof host === "string")) {
+    const names = new Set(rule.hosts.map(hostnameOf))
+    covers = (hostname) => names.has(hostname)
+  } else {
+    throw new TypeError(
+      `[nifra/web] hostPolicy: ${label}.hosts must be a list of host names or a predicate`,
+    )
+  }
+  if (!Array.isArray(rule.pages)) {
+    throw new TypeError(
+      `[nifra/web] hostPolicy: ${label}.pages must list the page routes the hosts serve`,
+    )
+  }
+  const pages = compilePatterns(rule.pages, `${label}.pages`)
+  const paths = rule.paths === undefined ? undefined : compilePatterns(rule.paths, `${label}.paths`)
+  return {
+    covers,
+    matches: paths === undefined ? pages : (pathname) => pages(pathname) || paths(pathname),
+    buildAssets: rule.buildAssets !== false,
+  }
+}
+
+const notFound = (): Response =>
+  new Response("Not Found", {
+    status: 404,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+  })
+
+/**
+ * Declare which pages and files each host serves. Hand the result to `createWebApp({ hostPolicy })`
+ * (or export it as `hostPolicy` from the framework module, which `nifra build`'s server entry reads):
+ * it is evaluated before the build's static files, the prerendered pages, the mounts and every page.
+ * On Vercel the CDN answers the build's files before the function runs, so there it covers the rest.
+ * A hand-written entry calls `check(request, buildAssets)` first, before its own static handler.
+ *
+ * ```ts
+ * export const hostPolicy = createHostPolicy({
+ *   rules: [{
+ *     hosts: (host) => !OWN_HOSTS.has(host),
+ *     pages: ["/", "/p/:id", "/share/*"],
+ *     paths: ["/api/submissions/*"],
+ *   }],
+ * })
+ * ```
+ */
+export function createHostPolicy(options: HostPolicyOptions): HostPolicy {
+  if (typeof options !== "object" || options === null || !Array.isArray(options.rules)) {
+    throw new TypeError("[nifra/web] createHostPolicy takes { rules: [...] }")
+  }
+  const rules = options.rules.map(compileRule)
+  const refuse = options.refuse ?? notFound
+  const allows = (host: string, pathname: string, buildAssets?: BuildAssetSet): boolean => {
+    const hostname = hostnameOf(host)
+    const rule = rules.find((candidate) => candidate.covers(hostname))
+    if (rule === undefined) return true
+    if (rule.buildAssets && buildAssets?.has(pathname) === true) return true
+    return rule.matches(pathname)
+  }
+  const refusal = (host: string, pathname: string, buildAssets?: BuildAssetSet) =>
+    allows(host, pathname, buildAssets) ? undefined : refuse({ host: hostnameOf(host), pathname })
+  const policy: HostPolicy = {
+    rules: Object.freeze([...options.rules]),
+    allows,
+    refusal,
+    check(request, buildAssets) {
+      const url = new URL(request.url)
+      return refusal(request.headers.get("host") ?? url.host, url.pathname, buildAssets)
+    },
+  }
+  Object.defineProperty(policy, HOST_POLICY, { value: true })
+  return Object.freeze(policy)
+}
+
+/** Whether `value` came from {@link createHostPolicy}. */
+export function isHostPolicy(value: unknown): value is HostPolicy {
+  return typeof value === "object" && value !== null && HOST_POLICY in value
+}
+
+const BUN_NATIVE_REQUEST_SAFE = Symbol.for("@nifrajs/core/bun-native-request-safe")
+
+/** The path of a Node view's URL, `<protocol>://<host><target>`: the adapter has refused a host
+ * holding `/`, `?`, `#` or `@` and resolved the target's dot segments, so it starts at the first `/`
+ * after the scheme and ends where core's routing ends it. */
+const targetPath = (url: string): string => {
+  const start = url.indexOf("/", url.indexOf("://") + 3)
+  if (start === -1) return ""
+  let end = url.length
+  for (let i = start; i < end; i++) {
+    const c = url.charCodeAt(i)
+    if (c === 63 /* ? */ || c === 35 /* # */) end = i
+  }
+  return url.slice(start, end)
+}
+
+/** A host policy as request middleware, for `createWebApp`: header-only, so its Node twin keeps the
+ * direct lane. */
+export function hostPolicyGate(
+  policy: HostPolicy,
+  buildAssets: BuildAssetSet | undefined,
+): Middleware {
+  const gate: Middleware = {
+    name: "nifra-host-policy",
+    onRequest: (request) => policy.check(request, buildAssets),
+    onNodeRequest: (request: NodeRequestContext) =>
+      policy.refusal(request.header("host") ?? "", targetPath(request.url), buildAssets),
+  }
+  Object.defineProperty(gate, BUN_NATIVE_REQUEST_SAFE, { value: true })
+  return gate
+}

package/src/host-reach.ts

@@ -0,0 +1,177 @@
+/**
+ * Whether a host can load what its pages reference: the check that catches a host policy (or any
+ * gate in front of the static files) that serves a page but refuses its stylesheet or bundle. Such a
+ * page still answers 200, so a status check passes while the browser renders it unstyled and never
+ * hydrates it.
+ *
+ * Bun-only (HTMLRewriter, Bun.Transpiler), like the rest of `@nifrajs/web/build`.
+ */
+
+/** One request the check made. */
+export interface HostReachResult {
+  /** The request path, as sent. */
+  readonly path: string
+  /** `page` for a page the check was given, `asset` for a file a page or another file references. */
+  readonly kind: "page" | "asset" | "refused"
+  readonly status: number
+  /** What referenced it: the page or file path. Absent for a page. */
+  readonly from?: string
+}
+
+export interface HostReachReport {
+  readonly host: string
+  readonly ok: boolean
+  readonly results: readonly HostReachResult[]
+  /** The results that broke the expectation: a page or asset not answered 200, a refused path answered. */
+  readonly failures: readonly HostReachResult[]
+  /** `limit` stopped the walk with declared pages or references left unfetched; `ok` is then `false`. */
+  readonly truncated: boolean
+}
+
+export interface HostReachOptions {
+  /** Sends one GET. Given the path and the Host header to send. */
+  readonly fetch: (path: string, host: string) => Promise<Response>
+  /** The host to address (the Host header every request carries). */
+  readonly host: string
+  /** Page paths that must render on `host` (concrete paths, not patterns). */
+  readonly pages: readonly string[]
+  /** Paths `host` must refuse with `refusedStatus`. */
+  readonly refused?: readonly string[]
+  /** The status a refused path answers (default `404`). */
+  readonly refusedStatus?: number
+  /** At most this many files are fetched, pages included (default 500). */
+  readonly limit?: number
+}
+
+// The attributes that make a browser fetch a file before or while a page renders.
+const LINK_RELS = new Set([
+  "stylesheet",
+  "modulepreload",
+  "preload",
+  "icon",
+  "apple-touch-icon",
+  "manifest",
+  "mask-icon",
+])
+
+/** The URLs a document asks the browser to load: scripts, stylesheets, preloads, icons, images. */
+async function documentReferences(html: string): Promise<string[]> {
+  const found: string[] = []
+  const rewriter = new HTMLRewriter()
+    .on("script[src]", {
+      element: (el) => void found.push(el.getAttribute("src") ?? ""),
+    })
+    .on("link[href]", {
+      element: (el) => {
+        const rels = (el.getAttribute("rel") ?? "").toLowerCase().split(/\s+/)
+        if (rels.some((rel) => LINK_RELS.has(rel))) found.push(el.getAttribute("href") ?? "")
+      },
+    })
+    .on("img[src], source[src], video[poster]", {
+      element: (el) => void found.push(el.getAttribute("src") ?? el.getAttribute("poster") ?? ""),
+    })
+  await rewriter.transform(new Response(html)).text()
+  return found.filter((url) => url !== "")
+}
+
+/** `url(...)` references in a stylesheet, found by scanning rather than a regex over untrusted text. */
+function cssReferences(css: string): string[] {
+  const found: string[] = []
+  let at = css.indexOf("url(")
+  while (at !== -1) {
+    const close = css.indexOf(")", at)
+    if (close === -1) break
+    const raw = css
+      .slice(at + 4, close)
+      .trim()
+      .replace(/^["']|["']$/g, "")
+    if (raw !== "" && !raw.startsWith("data:")) found.push(raw)
+    at = css.indexOf("url(", close)
+  }
+  return found
+}
+
+const scanner = new Bun.Transpiler({ loader: "js" })
+
+/** A script's static and dynamic import specifiers that name files (not bare packages). */
+function scriptReferences(code: string): string[] {
+  try {
+    return scanner
+      .scanImports(code)
+      .map((entry) => entry.path)
+      .filter((path) => path.startsWith("/") || path.startsWith("./") || path.startsWith("../"))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Render each page on `host`, then fetch every same-origin file each page references, following
+ * scripts' imports and stylesheets' `url()`s, and expect 200 for all of them; then expect each
+ * `refused` path to answer `refusedStatus`. Cross-origin references are skipped: they are not this
+ * app's to serve.
+ */
+export async function checkHostReach(options: HostReachOptions): Promise<HostReachReport> {
+  const { host, fetch } = options
+  const limit = options.limit ?? 500
+  const refusedStatus = options.refusedStatus ?? 404
+  const origin = `http://${host}`
+  const results: HostReachResult[] = []
+  const seen = new Set<string>()
+  const queue: { path: string; from: string }[] = []
+  const enqueue = (reference: string, base: string): void => {
+    let url: URL
+    try {
+      url = new URL(reference, origin + base)
+    } catch {
+      return
+    }
+    if (url.origin !== origin) return
+    const path = url.pathname
+    if (seen.has(path)) return
+    seen.add(path)
+    queue.push({ path, from: base })
+  }
+
+  let pagesTruncated = false
+  for (const page of options.pages) {
+    if (results.length >= limit) {
+      pagesTruncated = true
+      break
+    }
+    seen.add(page)
+    const response = await fetch(page, host)
+    const text = await response.text()
+    results.push({ path: page, kind: "page", status: response.status })
+    if (response.status !== 200) continue
+    for (const reference of await documentReferences(text)) enqueue(reference, page)
+  }
+  while (results.length < limit) {
+    const next = queue.shift()
+    if (next === undefined) break
+    const response = await fetch(next.path, host)
+    results.push({ path: next.path, kind: "asset", status: response.status, from: next.from })
+    if (response.status !== 200) {
+      await response.body?.cancel()
+      continue
+    }
+    const type = response.headers.get("content-type") ?? ""
+    if (!type.includes("css") && !type.includes("javascript")) {
+      await response.body?.cancel()
+      continue
+    }
+    const body = await response.text()
+    const references = type.includes("css") ? cssReferences(body) : scriptReferences(body)
+    for (const reference of references) enqueue(reference, next.path)
+  }
+  for (const path of options.refused ?? []) {
+    const response = await fetch(path, host)
+    await response.body?.cancel()
+    results.push({ path, kind: "refused", status: response.status })
+  }
+  const failures = results.filter((result) =>
+    result.kind === "refused" ? result.status !== refusedStatus : result.status !== 200,
+  )
+  const truncated = pagesTruncated || queue.length > 0
+  return { host, ok: failures.length === 0 && !truncated, results, failures, truncated }
+}

package/src/index.ts

@@ -76,6 +76,16 @@ export {
   fontFace,
   fontPreload,
 } from "./fonts.ts"
+// Generated client entries intentionally import the browser router from the client subpath:
+// `import { createClientRouter, createMatcher, mergeHeads, resolveChainMeta } from "@nifrajs/web/client"`.
+export {
+  type BuildAssetSet,
+  createHostPolicy,
+  type HostPolicy,
+  type HostPolicyOptions,
+  type HostPolicyRule,
+  isHostPolicy,
+} from "./host-policy.ts"
 export {
   type GenerateClientEntryOptions,
   type GenerateRouteSearchTypesOptions,
@@ -84,8 +94,6 @@ export {
   generateRouteSearchTypes,
   generateServerManifest,
 } from "./internal/codegen.ts"
-// Generated client entries intentionally import the browser router from the client subpath:
-// `import { createClientRouter, createMatcher, mergeHeads, resolveChainMeta } from "@nifrajs/web/client"`.
 export { mergeHeads, resolveChainMeta, resolveMeta } from "./internal/head-merge.ts"
 export type { PrerenderedPages } from "./internal/prerendered-pages.ts"
 export {

package/src/internal/certified-components.ts

@@ -0,0 +1,7 @@
+/**
+ * The one Vite and React release the server-component pipeline is certified against. The plugin's
+ * guard and the consumer check read these; `component-certification.test.ts` holds the exact pins
+ * in every manifest that runs the pipeline to them, so a range bump cannot drift past the guard.
+ */
+export const CERTIFIED_COMPONENT_VITE = "8.2.1"
+export const CERTIFIED_COMPONENT_REACT = "19.3.1"

package/src/internal/codegen.ts

@@ -17,6 +17,13 @@ import {
 import { PRERENDERED_GLOBAL } from "../router.ts"
 import { jsStringLiteral, jsValueLiteral } from "./js-string.ts"
 
+/** The refusal for a server build given no client entry, shared by the codegen and `buildServer`. */
+export function missingClientEntry(clientEntry: unknown): TypeError {
+  return new TypeError(
+    `[nifra/web] the server build needs the client build: pass client (the manifest buildClient returned) or clientEntry (its entry URL), got clientEntry ${clientEntry === null ? "null" : typeof clientEntry}; pass clientEntry "" for an app with no client script`,
+  )
+}
+
 /** The globals the page-state handover may set - nothing else in it reaches `window`. */
 const HANDOVER_GLOBALS = [
   DATA_GLOBAL,
@@ -474,6 +481,12 @@ export interface GenerateServerManifestOptions {
   /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`) - baked as
    * `export const copyChunks` when the client build split copy tables, for `createWebApp`. */
   readonly copyChunks?: Readonly<Record<string, string>> | undefined
+  /**
+   * The request path of every file the build emitted: the client build's `assets` and the `public/`
+   * files it copied. Baked as `export const buildAssets` (a `Set`) and `isBuildAsset(pathname)`, so a
+   * server entry or a host policy can allow exactly the files that exist. Omitted ⇒ neither export.
+   */
+  readonly buildAssets?: readonly string[] | undefined
   /** Emit **lazy** per-route loaders (`() => import("./routes/x")`, a static specifier) instead of
    * eager `import * as`, so a bundler with code-splitting emits one chunk per route - loaded on the
    * first request to it, not all at boot (smaller cold-start parse). Default `false` (eager). Both
@@ -522,15 +535,12 @@ export function generateServerManifest(
     routeStyles,
     cssLoading: requestedCssLoading,
     copyChunks,
+    buildAssets,
     lazy = false,
   } = options
   // A missing entry would bake `clientEntry = undefined` and the build would still succeed, leaving
   // every hydrating page to fail at request time. `""` stays valid: an app with no client script.
-  if (typeof clientEntry !== "string") {
-    throw new TypeError(
-      `[nifra/web] the server build needs clientEntry (the built client entry URL, buildClient's manifest.entry), got ${clientEntry === null ? "null" : typeof clientEntry}; check the option is spelled clientEntry, or pass "" for an app with no client script`,
-    )
-  }
+  if (typeof clientEntry !== "string") throw missingClientEntry(clientEntry)
   const cssLoading = normalizeCssLoading(requestedCssLoading ?? DEFAULT_CSS_LOADING)
   // Every unique source file in the manifest, both halves of each, sorted for stable output. This is the
   // one generated module that imports frontend and backend halves together: it is the server's
@@ -568,6 +578,13 @@ export function generateServerManifest(
     copyChunks === undefined || Object.keys(copyChunks).length === 0
       ? []
       : [`export const copyChunks = ${jsValueLiteral(copyChunks)}`]
+  const buildAssetsLines =
+    buildAssets === undefined
+      ? []
+      : [
+          `export const buildAssets: ReadonlySet<string> = new Set(${jsValueLiteral([...new Set(buildAssets)].sort())})`,
+          "export const isBuildAsset = (pathname: string): boolean => buildAssets.has(pathname)",
+        ]
   if (lazy) {
     // Lazy: `() => import("./routes/x")` per route (static specifier → one chunk per route under a
     // code-splitting bundler, loaded on first request). The map keys are the route-relative paths
@@ -586,6 +603,7 @@ export function generateServerManifest(
       routeStylesLine,
       cssLoadingLine,
       ...copyChunksLines,
+      ...buildAssetsLines,
       `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER})`,
     ].join("\n")}\n`
   }
@@ -606,6 +624,7 @@ export function generateServerManifest(
     routeStylesLine,
     cssLoadingLine,
     ...copyChunksLines,
+    ...buildAssetsLines,
     `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER})`,
   ].join("\n")}\n`
 }

package/src/internal/node-adapter.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+/** A package as installed: its directory and the version its package.json declares. */
+export interface InstalledPackage {
+  readonly dir: string
+  readonly version: string
+}
+
+/** The `version` a package.json declares, or `undefined` when it declares none. */
+function manifestVersion(path: string | URL): string | undefined {
+  const manifest: unknown = JSON.parse(readFileSync(path, "utf8"))
+  return typeof manifest === "object" &&
+    manifest !== null &&
+    "version" in manifest &&
+    typeof manifest.version === "string"
+    ? manifest.version
+    : undefined
+}
+
+/**
+ * The copy of `name` a module in `fromDir` imports: the first `node_modules/<name>` walking up, as
+ * both bundlers resolve a bare specifier. Walked rather than `Bun.resolveSync`, which keeps its first
+ * answer for the life of the process.
+ */
+export function installedPackage(name: string, fromDir: string): InstalledPackage | undefined {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const manifest = join(dir, "node_modules", name, "package.json")
+    if (existsSync(manifest)) {
+      const version = manifestVersion(manifest)
+      return version === undefined ? undefined : { dir: dirname(manifest), version }
+    }
+    if (dirname(dir) === dir) return undefined
+  }
+}
+
+/**
+ * Why a `--target node` build whose server entry is generated in `workDir` must stop before
+ * bundling, or `undefined`. The entry is written for the `@nifrajs/node` of this package's release and
+ * the bundle inlines whichever copy is installed: a 5.3 adapter built cleanly, then threw at startup
+ * on the static mounts.
+ */
+export function nodeAdapterRefusal(
+  workDir: string,
+  // src/internal/ and dist/internal/ both sit two levels below the package root.
+  webVersion = manifestVersion(new URL("../../package.json", import.meta.url)),
+): string | undefined {
+  const adapter = installedPackage("@nifrajs/node", workDir)
+  if (adapter === undefined || webVersion === undefined) return undefined
+  if (Bun.semver.order(adapter.version, webVersion) >= 0) return undefined
+  return (
+    `[nifra/web] --target node would bundle @nifrajs/node ${adapter.version} (${adapter.dir}), older ` +
+    `than @nifrajs/web ${webVersion}. The server entry is generated for the adapter of the same ` +
+    "release, and an older one can fail when the server starts. Upgrade the nifra packages " +
+    `together: nifra upgrade ${webVersion}`
+  )
+}