@nifrajs/web 5.0.0 → 5.2.0

package/src/build-vite.ts

@@ -39,15 +39,18 @@ import {
 } from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
+import { loadCopySplit } from "./internal/copy-split.ts"
 import { viteDedupePackages } from "./internal/identity-policy.ts"
 import {
   assertDevelopmentProductionParity,
   assertIdentityParity,
   collectDevelopmentParityInput,
 } from "./internal/parity.ts"
+import { emittedScanFiles, formatSecretFindings, scanForSecrets } from "./internal/secret-scan.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { unsupportedBuiltin } from "./internal/target-compat.ts"
 import { importVite, isViteUnresolved } from "./internal/vite-import.ts"
+import { normalizeRolldownPlugins } from "./internal/vite-plugin-compat.ts"
 import { scopedName } from "./plugins/css-modules.ts"
 import { reproduciblePath } from "./plugins/kit.ts"
 import {
@@ -73,6 +76,7 @@ interface ViteManifestEntry {
 type ViteBuildManifest = Readonly<Record<string, ViteManifestEntry>>
 
 interface ViteModule {
+  readonly rolldownVersion?: string
   build(config: Record<string, unknown>): Promise<unknown>
   loadEnv(mode: string, envDir: string, prefixes: string): Record<string, string>
 }
@@ -166,13 +170,21 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
   mkdirSync(outDir, { recursive: true })
 
   const routeManifest = discoverRoutes(routesDir)
+  const copySplit =
+    (options.copySplit ?? options.minify !== false)
+      ? await loadCopySplit(root, { skip: [outDir] })
+      : undefined
   // The generated bootstrap, written beside the project so its imports resolve the app's deps (same
   // reasoning as buildClient). A unique dir avoids clobbering a user file / colliding with parallel builds.
   const entryDir = mkdtempSync(resolvePath(dirname(routesDir), ".nifra-vite-client-"))
   const entryFile = `${entryDir}/_nifra-entry.ts`
   writeFileSync(
     entryFile,
-    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, { clientModule, resolve })}`,
+    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, {
+      clientModule,
+      resolve,
+      copyChunks: copySplit !== undefined,
+    })}`,
   )
 
   // Every unique route/layout/_404 file - each an additional entry so Vite emits a named chunk per file
@@ -274,7 +286,28 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
         },
         // First, so a bare built-in is named before Vite turns it into an anonymous stub.
         // The asset URL guard last, so it reads each module after any framework plugin made it JavaScript.
-        plugins: [viteBareBuiltinExternal(), ...(options.vitePlugins ?? []), assetUrlGuard],
+        plugins: [
+          viteBareBuiltinExternal(),
+          ...(copySplit === undefined
+            ? []
+            : [
+                {
+                  name: "nifra-copy-split",
+                  // Before a framework plugin compiles the module: the tables are read from its source.
+                  enforce: "pre" as const,
+                  transform(code: string, id: string) {
+                    const out = copySplit.rewrite(id, code)
+                    // Lines do not move, so the module's map stays the source's.
+                    return out === undefined ? undefined : { code: out, map: null }
+                  },
+                },
+              ]),
+          ...normalizeRolldownPlugins(
+            options.vitePlugins ?? [],
+            vite.rolldownVersion !== undefined,
+          ),
+          assetUrlGuard,
+        ],
         worker: {
           plugins: () => {
             const guard = viteLeakGuard(guardOptions)
@@ -416,6 +449,23 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     for (const asset of entry.assets ?? []) assets.add(url(asset))
   }
 
+  // The leak guard scanned the bundle; the copy it no longer holds is scanned here.
+  const copy = copySplit?.chunks(publicPath)
+  if (copy !== undefined && copy.files.length > 0) {
+    const secrets = formatSecretFindings(
+      scanForSecrets({
+        artifacts: copy.files.flatMap((file) => emittedScanFiles(file.name, file.text)),
+        env: guardOptions.secrets.env,
+        publicEnvPrefix: options.publicEnvPrefix ?? "PUBLIC_",
+        exemptions: exemptions ?? [],
+      }),
+    )
+    if (secrets !== undefined) throw new Error(secrets)
+    for (const file of copy.files) writeFileSync(join(outDir, file.name), file.text)
+  }
+  const copyChunks = copy?.urls ?? {}
+  for (const chunk of Object.values(copyChunks)) assets.add(chunk)
+
   const publicFiles =
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
 
@@ -428,6 +478,7 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
+    ...(Object.keys(copyChunks).length > 0 ? { copyChunks } : {}),
   }
   assertDevelopmentProductionParity(collectDevelopmentParityInput(routesDir, publicDir), manifest)
   writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2))
@@ -442,6 +493,7 @@ export interface BuildServerViteOptions {
   readonly clientEntry: string
   readonly styles?: readonly string[] | undefined
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  readonly copyChunks?: Readonly<Record<string, string>> | undefined
   /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
   readonly cssLoading?: CssLoadingMode
   readonly resolve?: (file: string) => string
@@ -563,6 +615,7 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
       styles,
       routeStyles,
       ...(cssLoading !== undefined ? { cssLoading } : {}),
+      ...(options.copyChunks !== undefined ? { copyChunks: options.copyChunks } : {}),
     }),
   )
 
@@ -599,7 +652,10 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
           dedupe: ["react", "react-dom", ...singleCopyPackageNames(root)],
           conditions: [...conditions],
         },
-        plugins: [...(options.vitePlugins ?? [])],
+        plugins: normalizeRolldownPlugins(
+          options.vitePlugins ?? [],
+          vite.rolldownVersion !== undefined,
+        ),
         build: {
           outDir,
           emptyOutDir: false,
@@ -675,6 +731,7 @@ export const viteBundler: Bundler = {
       target: input.target,
       ...(input.styles !== undefined ? { styles: input.styles } : {}),
       ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
+      ...(input.copyChunks !== undefined ? { copyChunks: input.copyChunks } : {}),
       ...(input.plugins ? { vitePlugins: input.plugins } : {}),
       ...(input.define ? { define: input.define } : {}),
       ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),

package/src/build.ts

@@ -39,6 +39,7 @@ import {
   formatServerOnlyLeak,
   parseBuildTarget,
   parseManifestClientEntry,
+  parseManifestCopyChunks,
   parseManifestCssLoading,
   parseManifestRouteStyles,
   parseManifestStyles,
@@ -50,6 +51,7 @@ 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 { loadCopySplit } from "./internal/copy-split.ts"
 import { assertDisposableDir } from "./internal/disposable-dir.ts"
 import { entryChunks } from "./internal/entry-chunks.ts"
 import { dedupePolicyFor } from "./internal/identity-policy.ts"
@@ -89,6 +91,7 @@ import {
   verifyServerGraph,
 } from "./internal/zone-graph.ts"
 import { type ClientModuleGraph, fromBunMetafile } from "./module-graph.ts"
+import { assertNoImportGlob, importGlobPlugin } from "./plugins/import-glob.ts"
 import { zoneGuardPlugin } from "./plugins/zone-guard.ts"
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
 import { prerenderRoutes } from "./prerender.ts"
@@ -186,6 +189,12 @@ export interface BuildClientOptions {
    * variable. Each names its rule, its file (or, for an environment value, its variable) and a reason.
    */
   readonly secretExemptions?: readonly SecretExemption[]
+  /**
+   * Move copy tables (`@nifrajs/i18n/copy`) into one chunk per locale, so a page's JavaScript carries
+   * only the copy of the locale it renders in (default: on when minifying). The server bundle keeps
+   * every table whole; the server entry passes the manifest's `copyChunks` to `createWebApp`.
+   */
+  readonly copySplit?: boolean
 }
 
 /**
@@ -374,12 +383,14 @@ export function resyncServerManifestSource(
   routesPrefix: string,
 ): string {
   const cssLoading = parseManifestCssLoading(source)
+  const copyChunks = parseManifestCopyChunks(source)
   return generateServerManifest(manifest, {
     resolve: (file) => `${routesPrefix}${file}`,
     clientEntry: parseManifestClientEntry(source) ?? "",
     styles: parseManifestStyles(source),
     routeStyles: parseManifestRouteStyles(source),
     ...(cssLoading !== undefined ? { cssLoading } : {}),
+    ...(copyChunks !== undefined ? { copyChunks } : {}),
     lazy: MANIFEST_IS_LAZY.test(source),
   })
 }
@@ -426,6 +437,10 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // The bootstrap's filename is `_nifra`-namespaced (not `entry.ts`) so its `[name]` can't collide with
   // a user route named `entry.tsx` when the CSS mapping below excludes the bootstrap's aggregate CSS.
   const mode = options.minify === false ? "development" : "production"
+  const copySplit =
+    (options.copySplit ?? mode === "production")
+      ? await loadCopySplit(root, { skip: [outDir] })
+      : undefined
   // PUBLIC_*-prefixed env → client define (Vite/Next convention). Sourced from the build env (`Bun.env`,
   // falling back to `process.env`). Only prefixed vars are baked in; unprefixed secrets stay undefined
   // in the client via the bare `process.env` → `({})` define below. Caller's `options.define` wins (it's
@@ -442,7 +457,11 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // an app module doesn't crash hydration (`process.env.*` reads are handled at compile time by `define`).
   writeFileSync(
     entryFile,
-    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, { clientModule, resolve })}`,
+    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, {
+      clientModule,
+      resolve,
+      copyChunks: copySplit !== undefined,
+    })}`,
   )
 
   // Every unique route/layout/`_404` file (sorted, stable), as ADDITIONAL entrypoints - Bun emits a
@@ -496,6 +515,10 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
           svelteDedupePlugin(routesDir),
           serverFnStubPlugin(),
           ...(options.plugins ?? []),
+          // Before the copy split: it claims a module that calls the glob and reads it through the split.
+          importGlobPlugin({ root }),
+          // Last: it rewrites a module no other plugin claims, and the ones that do read through it.
+          ...(copySplit === undefined ? [] : [copySplit.plugin]),
         ],
         ...(options.conditions ? { conditions: [...options.conditions] } : {}),
         // Replace `process.env.*` at compile time so an app module reading config off `process.env` doesn't
@@ -550,6 +573,11 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
       return { name: out.path, kind: "code", text: await out.text() }
     }),
   )
+  assertNoImportGlob(
+    emitted.flatMap((file) =>
+      file.kind === "code" ? [[relative(cwd, file.name), file.text ?? ""] as const] : [],
+    ),
+  )
   const clientGraph = withEmittedImports(fromBunMetafile(clientMeta), emitted, publicPath)
   const verdict = verifyClientGraph(clientGraph, {
     classifier,
@@ -596,6 +624,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   if (unaccounted !== undefined) throw new Error(unaccounted)
 
   const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
+  const copy = copySplit?.chunks(publicPath)
   const { sources, originsOf } = graphScanInput(clientGraph, bunModuleSource(cwd), classifier)
   const secrets = formatSecretFindings(
     scanForSecrets({
@@ -606,6 +635,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
           const name = file.name.replace(/^\.\//, "")
           return emittedScanFiles(name, file.text, originsOf(name))
         }),
+        ...(copy?.files ?? []).flatMap((file) => emittedScanFiles(file.name, file.text)),
         ...(publicDir !== undefined && existsSync(publicDir)
           ? publicScanFiles(publicDir, originName(root, resolvePath(publicDir)))
           : []),
@@ -624,6 +654,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
       return { kind: out.kind, path }
     }),
   )
+  for (const file of copy?.files ?? []) writeFileSync(join(outDir, file.name), file.text)
 
   // Rename any chunk whose basename isn't URL-safe (dynamic-route files become `[slug]-hash.js`) and
   // rewrite the references - otherwise the lazy import 404s and the route silently never hydrates.
@@ -750,13 +781,15 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   const publicFiles =
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
 
+  const copyChunks = copy?.urls ?? {}
   const manifest: BuildManifest = {
     entry: entryUrl,
-    assets: outputs.map((o) => toUrl(o.path)),
+    assets: [...outputs.map((o) => toUrl(o.path)), ...Object.values(copyChunks)],
     routes,
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
+    ...(Object.keys(copyChunks).length > 0 ? { copyChunks } : {}),
   }
   assertDevelopmentProductionParity(collectDevelopmentParityInput(routesDir, publicDir), manifest)
   writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2))
@@ -780,6 +813,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
+  /** Copy chunk URLs by locale (`buildClient`'s `BuildManifest.copyChunks`) - baked as `copyChunks`. */
+  readonly copyChunks?: Readonly<Record<string, 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
@@ -1051,6 +1086,7 @@ function formatRefusedFiles(refused: ReadonlyMap<string, string>, root: string):
   return `[nifra/web] the browser build reached code that may not ship to a browser:\n${lines.join("\n")}`
 }
 
+export { importGlobPlugin } from "./plugins/import-glob.ts"
 export { zoneGuardPlugin } from "./plugins/zone-guard.ts"
 
 /**
@@ -1130,6 +1166,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       styles,
       routeStyles,
       ...(cssLoading !== undefined ? { cssLoading } : {}),
+      ...(options.copyChunks !== undefined ? { copyChunks: options.copyChunks } : {}),
       lazy,
     }),
   )
@@ -1161,6 +1198,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       reactDedupePlugin(entryDir),
       preactDedupePlugin(entryDir),
       ...(options.plugins ?? []),
+      importGlobPlugin({ root: resolvePath(options.root ?? dirname(routesDir)) }),
     ],
   })
   if (!result.success) {
@@ -1227,7 +1265,14 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
 // ===================================================================================================
 
 /** The `createWebApp` options a generated server entry can import from the app's framework module. */
-export const SERVER_ENTRY_OPTIONS = ["apiPrefix", "apiStrip", "mounts", "csp", "nonce"] as const
+export const SERVER_ENTRY_OPTIONS = [
+  "apiPrefix",
+  "apiStrip",
+  "mounts",
+  "csp",
+  "nonce",
+  "i18n",
+] as const
 export type ServerEntryOption = (typeof SERVER_ENTRY_OPTIONS)[number]
 /** Each importable option mapped to the specifier of the module that exports it. */
 export type ServerEntryOptionImports = Readonly<Partial<Record<ServerEntryOption, string>>>
@@ -1285,6 +1330,8 @@ export function generateServerEntry(options: {
   readonly hashedFiles?: readonly string[]
   /** Trust the edge platform's client-address header for `c.clientIp`. See {@link ServerEntryClientIp}. */
   readonly clientIp?: ServerEntryClientIp
+  /** The server manifest exports `copyChunks` (the client build split copy tables by locale). */
+  readonly copyChunks?: boolean
 }): string {
   const {
     target,
@@ -1327,7 +1374,9 @@ export function generateServerEntry(options: {
     lines.push(`import { backend } from ${JSON.stringify(backendImport)}`)
   }
   lines.push(
-    'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
+    options.copyChunks === true
+      ? 'import { clientEntry, copyChunks, cssLoading, manifest, styles, routeStyles } from "./server-manifest"'
+      : 'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
   )
   // Cloudflare needs the fetch-handler shape; the others call app.fetch directly.
   if (target === "cloudflare") lines.push('import { toFetchHandler } from "@nifrajs/core/server"')
@@ -1343,6 +1392,7 @@ export function generateServerEntry(options: {
     "  styles,",
     "  routeStyles,",
     "  cssLoading,",
+    ...(options.copyChunks === true ? ["  copyChunks,"] : []),
     ...(backendImport !== undefined ? ["  api: inProcessClient(backend),"] : []),
     `  title: ${JSON.stringify(title)},`,
     // Core's own `{ header }` trust, so the mounted backend and every loader see the derived caller.
@@ -1630,6 +1680,7 @@ export const bunBundler: Bundler = {
       target: input.target,
       ...(input.styles !== undefined ? { styles: input.styles } : {}),
       ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
+      ...(input.copyChunks !== undefined ? { copyChunks: input.copyChunks } : {}),
       ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
       ...(input.define ? { define: input.define } : {}),
       ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
@@ -1813,6 +1864,7 @@ export async function buildTargetWith(
       ...(publicFiles.length > 0 ? { publicFiles } : {}),
       hashedFiles: client.assets,
       ...(options.clientIp !== undefined ? { clientIp: options.clientIp } : {}),
+      ...(client.copyChunks !== undefined ? { copyChunks: true } : {}),
     }),
   )
   const { worker } = await bundler.buildServer({
@@ -1823,6 +1875,7 @@ export async function buildTargetWith(
     target: targetPlan.serverTarget,
     ...(client.css !== undefined ? { styles: client.css } : {}),
     ...(client.routeStyles !== undefined ? { routeStyles: client.routeStyles } : {}),
+    ...(client.copyChunks !== undefined ? { copyChunks: client.copyChunks } : {}),
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
     ...(client.cssLoading !== undefined

package/src/client.ts

@@ -5,6 +5,7 @@
  * a full page load). DOM-only - never imported on the server, so the store stays SSR-safe.
  */
 import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+import { appUrl } from "./internal/route-path.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import type { Meta } from "./manifest.ts"
 import {
@@ -18,6 +19,7 @@ import {
   setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
+import { handoverLocale } from "./render-seam.ts"
 import { type ClientRouter, redirectOf } from "./router.ts"
 
 /** Read the nonce carried by the current server-rendered document, if any. */
@@ -48,6 +50,7 @@ export {
   resolveNavigate,
 } from "./navigation.ts"
 export { createMutation, createQueryClient } from "./query.ts"
+export { localeOfProps } from "./render-seam.ts"
 export { createClientRouter, createMatcher } from "./router.ts"
 // Same reason, for the ADAPTER packages (`@nifrajs/web-react` and friends). Every one of them reaches
 // for these from the root - `searchOfChain` in its `/client` entry, the navigation and query values in
@@ -232,7 +235,7 @@ export function installHistory(
   router: ClientRouter,
   options: InstallHistoryOptions = {},
 ): () => void {
-  const fallback = options.fallback ?? ((path: string) => location.assign(path))
+  const fallback = options.fallback ?? ((path: string) => location.assign(appUrl(path)))
 
   // We manage scroll ourselves (save per history entry, restore after the navigated content
   // renders), so disable the browser's native restoration which would otherwise fight us.
@@ -364,7 +367,7 @@ export function installHistory(
     if (mode === "replace") {
       // Replace the current entry (same index) with the new URL. The entry we're leaving is discarded, so
       // its scroll isn't worth saving; the new route scrolls to its fragment target, else the top.
-      history.replaceState(entryState, "", path)
+      history.replaceState(entryState, "", appUrl(path))
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     } else {
       // Save the leaving entry's scroll (spread keeps its nifraIndex), push a fresh higher-indexed entry
@@ -372,7 +375,7 @@ export function installHistory(
       history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
       index += 1
       entryState.nifraIndex = index
-      history.pushState(entryState, "", path)
+      history.pushState(entryState, "", appUrl(path))
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     }
     here = url.pathname + url.search + url.hash
@@ -555,9 +558,9 @@ export function installHistory(
       if (expected === undefined) {
         history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
         index += 1
-        history.pushState({ nifraIndex: index }, "", path)
+        history.pushState({ nifraIndex: index }, "", appUrl(path))
       } else {
-        history.replaceState(history.state, "", path + location.hash)
+        history.replaceState(history.state, "", appUrl(path) + location.hash)
       }
       here = location.pathname + location.search + location.hash
       pendingScroll = location.hash !== "" ? { hash: hashId(location.hash) } : { pos: [0, 0] }
@@ -610,28 +613,29 @@ export function installHistory(
   }
 }
 
-/**
- * Intercept submissions of same-origin `<form method="post">` whose action targets an app route:
- * submit via the router (no full reload - POST the action, then revalidate the active loader). On
- * failure it falls back to a native submit, so the form still works. Returns a teardown function.
- */
 /**
  * Sync the document head to a route's resolved {@link Meta} on client navigation. Sets the title
  * (when provided) and replaces the **managed** (`data-nifra`) `<meta>`/`<link>` tags - static head
  * content (charset, hand-written tags) is never touched. SSR injects the same `data-nifra` tags, so
  * the first navigation cleanly takes over from the server-rendered head.
  */
-export function applyHead(head: Meta): void {
+export function applyHead(head: Meta, path?: string): void {
   const documentNonce = currentDocumentNonce()
   if (head.title !== undefined) document.title = head.title
   // `<html lang>`/`<html dir>` - applied AUTHORITATIVELY (unlike `title`, which is left alone when the
-  // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
-  // removed when unset. Anything laxer drifts on a multilingual site - navigating /ur → /en would leave
-  // `dir="rtl"` behind and lay the English page out right-to-left, a bug a hard reload would not show.
+  // route omits it), mirroring the SSR shell's defaulting exactly: a meta `lang` wins, then the page's
+  // registered locale, then `"en"`; `dir` is removed when unset. Anything laxer drifts on a
+  // multilingual site - navigating /ur → /en would leave `dir="rtl"` behind and lay the English page
+  // out right-to-left, a bug a hard reload would not show.
+  const locale =
+    head.lang === undefined
+      ? handoverLocale(path ?? (typeof location === "undefined" ? "" : location.pathname))
+      : undefined
+  const dir = head.dir ?? locale?.dir
   const root = document.documentElement
-  root.setAttribute("lang", head.lang ?? "en")
-  if (head.dir === undefined) root.removeAttribute("dir")
-  else root.setAttribute("dir", head.dir)
+  root.setAttribute("lang", head.lang ?? locale?.lang ?? "en")
+  if (dir === undefined) root.removeAttribute("dir")
+  else root.setAttribute("dir", dir)
   for (const el of document.head.querySelectorAll("[data-nifra]")) el.remove()
   // Values follow the same HTML attribute conventions as the SSR `tagAttrs`: a string sets the value,
   // `true` sets the bare boolean attribute, `false`/`undefined` skip it - so a soft-nav head matches
@@ -689,6 +693,17 @@ export function applyHead(head: Meta): void {
   }
 }
 
+// A control named like a form property shadows it (`<input name="target">` makes `form.target` that
+// input), so the form's own state is read through the prototype accessors.
+function formProperty(form: HTMLFormElement, name: "action" | "method" | "target"): string {
+  return String(Reflect.get(HTMLFormElement.prototype, name, form))
+}
+
+/**
+ * Intercept submissions of same-origin `<form method="post">` whose action targets an app route:
+ * submit via the router (no full reload - POST the action, then revalidate the active loader). On
+ * failure it falls back to a native submit, so the form still works. Returns a teardown function.
+ */
 export function installForms(router: ClientRouter): () => void {
   // Forms whose data submit failed before the server answered: their next submit event is the native
   // post that replaces it.
@@ -702,20 +717,25 @@ export function installForms(router: ClientRouter): () => void {
     // name=value is part of the submission (`<button name="intent" value="delete">`).
     // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a submit event's submitter is the submit button or input that fired it, or null
     const submitter = event.submitter as HTMLButtonElement | null
-    const method = submitter?.hasAttribute("formmethod") ? submitter.formMethod : form.method
+    const method = submitter?.hasAttribute("formmethod")
+      ? submitter.formMethod
+      : formProperty(form, "method")
     if (method.toLowerCase() !== "post") return // GET forms submit natively
-    const target = submitter?.hasAttribute("formtarget") ? submitter.formTarget : form.target
+    const target = submitter?.hasAttribute("formtarget")
+      ? submitter.formTarget
+      : formProperty(form, "target")
     if (target !== "" && target !== "_self") return // it loads in another browsing context
     // Resolved (or the current document URL if unset).
     const url = sameDocumentUrl(
-      submitter?.hasAttribute("formaction") ? submitter.formAction : form.action,
+      submitter?.hasAttribute("formaction") ? submitter.formAction : formProperty(form, "action"),
     )
     if (url === null) return
     if (router.match(url.pathname) === null) return // not an app route → native submit
     event.preventDefault()
     // `data-nifra-revalidate="false"` opts out of the post-action loader revalidation (the action's
     // actionData drives the update); absent or any other value keeps the default revalidation.
-    const revalidate = form.dataset.nifraRevalidate !== "false"
+    const revalidate =
+      Element.prototype.getAttribute.call(form, "data-nifra-revalidate") !== "false"
     const body = new FormData(form, submitter)
     router.submit(url.pathname + url.search, body, { revalidate }).catch((error) => {
       const to = redirectOf(error)
@@ -724,7 +744,7 @@ export function installForms(router: ClientRouter): () => void {
       else {
         // Nothing reached the server - post natively, through the same button.
         native.add(form)
-        form.requestSubmit(submitter)
+        HTMLFormElement.prototype.requestSubmit.call(form, submitter)
       }
     })
   }

package/src/dev-port.ts

@@ -38,13 +38,14 @@ export const explainBindFailure = (err: unknown, port: number): Error =>
 
 /** The bits of a Node server {@link listenOrExplain} touches - structural, so a test can fake it. */
 export interface ListenTarget {
-  listen(port: number, cb: () => void): void
+  listen(port: number, hostname: string, cb: () => void): void
   once(event: "error", cb: (err: unknown) => void): void
   removeListener(event: "error", cb: (err: unknown) => void): void
 }
 
 /**
  * `listen`, but a bind failure becomes a readable nifra error instead of Node's raw internal throw.
+ * The hostname is required: omitting it binds every interface, and a dev server is local-only.
  *
  * Without an `error` listener attached, Node throws from deep inside `node:events`, the new process dies
  * in the background, and nothing connects that death to the stale page in front of you.
@@ -52,7 +53,7 @@ export interface ListenTarget {
 export function listenOrExplain(
   server: ListenTarget,
   port: number,
-  hostname?: string,
+  hostname: string,
 ): Promise<void> {
   return new Promise<void>((resolve, reject) => {
     const onError = (err: unknown): void => reject(explainBindFailure(err, port))
@@ -63,13 +64,6 @@ export function listenOrExplain(
       server.removeListener("error", onError)
       resolve()
     }
-    if (hostname === undefined) server.listen(port, onListening)
-    else {
-      ;(
-        server as ListenTarget & {
-          listen(port: number, hostname: string, cb: () => void): void
-        }
-      ).listen(port, hostname, onListening)
-    }
+    server.listen(port, hostname, onListening)
   })
 }

package/src/index.ts

@@ -88,12 +88,8 @@ export {
 // `import { createClientRouter, createMatcher, mergeHeads, resolveChainMeta } from "@nifrajs/web/client"`.
 export { mergeHeads, resolveChainMeta, resolveMeta } from "./internal/head-merge.ts"
 export {
-  canonical,
   gone,
-  jsonLd,
   notFound,
-  type OpenGraphInput,
-  openGraph,
   type RedirectOptions,
   type RenderAssemblyCache,
   type RenderedPage,
@@ -125,6 +121,7 @@ export {
   type CreateWebAppOptions,
   createWebApp,
   type NonceResolver,
+  type WebAppI18n,
   webProjectEvidence,
 } from "./internal/web-app.ts"
 // ISR (incremental static regeneration): a pluggable cache store + the `withISR` stale-while-revalidate
@@ -257,9 +254,15 @@ export {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
   DATA_GLOBAL,
+  type DocumentParts,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LOCALES_GLOBAL,
+  localeOfProps,
   type MatchChain,
+  type PageLocale,
+  type PageLocales,
+  pageLocaleIn,
   type RenderAdapter,
   type RenderProps,
   type RenderStreamOptions,
@@ -298,6 +301,7 @@ export {
 // ctx + `renderPage`) and a client adapter mount call this with the same URL + schema, so the two sides
 // produce the identical value by construction. An adapter's `useSearch` binding reads its result.
 export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.ts"
+export { canonical, jsonLd, type OpenGraphInput, openGraph } from "./seo.ts"
 export {
   type HtmlSanitizer,
   type SanitizedHtml,