@nifrajs/web 5.1.0 → 5.2.0

package/src/internal/render-document.ts

@@ -11,13 +11,23 @@ import type {
   RouteModule,
   UnsafeScriptDescriptor,
 } from "../manifest.ts"
-import type { DocumentParts, 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"
@@ -111,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
@@ -184,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
@@ -248,6 +267,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     cssLoading: requestedCssLoading,
     prerenderedPaths = [],
     prerenderedListUrl,
+    copyChunks,
+    locale,
     revalidate,
     revalidateTags = [],
     routeId,
@@ -276,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
@@ -405,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
@@ -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,13 +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}${slot.rootOpen}`
+  // 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}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
+      : `${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>"
@@ -457,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.
@@ -501,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
@@ -1171,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/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 },
+    }
+  })
+}

package/src/internal/web-app.ts

@@ -21,10 +21,54 @@ import type { RenderAdapter } from "../render-seam.ts"
 import { createMatcher, PRERENDERED_LIST_PATH } from "../router.ts"
 import type { EvidenceAncestry } from "./evidence-traversal.ts"
 import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
-import { createPageRequestExecutor, type NonceResolver } from "./page-execution.ts"
+import { createPageRequestExecutor, type NonceResolver, type PageI18n } from "./page-execution.ts"
 import { requestPattern } from "./route-path.ts"
 
 export type { NonceResolver } from "./page-execution.ts"
+
+/** An app's locale routing as `createWebApp` reads it: what `defineI18nRouting()` from
+ * `@nifrajs/i18n/routing` returns. */
+export interface WebAppI18n {
+  readonly locales: {
+    readonly default: string
+    /** Served locale keys, in registry order. */
+    readonly served: readonly string[]
+    documentMeta(key: string): { readonly lang: string; readonly dir: "ltr" | "rtl" }
+  }
+  localeOf(path: string): string
+  matchSegment(
+    value: string | undefined,
+    pathname: string,
+  ):
+    | { readonly kind: "ok" | "not-found" }
+    | { readonly kind: "redirect"; readonly location: string }
+}
+
+function pageI18n(routing: WebAppI18n): PageI18n {
+  const { locales } = routing
+  if (
+    typeof routing.localeOf !== "function" ||
+    typeof routing.matchSegment !== "function" ||
+    typeof locales?.documentMeta !== "function" ||
+    !Array.isArray(locales.served)
+  ) {
+    throw new TypeError(
+      "[nifra/web] createWebApp `i18n` must be the router defineI18nRouting() from @nifrajs/i18n/routing returns",
+    )
+  }
+  return {
+    locales: {
+      default: locales.default,
+      locales: locales.served.map((key) => {
+        const { lang, dir } = locales.documentMeta(key)
+        return { key, lang, dir }
+      }),
+    },
+    localeOf: (path) => routing.localeOf(path),
+    matchSegment: (value, pathname) => routing.matchSegment(value, pathname),
+  }
+}
+
 export interface CreateWebAppOptions<Env = unknown> {
   readonly serverComponents?: import("../server-components/types.ts").ServerComponentRuntime
   readonly adapter: RenderAdapter
@@ -181,6 +225,20 @@ export interface CreateWebAppOptions<Env = unknown> {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+  /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`, the server manifest's
+   * `copyChunks`). A production client build moves copy tables (`@nifrajs/i18n/copy`) into one chunk per
+   * locale; each page lists them for the browser and preloads its own. Omit ⇒ tables keep their values. */
+  readonly copyChunks?: Readonly<Record<string, string>>
+  /**
+   * The app's locale routing, `defineI18nRouting()` from `@nifrajs/i18n/routing`, registered once:
+   * export it as `i18n` from `backend/framework.ts`. Every document then takes its locale from the
+   * URL: `<html lang dir>` from the registry unless the route's meta sets `lang`, a `Content-Language`
+   * header, and the locale each adapter's `useLocale()` and `<I18nProvider>` read. A route under a
+   * `[lang]` or `[[lang]]` directory is checked with its `matchSegment()` before any middleware: an
+   * unserved locale, or a page missing from it, is a 404, and a non-canonical prefix (`/en/x` when the
+   * default is unprefixed) redirects with a 308.
+   */
+  readonly i18n?: WebAppI18n
   /**
    * Activation policy for framework-owned stylesheet links (default `"blocking"`). `"deferred"`
    * emits `media="print"` links; the generated client waits for them and switches them to `all` before
@@ -442,6 +500,8 @@ export function createWebApp<Env = unknown>(
     ...(options.routePreload === undefined ? {} : { routePreload: options.routePreload }),
     ...(options.styles === undefined ? {} : { styles: options.styles }),
     ...(options.routeStyles === undefined ? {} : { routeStyles: options.routeStyles }),
+    ...(options.copyChunks === undefined ? {} : { copyChunks: options.copyChunks }),
+    ...(options.i18n === undefined ? {} : { i18n: pageI18n(options.i18n) }),
     ...(options.cssLoading === undefined ? {} : { cssLoading: options.cssLoading }),
     ...(options.prerenderedPaths === undefined
       ? {}