@nifrajs/web 5.0.0 → 5.2.0

package/src/internal/render-document.ts

@@ -6,21 +6,28 @@ import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../defer
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
 import type {
   Loader as LayoutLoader,
-  LinkDescriptor,
   Meta,
-  MetaDescriptor,
   MetaInput,
   RouteModule,
-  ScriptDescriptor,
   UnsafeScriptDescriptor,
 } from "../manifest.ts"
-import type { MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
+import type {
+  DocumentParts,
+  MatchChain,
+  PageLocale,
+  PageLocales,
+  RenderAdapter,
+  RenderProps,
+} from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
+  COPY_CHUNKS_GLOBAL,
+  COPY_REALM,
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
@@ -114,6 +121,15 @@ export interface RenderPageOptions {
   /** SSG: the URL of a JSON array of the prerendered paths, handed over in place of
    * {@link prerenderedPaths} so a large set is fetched once instead of riding in every page. */
   readonly prerenderedListUrl?: string
+  /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`), handed over to the
+   * client; the chunks this page reads its copy from are preloaded. Omit ⇒ none. */
+  readonly copyChunks?: Readonly<Record<string, string>>
+  /** The page's locale from the app's locale routing: `<html lang dir>` default to it unless `head`
+   * sets `lang`, the response carries `Content-Language`, and the adapter reads it as
+   * `RenderProps.locale`. Omit ⇒ none of these. */
+  readonly locale?: PageLocale
+  /** The served locales, handed to the client so it names each page's locale on navigation. */
+  readonly locales?: PageLocales
   /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
    * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
   readonly revalidate?: number
@@ -187,7 +203,7 @@ export interface RenderPageOptions {
    * prefix/suffix, tail statics) on the first render and reuses afterwards, skipping their re-assembly.
    *
    * Only pass a cache when every shell-shaping input is IDENTICAL across the requests sharing it:
-   * same `head` content (a static meta chain - never a `meta(data)` function), `title`, `styles`,
+   * same `head` content (a static meta chain - never a `meta(data)` function), `locale`, `title`, `styles`,
    * `cssLoading`, `preload`, `islandScripts`, `clientEntry`, `rootId`, `hydrate`, and `prerenderedPaths`.
    * Per-request
    * values (`data`, `params`, `search`, `actionData`, `layoutData`, deferred state) are always assembled
@@ -201,8 +217,10 @@ export interface RenderPageOptions {
 export interface RenderAssemblyCache {
   /** Shell up to (not including) the deferred-runtime insertion point. */
   shellPre?: string
-  /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
+  /** Shell from after the deferred-runtime insertion point through `<body>`. */
   shellPost?: string
+  /** The open `#root` container. */
+  rootOpen?: string
   /** Tail opener: the handover script open tag + the data member's key. */
   tailPre?: string
   /** Tail from after the per-request handover members (the route id, prerendered paths, the handover
@@ -249,6 +267,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     cssLoading: requestedCssLoading,
     prerenderedPaths = [],
     prerenderedListUrl,
+    copyChunks,
+    locale,
     revalidate,
     revalidateTags = [],
     routeId,
@@ -277,6 +297,13 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       : prerenderedPaths.length === 0
         ? ""
         : `,"${PRERENDERED_GLOBAL}":${serializeData(prerenderedPaths)}`
+  const copyHandover =
+    copyChunks === undefined ? "" : `,"${COPY_CHUNKS_GLOBAL}":${serializeData(copyChunks)}`
+  const localesHandover =
+    options.locales === undefined ? "" : `,"${LOCALES_GLOBAL}":${serializeData(options.locales)}`
+  // A route's `lang` wins with its own `dir`; otherwise the page's registered locale names both.
+  const lang = head?.lang ?? locale?.lang ?? "en"
+  const dir = head?.dir ?? (head?.lang === undefined ? locale?.dir : undefined)
   // Split deferred values: the component sees markers (id + promise) to `<Await>`; the serialized
   // data carries `{__nifra_deferred: id}` placeholders (promises don't serialize). `actionData` may
   // also `defer()` - split it too, continuing the id space so a single registry settles both. The
@@ -406,7 +433,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     // `<html>` attributes. `lang` defaults to `"en"`; `dir` is omitted entirely when unset, which IS
     // HTML's `ltr` default. Both attribute-escaped. `client.ts`'s `applyHead` mirrors this exact
     // defaulting on soft-nav, so a hard load and a client navigation produce the same `<html>`.
-    const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`
+    const htmlAttrs = ` lang="${escapeAttr(lang)}"${dir === undefined ? "" : ` dir="${escapeAttr(dir)}"`}`
     // Marks the container for the client entry when the id is not the one the entry falls back to.
     const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`
     // A non-hydrated page omits the adapter's hydration bootstrap entirely (Solid's `_$HY` registry
@@ -423,7 +450,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
       : ""
     slot.shellPre = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head, nonce)}${styleLinks}${entryPreloads}`
-    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
+    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body>`
+    slot.rootOpen = `<div id="${escapeAttr(rootId)}"${rootMarker}>`
     // Island bundles load regardless of `hydrate` - a static page (hydrate:false) ships no framework
     // client but can still mount no-framework islands (`@nifrajs/web/islands`).
     let islandTags = ""
@@ -432,7 +460,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     if (hydrate) {
       // Inert JSON, never executed: the page state needs no nonce and no hash under any CSP.
       slot.tailPre = `<script type="application/json" id="${HANDOVER_ID}">{"${DATA_GLOBAL}":`
-      slot.tailPost = `${route}${prerendered}}</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
+      slot.tailPost = `${route}${prerendered}${copyHandover}${localesHandover}}</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
     } else {
       slot.tailPre = ""
       slot.tailPost = `${islandTags}</body></html>`
@@ -441,7 +469,18 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
   // only when something actually deferred - matching the pre-cache emission exactly.
   const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
-  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`
+  // Per request, so outside the cached shell: one route serves every locale.
+  const copyPreloads =
+    hydrate && copyChunks !== undefined
+      ? copyPreloadLinks(copyChunks, options.path ?? "", lang)
+      : ""
+  const shellHtml = `${slot.shellPre}${copyPreloads}${runtimeSeam}${slot.shellPost}${slot.rootOpen}`
+  const parts: DocumentParts | undefined =
+    adapter.documentParts === true ? { head: "", body: "" } : undefined
+  const shellOf = (): string =>
+    parts === undefined || (parts.head === "" && parts.body === "")
+      ? shellHtml
+      : `${slot.shellPre}${copyPreloads}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
   // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
   // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
   const closeRootHtml = "</div>"
@@ -451,6 +490,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${slot.tailPost}`
     : (slot.tailPost as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
+  if (locale !== undefined) headers["content-language"] = lang
   // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
   // framework's own below, so `content-type` and the ISR channel stay authoritative - a caller must
   // not be able to mislabel the document or forge the freshness header by passing them here.
@@ -495,6 +535,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       ? { boundaries: boundarySplit.forComponent as BoundaryStates }
       : {}),
     ...(options.matchChain !== undefined ? { matchChain: options.matchChain } : {}),
+    ...(locale === undefined ? {} : { locale }),
   }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
@@ -504,13 +545,22 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
   // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
   if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
-    const out = adapter.renderToString(chain, renderProps)
+    const out =
+      parts !== undefined
+        ? adapter.renderToString(
+            chain,
+            renderProps,
+            nonce === undefined ? { parts } : { nonce, parts },
+          )
+        : nonce === undefined
+          ? adapter.renderToString(chain, renderProps)
+          : adapter.renderToString(chain, renderProps, { nonce })
     return typeof out === "string"
-      ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
+      ? new BufferedRenderedPage(shellOf() + out + closeRootHtml + tailHtml, status, headers)
       : out.then(
           (bodyHtml) =>
             new BufferedRenderedPage(
-              shellHtml + bodyHtml + closeRootHtml + tailHtml,
+              shellOf() + bodyHtml + closeRootHtml + tailHtml,
               status,
               headers,
             ),
@@ -521,7 +571,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     adapter,
     chain,
     renderProps,
-    shellHtml,
+    shellOf,
+    parts,
     closeRootHtml,
     allDeferred,
     tailHtml,
@@ -536,7 +587,8 @@ async function renderStreamedPage(
   adapter: RenderAdapter,
   chain: readonly unknown[],
   renderProps: RenderProps,
-  shellHtml: string,
+  shellOf: () => string,
+  parts: DocumentParts | undefined,
   closeRootHtml: string,
   allDeferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
   tailHtml: string,
@@ -550,13 +602,20 @@ async function renderStreamedPage(
   // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
   // sent. A *mid*-stream failure errors the body instead.
   const enc = TEXT_ENCODER
-  const shell = enc.encode(shellHtml)
   const closeRoot = enc.encode(closeRootHtml)
   const tail = enc.encode(tailHtml)
   const appStream =
-    nonce === undefined
-      ? await adapter.renderToStream(chain, renderProps)
-      : await adapter.renderToStream(chain, renderProps, { nonce })
+    parts !== undefined
+      ? await adapter.renderToStream(
+          chain,
+          renderProps,
+          nonce === undefined ? { parts } : { nonce, parts },
+        )
+      : nonce === undefined
+        ? await adapter.renderToStream(chain, renderProps)
+        : await adapter.renderToStream(chain, renderProps, { nonce })
+  // After the render: an adapter fills its document parts before handing back the stream.
+  const shell = enc.encode(shellOf())
   const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
   return new Response(body, { status, headers })
 }
@@ -1123,68 +1182,6 @@ function headTags(head: Meta | undefined, documentNonce?: string): string {
   return out
 }
 
-/**
- * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
- * engines which URL is authoritative for a page (deduping query-string / tracking variants).
- *
- * ```ts
- * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
- * ```
- */
-export function canonical(href: string): LinkDescriptor {
-  return { rel: "canonical", href }
-}
-
-/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
- * ones become tags. `type` defaults to `"website"`. */
-export interface OpenGraphInput {
-  readonly title?: string
-  readonly description?: string
-  /** Absolute URL of the share image (`og:image`). */
-  readonly image?: string
-  /** Canonical URL of the page (`og:url`). */
-  readonly url?: string
-  /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
-  readonly type?: string
-}
-
-/**
- * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
- * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
- *
- * ```ts
- * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
- * ```
- */
-export function openGraph(input: OpenGraphInput): MetaDescriptor[] {
-  const tags: MetaDescriptor[] = []
-  const add = (property: string, content: string | undefined): void => {
-    if (content !== undefined) tags.push({ property, content })
-  }
-  add("og:title", input.title)
-  add("og:description", input.description)
-  add("og:image", input.image)
-  add("og:url", input.url)
-  // `og:type` always present (the spec's required property) - default "website" when unset.
-  tags.push({ property: "og:type", content: input.type ?? "website" })
-  return tags
-}
-
-/**
- * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
- * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
- * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
- *
- * ```ts
- * export const meta = {
- *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
- * }
- * ```
- */
-export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
-  return { type: "application/ld+json", content: JSON.stringify(data) }
-}
-
 /**
  * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
  * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.
@@ -1209,3 +1206,25 @@ export function unsafeInlineScript(
     content,
   }
 }
+
+/** The copy chunks a page loads first, as `@nifrajs/i18n/copy` picks them in the browser, so they
+ * download beside the route's code instead of after it. */
+function copyPreloadLinks(
+  chunks: Readonly<Record<string, string>>,
+  path: string,
+  lang: string,
+): string {
+  const realm: unknown = Reflect.get(globalThis, Symbol.for(COPY_REALM))
+  if (typeof realm !== "object" || realm === null) return ""
+  const pageLocales: unknown = Reflect.get(realm, "pageLocales")
+  if (typeof pageLocales !== "function") return ""
+  const locales: unknown = Reflect.apply(pageLocales, realm, [path, lang])
+  if (!Array.isArray(locales)) return ""
+  let links = ""
+  for (const locale of locales) {
+    const url =
+      typeof locale === "string" && Object.hasOwn(chunks, locale) ? chunks[locale] : undefined
+    if (url !== undefined) links += `<link rel="modulepreload" href="${escapeAttr(url)}">`
+  }
+  return links
+}

package/src/internal/route-path.ts

@@ -6,3 +6,19 @@
  */
 export const requestPattern = (pattern: string): string =>
   pattern.normalize("NFC").replace(/[^!-~]/gu, encodeURIComponent)
+
+// This module also compiles without the DOM lib; at runtime the name is the browser's own global.
+declare const location: { readonly origin: string } | undefined
+
+/**
+ * An app path as a URL `fetch`, `history` and `location` resolve on this document's own origin. A path
+ * starting `//` or `/\` is the path of a page here (`https://shop.example//evil.example/x`), but resolved
+ * as written it is a protocol-relative URL to another host, so it is anchored to this origin.
+ */
+export const appUrl = (path: string): string =>
+  path.charCodeAt(0) === 47 /* / */ &&
+  (path.charCodeAt(1) === 47 || path.charCodeAt(1) === 92) /* / or \ */ &&
+  typeof location !== "undefined" &&
+  location.origin !== "null"
+    ? location.origin + path
+    : path

package/src/internal/secret-scan.ts

@@ -293,6 +293,98 @@ function formatMatches(text: string): Match[] {
   return matches
 }
 
+/** Words that mark a whole `_`/`-` segment of a value as a stand-in: `your_signing_secret`. */
+const PLACEHOLDER_SEGMENT =
+  /^(?:your|example|placeholder|sample|dummy|changeme|replace|generated|x{3,})$/
+
+const placeholderSegments = (value: string): boolean =>
+  value
+    .toLowerCase()
+    .split(/[_-]/)
+    .some((segment) => PLACEHOLDER_SEGMENT.test(segment))
+
+/** A word-cased label: letters and marks, hyphen-joined words, an acronym. No digits, no runs of
+ * mixed case, no credential punctuation. */
+const LABEL = /^(?:\p{Lu}{1,4}|\p{Lu}?[\p{Ll}\p{M}]+)(?:-(?:\p{Lu}{1,4}|\p{Lu}?[\p{Ll}\p{M}]+))*$/u
+
+/** How many string values a catalog holds at least, and the share of them that is prose. */
+const CATALOG_VALUES = 10
+
+/** Where a `/` starts a regular expression: after anything but a value's end. */
+const VALUE_END = /[\w$)\]}"'`]/
+
+/**
+ * The spans of top-level object literals that read as message catalogs: at least
+ * {@link CATALOG_VALUES} string property values, most of them prose with whitespace. A lexer, not a
+ * parser, so a build scans without TypeScript; strings, comments and regular expressions are skipped.
+ */
+function catalogSpans(text: string): Array<readonly [number, number]> {
+  const spans: Array<readonly [number, number]> = []
+  let depth = 0
+  let start = 0
+  let values = 0
+  let prose = 0
+  // Whether the open top-level brace starts an object literal, not a block such as a function body.
+  let literal = false
+  let last = ""
+  let i = 0
+  while (i < text.length) {
+    const c = text.charAt(i)
+    if (c === "/" && text[i + 1] === "/") {
+      const end = text.indexOf("\n", i)
+      i = end === -1 ? text.length : end
+      continue
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2)
+      i = end === -1 ? text.length : end + 2
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`" || (c === "/" && !VALUE_END.test(last))) {
+      let j = i + 1
+      let inClass = false
+      for (; j < text.length; j++) {
+        const d = text[j]
+        if (d === "\\") {
+          j++
+          continue
+        }
+        if (c !== "`" && d === "\n") break
+        if (c !== "/") {
+          if (d === c) break
+          continue
+        }
+        if (d === "[") inClass = true
+        else if (d === "]") inClass = false
+        else if (d === "/" && !inClass) break
+      }
+      // A string after `:` is a property's value.
+      if (depth > 0 && c !== "/" && c !== "`" && last === ":") {
+        values++
+        if (/\s/.test(text.slice(i + 1, j))) prose++
+      }
+      last = c
+      i = j + 1
+      continue
+    }
+    if (c === "{") {
+      if (depth === 0) {
+        start = i
+        values = 0
+        prose = 0
+        const word = /([\w$]+)\s*$/.exec(text.slice(Math.max(0, i - 16), i))?.[1]
+        literal = last === "" || "=(,:[?".includes(last) || word === "default"
+      }
+      depth++
+    } else if (c === "}" && depth > 0 && --depth === 0) {
+      if (literal && values >= CATALOG_VALUES && prose * 2 > values) spans.push([start, i + 1])
+    }
+    if (!/\s/.test(c)) last = c
+    i++
+  }
+  return spans
+}
+
 /** The credential a literal given to `name` carries, when the name is secret-like and the literal
  * looks random. */
 function credentialOf(name: string, value: string): string | undefined {
@@ -304,6 +396,7 @@ function credentialOf(name: string, value: string): string | undefined {
     secret === undefined ||
     PUBLIC_VALUE.test(secret) ||
     PLACEHOLDER.test(secret) ||
+    placeholderSegments(secret) ||
     !looksRandom(secret, 16)
   )
     return undefined
@@ -312,9 +405,16 @@ function credentialOf(name: string, value: string): string | undefined {
 
 function assignedMatches(text: string): Match[] {
   const matches: Match[] = []
+  let catalogs: ReadonlyArray<readonly [number, number]> | undefined
+  /** A label in a message catalog: `password: "Lykilorð"` names the field in another language. */
+  const catalogLabel = (value: string, valueAt: number): boolean => {
+    if (!LABEL.test(value)) return false
+    catalogs ??= catalogSpans(text)
+    return catalogs.some(([start, end]) => valueAt > start && valueAt < end)
+  }
   const add = (name: string, value: string, valueAt: number): void => {
     const secret = credentialOf(name, value)
-    if (secret === undefined) return
+    if (secret === undefined || catalogLabel(value, valueAt)) return
     matches.push({
       rule: "assigned-secret",
       // The credential is the value's tail: a header value's scheme is not part of it.

package/src/internal/typescript-api.ts

@@ -0,0 +1,11 @@
+import type * as TS from "typescript"
+
+/** Whether a loaded `typescript` module carries the in-process compiler API (TypeScript 7's does not). */
+export function isTypeScriptCompiler(value: unknown): value is typeof TS {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "createSourceFile" in value &&
+    typeof value.createSourceFile === "function"
+  )
+}

package/src/internal/vite-plugin-compat.ts

@@ -0,0 +1,81 @@
+// A Vite `config` hook is a plain function or the object form `{ handler, order }` Vite accepts for hook
+// ordering; plugins are typed structurally (no `vite` type dep) and every other field is kept by spread.
+type ConfigFn = (config: unknown, env: unknown) => unknown
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+
+/**
+ * Move a plugin's `optimizeDeps.rollupOptions` to `optimizeDeps.rolldownOptions` under rolldown-vite and
+ * drop its `jsx` key, so Vite 8 warns about neither on `nifra dev` or a Vite build.
+ *
+ * Both are version-skew artifacts of plugins such as `@vitejs/plugin-react@4.x`, which still emit
+ * `optimizeDeps.rollupOptions.jsx`:
+ *
+ * - Vite 8 renamed the dep optimizer's options to `rolldownOptions` and moved jsx under `transform.jsx`,
+ *   so a stale `jsx` key prints `Invalid input options … "jsx" Invalid key`. The route JSX transform runs
+ *   through the plugin's own `transform` hook and pre-bundled deps almost never hold raw JSX, so the key
+ *   is dead and dropping it changes no behavior.
+ * - Vite 8 reads `rollupOptions` there only as a deprecated alias of `rolldownOptions` and warns on every
+ *   resolve, even for `{}`. The remaining keys move to `rolldownOptions`; when the same object already
+ *   sets `rolldownOptions`, Vite ignores the alias, so it is dropped. `ssr.optimizeDeps` gets the same.
+ *
+ * Only a plugin's `config` hook output is rewritten, never mutated, and only under rolldown-vite.
+ * Non-rolldown Vite is passed through verbatim.
+ *
+ * FLATTEN FIRST: a Vite plugin factory may return an ARRAY of plugins - `@vitejs/plugin-react`'s `react()`
+ * returns `[vite:react-babel, vite:react-refresh]`, and it's `react:react-babel`'s `config` hook that emits
+ * the offending `optimizeDeps.rollupOptions.jsx`. `nifra.config.ts` writes `vitePlugins = [react()]`, so the
+ * plugin list arrives NESTED (`[[babel, refresh]]`). Without flattening, `.map` sees the inner array (which
+ * has no `config`), leaves it untouched, and Vite - which flattens plugin arrays itself before running them
+ * - then executes the un-stripped babel hook, so the warning survives. Flattening here (Vite accepts a flat
+ * list identically) is what lets the strip reach every real plugin.
+ */
+export function normalizeRolldownPlugins(
+  plugins: readonly unknown[],
+  isRolldown: boolean,
+): readonly unknown[] {
+  if (!isRolldown) return plugins
+  const migrateDepOptions = (deps: unknown): unknown => {
+    if (!isRecord(deps)) return deps
+    const { rollupOptions, ...rest } = deps
+    if (rollupOptions === undefined) return deps
+    // Vite skips the alias when the same object sets rolldownOptions (mergeConfigRecursively).
+    if (rest.rolldownOptions || rollupOptions === null) return rest
+    if (!isRecord(rollupOptions)) return { ...rest, rolldownOptions: rollupOptions }
+    const { jsx: _dropped, ...kept } = rollupOptions
+    return Object.keys(kept).length === 0 ? rest : { ...rest, rolldownOptions: kept }
+  }
+  const migrateConfig = (returned: unknown): unknown => {
+    if (!isRecord(returned)) return returned
+    const ssr = isRecord(returned.ssr) ? returned.ssr : undefined
+    const deps = migrateDepOptions(returned.optimizeDeps)
+    const ssrDeps = migrateDepOptions(ssr?.optimizeDeps)
+    if (deps === returned.optimizeDeps && ssrDeps === ssr?.optimizeDeps) return returned
+    const out = { ...returned }
+    if (deps !== returned.optimizeDeps) out.optimizeDeps = deps
+    if (ssr !== undefined && ssrDeps !== ssr.optimizeDeps)
+      out.ssr = { ...ssr, optimizeDeps: ssrDeps }
+    return out
+  }
+  return plugins.flat(Number.POSITIVE_INFINITY).map((plugin) => {
+    if (!isRecord(plugin)) return plugin
+    // `config` may be a plain function or the object form `{ handler, order }`. Wrap the handler either way.
+    const hook = plugin.config
+    const objectHook = isRecord(hook) ? hook : undefined
+    const handler = typeof hook === "function" ? hook : objectHook?.handler
+    if (typeof handler !== "function") return plugin
+    const wrappedHandler: ConfigFn = (config, env) => {
+      const returned: unknown = handler(config, env)
+      // The hook may return a promise - normalize both shapes.
+      return returned instanceof Promise ? returned.then(migrateConfig) : migrateConfig(returned)
+    }
+    // Preserve the ORIGINAL shape: a function stays a function; the object form keeps its `order`
+    // (collapsing `{ handler, order }` to a bare function would silently drop the hook ordering).
+    return {
+      ...plugin,
+      config:
+        objectHook === undefined ? wrappedHandler : { ...objectHook, handler: wrappedHandler },
+    }
+  })
+}