@nifrajs/web 3.2.0 → 3.5.0

package/dist/trusted-html.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A framework-neutral trust boundary for the small set of adapters that intentionally inject HTML.
+ *
+ * `TrustedHtml` is a type-level brand, not a sanitizer. Callers must sanitize untrusted input with a
+ * well-reviewed allowlist sanitizer before calling {@link trustHtml}; build-time markdown and
+ * application-owned templates may use it directly after review. Keeping the constructor explicit
+ * makes every raw-HTML sink audit-greppable and prevents an ordinary string from type-checking by
+ * accident.
+ */
+declare const TRUSTED_HTML_BRAND: unique symbol;
+declare const SANITIZED_HTML_BRAND: unique symbol;
+export type TrustedHtml = string & {
+    readonly [TRUSTED_HTML_BRAND]: "trusted-html";
+};
+/** HTML returned by an explicit, caller-supplied sanitizer. It is also trusted by the adapters. */
+export type SanitizedHtml = TrustedHtml & {
+    readonly [SANITIZED_HTML_BRAND]: "sanitized-html";
+};
+/** The only contract a project-specific, allowlist-based HTML sanitizer must satisfy. */
+export type HtmlSanitizer = (value: string) => string;
+/** Mark already-sanitized or application-owned HTML for an intentional raw-HTML adapter sink. */
+export declare function trustHtml(value: string): TrustedHtml;
+/**
+ * Run untrusted markup through an explicit sanitizer before it reaches a raw-HTML adapter.
+ *
+ * Nifra deliberately does not bundle a sanitizer: applications choose the maintained allowlist
+ * appropriate to their runtime and content policy. Requiring the sanitizer as an argument prevents
+ * `sanitizedHtml(value)` from silently becoming an alias for the unsafe trust operation.
+ */
+export declare function sanitizeHtml(value: string, sanitizer: HtmlSanitizer): SanitizedHtml;
+/** Explicit sanitized-content vocabulary for callers and security audits. */
+export declare const sanitizedHtml: typeof sanitizeHtml;
+export {};
+//# sourceMappingURL=trusted-html.d.ts.map

package/dist/trusted-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-html.d.ts","sourceRoot":"","sources":["../src/trusted-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAA;AAC/C,OAAO,CAAC,MAAM,oBAAoB,EAAE,OAAO,MAAM,CAAA;AAEjD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,cAAc,CAAA;CAAE,CAAA;AAEpF,mGAAmG;AACnG,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAE/F,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;AAErD,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAGpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,aAAa,CAMnF;AAED,6EAA6E;AAC7E,eAAO,MAAM,aAAa,qBAAe,CAAA"}

package/dist/trusted-html.js

@@ -0,0 +1,35 @@
+/**
+ * A framework-neutral trust boundary for the small set of adapters that intentionally inject HTML.
+ *
+ * `TrustedHtml` is a type-level brand, not a sanitizer. Callers must sanitize untrusted input with a
+ * well-reviewed allowlist sanitizer before calling {@link trustHtml}; build-time markdown and
+ * application-owned templates may use it directly after review. Keeping the constructor explicit
+ * makes every raw-HTML sink audit-greppable and prevents an ordinary string from type-checking by
+ * accident.
+ */
+/** Mark already-sanitized or application-owned HTML for an intentional raw-HTML adapter sink. */
+export function trustHtml(value) {
+    if (typeof value !== "string")
+        throw new TypeError("trusted HTML must be a string");
+    return value;
+}
+/**
+ * Run untrusted markup through an explicit sanitizer before it reaches a raw-HTML adapter.
+ *
+ * Nifra deliberately does not bundle a sanitizer: applications choose the maintained allowlist
+ * appropriate to their runtime and content policy. Requiring the sanitizer as an argument prevents
+ * `sanitizedHtml(value)` from silently becoming an alias for the unsafe trust operation.
+ */
+export function sanitizeHtml(value, sanitizer) {
+    if (typeof value !== "string")
+        throw new TypeError("HTML to sanitize must be a string");
+    if (typeof sanitizer !== "function")
+        throw new TypeError("an HTML sanitizer is required");
+    const sanitized = sanitizer(value);
+    if (typeof sanitized !== "string")
+        throw new TypeError("HTML sanitizer must return a string");
+    return sanitized;
+}
+/** Explicit sanitized-content vocabulary for callers and security audits. */
+export const sanitizedHtml = sanitizeHtml;
+//# sourceMappingURL=trusted-html.js.map

package/dist/trusted-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-html.js","sourceRoot":"","sources":["../src/trusted-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,iGAAiG;AACjG,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAA;IACnF,OAAO,KAAoB,CAAA;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,SAAwB;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAA;IACvF,IAAI,OAAO,SAAS,KAAK,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAA;IACzF,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAClC,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAA;IAC7F,OAAO,SAA0B,CAAA;AACnC,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web",
-  "version": "3.2.0",
+  "version": "3.5.0",
   "description": "Framework-agnostic SSR core for nifra - the render seam + HTML document orchestration.",
   "keywords": [
     "bun",
@@ -196,8 +196,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "3.2.0",
-    "@nifrajs/island-trigger": "3.2.0"
+    "@nifrajs/core": "3.5.0",
+    "@nifrajs/island-trigger": "3.5.0"
   },
   "peerDependencies": {
     "@babel/core": "^7.26.0",

package/src/build-plan.ts

@@ -1,4 +1,5 @@
 import { basename as pathBasename } from "node:path"
+import type { CssLoadingMode } from "./css-contract.ts"
 import type { ClientModuleGraph } from "./module-graph.ts"
 
 export interface BuildManifest {
@@ -19,6 +20,10 @@ export interface BuildManifest {
    * imported the CSS; the always-safe fallback `createWebApp` links when a route has no per-route entry
    * in {@link routeStyles}. Omitted when the app imports no CSS. */
   readonly css?: readonly string[]
+  /** Whether the Vite client build kept CSS split by entry/chunk. Absent for the native Bun build. */
+  readonly cssCodeSplit?: boolean
+  /** How framework-owned SSR stylesheet links should become active. Defaults to `blocking`. */
+  readonly cssLoading?: CssLoadingMode
   /** `routeId → [chain CSS URLs]` - only the stylesheets the matched route's layout chain + own file
    * actually use (Bun emits a per-entrypoint CSS bundle per route/layout, with shared-component CSS
    * inlined into each consumer). `createWebApp` links these instead of the aggregate, so a page ships
@@ -150,6 +155,10 @@ export interface Bundler {
     readonly define?: Readonly<Record<string, string>>
     readonly publicDir?: string | false
     readonly publicEnvPrefix?: string
+    /** Vite CSS splitting policy; the Bun strategy rejects `false` and otherwise preserves its native behavior. */
+    readonly cssCodeSplit?: boolean
+    /** Framework-owned stylesheet activation policy; supported by both server strategies. */
+    readonly cssLoading?: CssLoadingMode
     /** Project root (Vite needs it; the Bun strategy ignores it). */
     readonly root?: string
   }): Promise<BuildManifest>
@@ -160,8 +169,14 @@ export interface Bundler {
     readonly outDir: string
     readonly clientEntry: string
     readonly target: "browser" | "node" | "bun"
+    /** The client build's aggregate stylesheet URLs to bake into the server manifest. */
+    readonly styles?: readonly string[]
+    /** The client build's per-route stylesheet map to bake into the server manifest. */
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>>
     readonly plugins?: readonly unknown[]
     readonly define?: Readonly<Record<string, string>>
+    /** CSS activation policy to bake into the generated server manifest. */
+    readonly cssLoading?: CssLoadingMode
     readonly root?: string
   }): Promise<ServerBuild>
 }
@@ -618,6 +633,8 @@ export interface ManifestDrift {
 const MANIFEST_ROUTE_ENTRY = /^[ \t]+(["'])([^"'\n]+)\1\s*:\s*(?:m\d+\b|\(\s*\)\s*=>\s*import\b)/gm
 // The baked client-entry line: `export const clientEntry = "…"`.
 const MANIFEST_CLIENT_ENTRY = /export\s+const\s+clientEntry\s*=\s*["']([^"']+)["']/
+// The baked stylesheet activation line: `generateServerManifest` emits this after the style maps.
+const MANIFEST_CSS_LOADING = /export\s+const\s+cssLoading\s*=\s*["'](blocking|deferred)["']/
 
 /**
  * Extract the route-relative file list a committed server-manifest declares, as the same
@@ -642,6 +659,11 @@ export function parseManifestClientEntry(source: string): string | undefined {
   return MANIFEST_CLIENT_ENTRY.exec(source)?.[1]
 }
 
+/** The baked framework stylesheet activation mode, or `undefined` for an older manifest. Pure. */
+export function parseManifestCssLoading(source: string): CssLoadingMode | undefined {
+  return MANIFEST_CSS_LOADING.exec(source)?.[1] as CssLoadingMode | undefined
+}
+
 // The baked asset lines `generateServerManifest` emits: `export const styles = […]` then
 // `export const routeStyles = {…}`, each a JSON literal running to the next `export const`. Extracted
 // with `indexOf` slicing rather than a lazy `[\s\S]*?` regex: the slice is multi-line by nature (a
@@ -653,7 +675,7 @@ function bakedManifestLiteral(source: string, name: string): string | undefined
   if (start === -1) return undefined
   const from = start + opener.length
   const end = source.indexOf("\nexport const ", from)
-  return end === -1 ? undefined : source.slice(from, end)
+  return source.slice(from, end === -1 ? source.length : end).trim()
 }
 
 /** Parse a baked JSON literal captured from a committed manifest, tolerating a formatter's TRAILING COMMAS

package/src/build-vite.ts

@@ -28,6 +28,13 @@ import {
   publicEnvDefines,
 } from "./build.ts"
 import type { BuildManifest, BuildTarget, Bundler, ServerBuild } from "./build-plan.ts"
+import {
+  assertCssLoadingCompatible,
+  type CssLoadingMode,
+  DEFAULT_CSS_LOADING,
+  normalizeCssCodeSplit,
+  normalizeCssLoading,
+} from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
 import { viteDedupePackages } from "./internal/identity-policy.ts"
@@ -117,6 +124,17 @@ export interface BuildClientViteOptions extends Omit<BuildClientOptions, "plugin
   readonly vitePlugins?: readonly unknown[]
   /** Vite project root (default: the parent of `routesDir`). Manifest keys are relative to it. */
   readonly root?: string
+  /**
+   * Vite's CSS output strategy (default `true`). Set to `false` to emit one aggregate stylesheet for
+   * the whole client, preventing lazy-route prefetch from attaching additional stylesheets.
+   */
+  readonly cssCodeSplit?: boolean
+  /**
+   * Activation policy for framework-owned SSR stylesheet links (default `"blocking"`). `"deferred"`
+   * fetches with `media="print"` and the generated client promotes the links before mounting. It must
+   * be paired with `cssCodeSplit: false`; split lazy chunks can otherwise attach CSS during prefetch.
+   */
+  readonly cssLoading?: CssLoadingMode
 }
 
 /**
@@ -130,6 +148,9 @@ export interface BuildClientViteOptions extends Omit<BuildClientOptions, "plugin
  */
 export async function buildClientVite(options: BuildClientViteOptions): Promise<BuildManifest> {
   const { routesDir, outDir, clientModule } = options
+  const cssCodeSplit = normalizeCssCodeSplit(options.cssCodeSplit)
+  const cssLoading = normalizeCssLoading(options.cssLoading ?? DEFAULT_CSS_LOADING)
+  assertCssLoadingCompatible(cssCodeSplit, cssLoading)
   const root = resolvePath(options.root ?? dirname(routesDir))
   await assertIdentityParity(root)
   const resolve = options.resolve ?? ((file: string) => `${routesDir}/${file}`)
@@ -219,6 +240,7 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
           outDir,
           emptyOutDir: false, // buildTargetWith owns outDir lifecycle; never let Vite wipe sibling files
           manifest: true,
+          cssCodeSplit,
           minify: options.minify !== false,
           rollupOptions: {
             // Keep `node:` builtins as external specifiers so the leak guard sees `node:crypto` and can
@@ -298,14 +320,20 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     }
     return [...urls]
   }
-  // CSS aggregate - every stylesheet the app emits, the always-safe fallback.
+  // CSS aggregate - every stylesheet the app emits, the always-safe fallback. With native Vite
+  // `cssCodeSplit: false`, the aggregate is a standalone manifest asset and is not listed in any
+  // JavaScript entry's `css` array. Collect both shapes so the framework manifest never loses the only
+  // stylesheet in a single-file build.
   const allCss = new Set<string>()
   for (const entry of Object.values(viteManifest)) {
+    if (entry.file.endsWith(".css")) allCss.add(url(entry.file))
     for (const css of entry.css ?? []) allCss.add(url(css))
   }
   const css = [...allCss]
   const routeStyles: Record<string, readonly string[]> = {}
-  if (css.length > 0) {
+  // 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])
   }
@@ -326,6 +354,8 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     entry: url(bootstrap.file),
     assets: [...assets],
     routes,
+    cssCodeSplit,
+    cssLoading,
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
@@ -343,6 +373,8 @@ export interface BuildServerViteOptions {
   readonly clientEntry: string
   readonly styles?: readonly string[] | undefined
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
+  readonly cssLoading?: CssLoadingMode
   readonly resolve?: (file: string) => string
   readonly manifestFile?: string
   readonly vitePlugins?: readonly unknown[]
@@ -434,7 +466,7 @@ function edgeBuiltinGuard(): EdgeGuardPlugin {
  * The client-leak guards are deliberately NOT run here: a server bundle's `node:` imports are legitimate.
  */
 export async function buildServerVite(options: BuildServerViteOptions): Promise<ServerBuild> {
-  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles } = options
+  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles, cssLoading } = options
   const root = resolvePath(options.root ?? dirname(routesDir))
   const entryDir = dirname(serverEntry)
   const manifestFile = options.manifestFile ?? "server-manifest.ts"
@@ -451,7 +483,13 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
   const routeManifest = discoverRoutes(routesDir)
   writeFileSync(
     `${entryDir}/${manifestFile}`,
-    generateServerManifest(routeManifest, { resolve, clientEntry, styles, routeStyles }),
+    generateServerManifest(routeManifest, {
+      resolve,
+      clientEntry,
+      styles,
+      routeStyles,
+      ...(cssLoading !== undefined ? { cssLoading } : {}),
+    }),
   )
 
   // Pin the mode to match NODE_ENV - the react plugin's JSX runtime (jsx vs jsxDEV) follows it, and a
@@ -536,6 +574,8 @@ export const viteBundler: Bundler = {
       ...(input.plugins ? { vitePlugins: input.plugins } : {}),
       ...(input.conditions ? { conditions: input.conditions } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssCodeSplit !== undefined ? { cssCodeSplit: input.cssCodeSplit } : {}),
+      ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
       ...(input.publicDir !== undefined ? { publicDir: input.publicDir } : {}),
       ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
       ...(input.root ? { root: input.root } : {}),
@@ -547,8 +587,11 @@ export const viteBundler: Bundler = {
       outDir: input.outDir,
       clientEntry: input.clientEntry,
       target: input.target,
+      ...(input.styles !== undefined ? { styles: input.styles } : {}),
+      ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
       ...(input.plugins ? { vitePlugins: input.plugins } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
       ...(input.root ? { root: input.root } : {}),
     }),
 }

package/src/build.ts

@@ -31,6 +31,7 @@ import {
   formatNodeBuiltinLeak,
   formatServerOnlyLeak,
   parseManifestClientEntry,
+  parseManifestCssLoading,
   parseManifestRouteStyles,
   parseManifestStyles,
   planBuildTarget,
@@ -38,6 +39,7 @@ import {
   type SizeReport,
 } from "./build-plan.ts"
 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 { dedupePolicyFor } from "./internal/identity-policy.ts"
@@ -350,11 +352,13 @@ export function resyncServerManifestSource(
   manifest: Parameters<typeof generateServerManifest>[0],
   routesPrefix: string,
 ): string {
+  const cssLoading = parseManifestCssLoading(source)
   return generateServerManifest(manifest, {
     resolve: (file) => `${routesPrefix}${file}`,
     clientEntry: parseManifestClientEntry(source) ?? "",
     styles: parseManifestStyles(source),
     routeStyles: parseManifestRouteStyles(source),
+    ...(cssLoading !== undefined ? { cssLoading } : {}),
     lazy: MANIFEST_IS_LAZY.test(source),
   })
 }
@@ -626,6 +630,8 @@ export interface BuildServerOptions {
   readonly styles?: readonly string[] | undefined
   /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked alongside `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
+  readonly cssLoading?: CssLoadingMode
   /** Route/layout file → import specifier in the generated manifest (default: a relative path from the
    * manifest's location - written next to `serverEntry` - to `routesDir`). */
   readonly resolve?: (file: string) => string
@@ -847,7 +853,7 @@ const solidWebServerPlugin = (from: string): BunPlugin => ({
  * silently ships a broken worker.
  */
 export async function buildServer(options: BuildServerOptions): Promise<ServerBuild> {
-  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles } = options
+  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles, cssLoading } = options
   const entryDir = dirname(serverEntry)
   const manifestFile = options.manifestFile ?? "server-manifest.ts"
   // Default: import routes relative from the generated manifest (next to serverEntry) to routesDir.
@@ -866,7 +872,14 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
   const manifest = discoverRoutes(routesDir)
   writeFileSync(
     `${entryDir}/${manifestFile}`,
-    generateServerManifest(manifest, { resolve, clientEntry, styles, routeStyles, lazy }),
+    generateServerManifest(manifest, {
+      resolve,
+      clientEntry,
+      styles,
+      routeStyles,
+      ...(cssLoading !== undefined ? { cssLoading } : {}),
+      lazy,
+    }),
   )
 
   const result = await Bun.build({
@@ -963,7 +976,9 @@ export function generateServerEntry(options: {
   if (backendImport !== undefined) {
     lines.push(`import { backend } from ${JSON.stringify(backendImport)}`)
   }
-  lines.push('import { clientEntry, manifest, styles, routeStyles } from "./server-manifest"')
+  lines.push(
+    'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
+  )
   // cf-pages/vercel/deno need the fetch-handler shape; bun/node call app.fetch directly.
   const usesToFetch = target === "cf-pages" || target === "vercel" || target === "deno"
   if (usesToFetch) lines.push('import { toFetchHandler } from "@nifrajs/core/server"')
@@ -977,6 +992,7 @@ export function generateServerEntry(options: {
     "  clientEntry,",
     "  styles,",
     "  routeStyles,",
+    "  cssLoading,",
     ...(backendImport !== undefined ? ["  api: inProcessClient(backend),"] : []),
     `  title: ${JSON.stringify(title)},`,
     "})",
@@ -1157,6 +1173,18 @@ export interface BuildTargetOptions {
   readonly publicDir?: string | false
   /** Prefix of environment variables allowed into the client bundle (default `"PUBLIC_"`). */
   readonly publicEnvPrefix?: string
+  /**
+   * Vite-only CSS output policy. `false` emits one aggregate stylesheet. The native Bun build does not
+   * support this switch and fails closed if it is supplied instead of silently ignoring it.
+   */
+  readonly cssCodeSplit?: boolean
+  /**
+   * Activation policy for framework-owned SSR stylesheet links. Defaults to `"blocking"`; `"deferred"`
+   * fetches with `media="print"` and promotes before hydration. With Vite, pair it with
+   * `cssCodeSplit: false`; the native Bun build supports the activation policy but keeps its existing
+   * CSS output strategy.
+   */
+  readonly cssLoading?: CssLoadingMode
   /** Document `<title>` for the generated server entry. */
   readonly title?: string
 }
@@ -1198,17 +1226,25 @@ export interface BuildTargetResult {
  */
 /** The default (Bun) strategy - `buildClient`/`buildServer` from this module. */
 export const bunBundler: Bundler = {
-  buildClient: (input) =>
-    buildClient({
+  buildClient: (input) => {
+    const cssCodeSplit = normalizeCssCodeSplit(input.cssCodeSplit)
+    if (cssCodeSplit === false) {
+      throw new Error(
+        "[nifra/web] cssCodeSplit: false is a Vite-only production option. Use buildTargetVite or remove it for the native Bun build.",
+      )
+    }
+    return buildClient({
       routesDir: input.routesDir,
       outDir: input.outDir,
       clientModule: input.clientModule,
       ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
       ...(input.conditions ? { conditions: input.conditions } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssCodeSplit !== undefined ? { cssCodeSplit } : {}),
       ...(input.publicDir !== undefined ? { publicDir: input.publicDir } : {}),
       ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
-    }),
+    })
+  },
   buildServer: (input) =>
     buildServer({
       routesDir: input.routesDir,
@@ -1216,8 +1252,11 @@ export const bunBundler: Bundler = {
       outDir: input.outDir,
       clientEntry: input.clientEntry,
       target: input.target,
+      ...(input.styles !== undefined ? { styles: input.styles } : {}),
+      ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
       ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
     }),
 }
 
@@ -1241,6 +1280,10 @@ export async function buildTargetWith(
   bundler: Bundler,
 ): Promise<BuildTargetResult> {
   const { routesDir, outDir, workDir } = options
+  const requestedCssCodeSplit =
+    options.cssCodeSplit === undefined ? undefined : normalizeCssCodeSplit(options.cssCodeSplit)
+  const requestedCssLoading =
+    options.cssLoading === undefined ? undefined : normalizeCssLoading(options.cssLoading)
   const targetPlan = planBuildTarget(target, outDir)
   const { rmSync } = await import("node:fs")
   rmSync(outDir, { recursive: true, force: true })
@@ -1259,8 +1302,16 @@ export async function buildTargetWith(
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
     publicDir: false,
     ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
+    ...(requestedCssCodeSplit !== undefined ? { cssCodeSplit: requestedCssCodeSplit } : {}),
+    ...(requestedCssLoading !== undefined ? { cssLoading: requestedCssLoading } : {}),
     root: resolvePath(dirname(routesDir)),
   })
+  // Bun's client builder has no CSS-loading field, but the server-side document policy is bundler
+  // independent. Carry the requested policy into the result so static prerender callbacks and the
+  // generated server entry see the same choice on both build strategies.
+  if (requestedCssLoading !== undefined && client.cssLoading !== requestedCssLoading) {
+    client = { ...client, cssLoading: requestedCssLoading }
+  }
   const publicDir =
     options.publicDir === false
       ? undefined
@@ -1269,6 +1320,11 @@ export async function buildTargetWith(
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
   if (publicFiles.length > 0) {
     client = { ...client, publicFiles }
+  }
+  // `buildClient` writes its first manifest before the target orchestration knows the activation policy
+  // (the native Bun client builder has no CSS-loading option). Persist the target-level additions even
+  // when the app has no public/ files; otherwise the returned manifest and the deploy artifact disagree.
+  if (requestedCssLoading !== undefined || publicFiles.length > 0) {
     writeFileSync(`${assetsDir}/manifest.json`, JSON.stringify(client, null, 2))
   }
 
@@ -1330,8 +1386,15 @@ export async function buildTargetWith(
     outDir: `${workDir}/server`,
     clientEntry: client.entry,
     target: targetPlan.serverTarget,
+    ...(client.css !== undefined ? { styles: client.css } : {}),
+    ...(client.routeStyles !== undefined ? { routeStyles: client.routeStyles } : {}),
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
+    ...(client.cssLoading !== undefined
+      ? { cssLoading: client.cssLoading }
+      : requestedCssLoading !== undefined
+        ? { cssLoading: requestedCssLoading }
+        : {}),
     root: resolvePath(dirname(routesDir)),
   })
 

package/src/client.ts

@@ -53,6 +53,146 @@ export interface InstallHistoryOptions {
   readonly fallback?: (path: string) => void
 }
 
+/** Options for {@link waitForStyles}. */
+export interface WaitForStylesOptions {
+  /**
+   * Maximum time to wait for one framework-owned deferred stylesheet before hydrating anyway.
+   * Defaults to 4000 ms and is capped at 30000 ms so a bad value cannot leave the app inert forever.
+   */
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_CSS_WAIT_MS = 4_000
+const MAX_CSS_WAIT_MS = 30_000
+type CssLinkState = "loaded" | "error" | "timeout"
+
+// Per-link promises keep repeated calls idempotent without retaining an entire document after a hard
+// navigation. A WeakMap also lets tests and embedded documents replace `globalThis.document` safely.
+const stylesheetWaits = new WeakMap<HTMLLinkElement, Promise<void>>()
+
+const cssLinkStateOf = (link: HTMLLinkElement): CssLinkState | undefined => {
+  const state = link.getAttribute("data-nifra-css-state")
+  return state === "loaded" || state === "error" || state === "timeout" ? state : undefined
+}
+
+const hasLoadedStylesheet = (link: HTMLLinkElement): boolean => {
+  // Accessing `sheet` is safe for cross-origin stylesheets, but a browser may still throw while it is
+  // tearing down a document. Treat that as "not observed yet"; the load/error listener or the bounded
+  // timer is the authoritative fallback.
+  try {
+    return link.sheet !== null
+  } catch {
+    return false
+  }
+}
+
+const stylesheetLabel = (link: HTMLLinkElement): string =>
+  link.getAttribute("href") ?? link.href ?? "<unknown>"
+
+/**
+ * Wait for one server-emitted deferred stylesheet. The promise ALWAYS settles: a failed or slow CSS
+ * request must not leave the server-rendered page's loader visible forever. `media="all"` is applied on
+ * every terminal state so a late network completion cannot leave a link permanently in print media.
+ */
+const waitForStylesheet = (link: HTMLLinkElement, timeoutMs: number): Promise<void> =>
+  new Promise<void>((resolve) => {
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+
+    const cleanup = (): void => {
+      link.removeEventListener("load", onLoad)
+      link.removeEventListener("error", onError)
+      if (timer !== undefined) clearTimeout(timer)
+    }
+    const finish = (state: CssLinkState): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      link.setAttribute("data-nifra-css-state", state)
+      // Only the coordinator promotes the framework-owned link, after the resource has settled.
+      link.media = "all"
+      resolve()
+    }
+    const onLoad = (): void => finish("loaded")
+    const onError = (): void => {
+      console.error(`[nifra/web] stylesheet failed to load: ${stylesheetLabel(link)}`)
+      finish("error")
+    }
+
+    const prior = cssLinkStateOf(link)
+    if (prior !== undefined) {
+      finish(prior)
+      return
+    }
+    if (hasLoadedStylesheet(link)) {
+      finish("loaded")
+      return
+    }
+
+    // Attach listeners before the second loaded-sheet check: a cached resource can transition between
+    // the first check and listener registration, and the second check closes that small race.
+    link.addEventListener("load", onLoad, { once: true })
+    link.addEventListener("error", onError, { once: true })
+    timer = setTimeout(() => {
+      console.warn(
+        `[nifra/web] stylesheet load timed out after ${timeoutMs}ms: ${stylesheetLabel(link)}`,
+      )
+      finish("timeout")
+    }, timeoutMs)
+    if (hasLoadedStylesheet(link)) finish("loaded")
+  })
+
+const validateCssWaitMs = (value: number): number => {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `[nifra/web] css wait timeout must be a finite positive number, received ${value}`,
+    )
+  }
+  return Math.min(value, MAX_CSS_WAIT_MS)
+}
+
+/**
+ * Wait for the framework-owned deferred stylesheet links in the initial document, then promote them to
+ * `media="all"`. It is safe to call more than once: repeated calls for one document share the same
+ * per-link waits, and duplicate framework links are removed before waiting. Blocking links are not
+ * touched.
+ *
+ * This function lives in the browser-only `@nifrajs/web/client` entry. It is nevertheless defensive
+ * when imported in a non-DOM environment so an accidental import cannot crash a server process.
+ */
+export function waitForStyles(options: WaitForStylesOptions = {}): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve()
+  const timeoutMs = validateCssWaitMs(options.timeoutMs ?? DEFAULT_CSS_WAIT_MS)
+  const links = Array.from(
+    document.querySelectorAll<HTMLLinkElement>('link[data-nifra-css="deferred"]'),
+  ).filter(
+    (link) =>
+      link.getAttribute("data-nifra-css") === "deferred" && link.rel.toLowerCase() === "stylesheet",
+  )
+  const unique: HTMLLinkElement[] = []
+  const seen = new Set<string>()
+  for (const link of links) {
+    const key = stylesheetLabel(link)
+    if (seen.has(key)) {
+      // Only remove a duplicate carrying the framework marker; author-owned links are outside this
+      // selector and cannot be affected. Keeping the first link preserves its event state and cache.
+      link.remove()
+      continue
+    }
+    seen.add(key)
+    unique.push(link)
+  }
+  if (unique.length === 0) return Promise.resolve()
+  const promises = unique.map((link) => {
+    const existing = stylesheetWaits.get(link)
+    if (existing !== undefined) return existing
+    const promise = waitForStylesheet(link, timeoutMs)
+    stylesheetWaits.set(link, promise)
+    return promise
+  })
+  return Promise.all(promises).then(() => undefined)
+}
+
 /**
  * Attach history + link interception to a router. Returns a teardown function that removes the
  * listeners. A data-fetch failure during a client navigation falls back to a full-page load, so