@nifrajs/web 5.0.0 → 5.2.0

package/src/plugins/kit.ts

@@ -122,6 +122,42 @@ export function hash8(input: string): string {
   return h.toString(16).padStart(8, "0")
 }
 
+const SOURCE_TRANSFORMS = Symbol.for("nifra.build.source-transforms")
+
+/** A rewrite of a source file's text before any plugin compiles it; `undefined` leaves the text as is. */
+export type SourceTransform = (path: string, source: string) => string | undefined
+
+const isTransformList = (value: unknown): value is SourceTransform[] => Array.isArray(value)
+
+/**
+ * Register a source rewrite for one build. Bun runs only the first `onLoad` that returns contents, so
+ * a plugin that claims a file and reads it off disk would compile it without the rewrite: such a plugin
+ * reads through {@link readSource} instead. Stored on the build's config, which every plugin of one
+ * `Bun.build` shares.
+ */
+export function addSourceTransform(build: PluginBuilder, transform: SourceTransform): void {
+  const config: unknown = build.config
+  if (typeof config !== "object" || config === null) return
+  const existing: unknown = Reflect.get(config, SOURCE_TRANSFORMS)
+  if (isTransformList(existing)) existing.push(transform)
+  else Reflect.set(config, SOURCE_TRANSFORMS, [transform])
+}
+
+/** A source file's text as this build compiles it: off disk, through each {@link addSourceTransform}. */
+export async function readSource(build: PluginBuilder, path: string): Promise<string> {
+  let source = await Bun.file(path).text()
+  // A runtime plugin (`Bun.plugin`) has no build config.
+  const config: unknown = build.config
+  const transforms: unknown =
+    typeof config === "object" && config !== null
+      ? Reflect.get(config, SOURCE_TRANSFORMS)
+      : undefined
+  if (isTransformList(transforms)) {
+    for (const transform of transforms) source = transform(path, source) ?? source
+  }
+  return source
+}
+
 /**
  * Env flag a nifra dev server sets for its own lifetime, so a framework compiler plugin can tell a dev
  * compile from a `nifra build` one. Exported for the dev server that sets it; plugins ask

package/src/plugins/stylex.ts

@@ -11,6 +11,7 @@ import {
   devServerCompile,
   hash8,
   normalizeFilePath,
+  readSource,
   reproduciblePath,
   requirePeer,
 } from "./kit.ts"
@@ -236,7 +237,7 @@ export function stylexBunPlugin(
       const dependencies = dependenciesFor(options)
       build.onLoad({ filter: JS_FILTER }, async (args) => {
         const path = normalizeFilePath(args.path)
-        const source = await Bun.file(path).text()
+        const source = await readSource(build, path)
         const transformed = await transformModule(source, path, options, dependencies())
         if (transformed === undefined) return
         const contents =

package/src/plugins/vite-leak-guard.ts

@@ -46,6 +46,7 @@ import {
   formatServerOnlyLeak,
 } from "../build-plan.ts"
 import { isBareNodeBuiltin } from "../internal/node-builtins.ts"
+import { installedManifest } from "../internal/package-entries.ts"
 import { privateEnvCheck } from "../internal/private-env.ts"
 import {
   emittedScanFiles,
@@ -58,6 +59,7 @@ import {
   scanForSecrets,
   textOf,
 } from "../internal/secret-scan.ts"
+import { withoutQuery } from "../internal/without-query.ts"
 import {
   accountEmittedFiles,
   assetDenial,
@@ -75,7 +77,7 @@ import {
   type GraphModule,
   type RollupBundleLike,
 } from "../module-graph.ts"
-import { createZoneClassifier, type ZoneClassifier } from "../zones.ts"
+import { createZoneClassifier, specifierPackage, type ZoneClassifier } from "../zones.ts"
 
 /**
  * The Rollup plugin-context slice this uses: `getModuleInfo` for a module's resolved imports, and `error`
@@ -160,9 +162,80 @@ export interface LeakGuardPlugin {
    * reached the browser.
    */
   leak?: string
+  buildStart(): void
+  /** Ordered first: the bundler's own resolver answers before a plugin listed after it is asked. */
+  readonly resolveId: {
+    readonly order: "pre"
+    handler(
+      this: ResolveContext,
+      source: string,
+      importer: string | undefined,
+      options?: Readonly<Record<string, unknown>>,
+    ): Promise<null>
+  }
   generateBundle(this: RollupPluginContext, options: unknown, bundle: RollupBundleLike): void
 }
 
+/**
+ * Rollup keeps no import's written specifier, yet a package that gives each entry its own side is judged
+ * by the entry an import names, since two entries may share one file. This records the specifier of
+ * each import of such a package by the edge it resolved to, and puts it back on the finished graph.
+ */
+function entrySpecifiers(appRoot: string, options: ServerZoneGuardOptions) {
+  // One edge may carry several specifiers: `pkg` and `pkg/react` can resolve to one shared file.
+  const written = new Map<string, Set<string>>()
+  let classifier: ZoneClassifier | undefined
+  const edge = (from: string, to: string): string =>
+    `${from.replaceAll("\\", "/")}\0${to.replaceAll("\\", "/")}`
+  return {
+    reset(): void {
+      written.clear()
+      classifier = undefined
+    },
+    async resolveId(
+      context: ResolveContext,
+      source: string,
+      importer: string | undefined,
+      resolveOptions: Readonly<Record<string, unknown>> | undefined,
+    ): Promise<null> {
+      const name = specifierPackage(source)
+      const from = importer === undefined ? undefined : withoutQuery(importer)
+      if (name === undefined || importer === undefined || from === undefined || !isAbsolute(from))
+        return null
+      const manifest = installedManifest(dirname(from), name)
+      if (manifest === undefined) return null
+      classifier ??= classifierFor(appRoot, options)
+      if (classifier.classify(manifest, source).entry === undefined) return null
+      const resolved = await context.resolve(source, importer, {
+        ...resolveOptions,
+        skipSelf: true,
+      })
+      if (resolved === null) return null
+      const key = edge(importer, resolved.id)
+      written.set(key, (written.get(key) ?? new Set<string>()).add(source))
+      return null
+    },
+    annotate(graph: ClientModuleGraph): ClientModuleGraph {
+      if (written.size === 0) return graph
+      const modules: Record<string, GraphModule> = {}
+      for (const [id, module] of Object.entries(graph.modules)) {
+        modules[id] = {
+          imports: module.imports.flatMap((im) => {
+            const originals =
+              im.original !== undefined || im.path === undefined
+                ? undefined
+                : written.get(edge(id, im.path))
+            return originals === undefined
+              ? [im]
+              : [...originals].map((original) => ({ ...im, original }))
+          }),
+        }
+      }
+      return { ...graph, modules }
+    },
+  }
+}
+
 const CSS_FILE = /\.(?:css|scss|sass|less|styl)(?:$|\?)/
 
 /**
@@ -175,8 +248,16 @@ export function viteLeakGuard(options: LeakGuardOptions = {}): LeakGuardPlugin {
   const appRoot = resolve(options.appRoot ?? process.cwd())
   const root = resolve(options.root ?? appRoot)
   const outDir = resolve(root, options.outDir ?? "dist")
+  const specifiers = entrySpecifiers(appRoot, options)
   const plugin: LeakGuardPlugin = {
     name: "nifra:leak-guard",
+    buildStart: () => specifiers.reset(),
+    resolveId: {
+      order: "pre",
+      handler(source, importer, resolveOptions) {
+        return specifiers.resolveId(this, source, importer, resolveOptions)
+      },
+    },
     generateBundle(_options, bundle) {
       const classifier = classifierFor(appRoot, options)
       // Resolved import edges per module, straight from Rollup's graph. Dynamic imports count too: a
@@ -186,7 +267,9 @@ export function viteLeakGuard(options: LeakGuardOptions = {}): LeakGuardPlugin {
         if (info === null) return []
         return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])]
       }
-      const graph = completeGraph(fromRollupBundle(bundle, importsOf), this, importsOf)
+      const graph = specifiers.annotate(
+        completeGraph(fromRollupBundle(bundle, importsOf), this, importsOf),
+      )
       const sources = { classifier, sourceOf: rollupModuleSource }
       const privateEnv = privateEnvCheck(options.publicEnvPrefix ?? "PUBLIC_")
       const outputs = Object.values(bundle as Readonly<Record<string, RollupOutputLike>>)
@@ -271,8 +354,16 @@ export type ServerZoneGuardOptions = Pick<
  */
 export function viteServerZoneGuard(options: ServerZoneGuardOptions = {}): LeakGuardPlugin {
   const appRoot = resolve(options.appRoot ?? process.cwd())
+  const specifiers = entrySpecifiers(appRoot, options)
   const plugin: LeakGuardPlugin = {
     name: "nifra:server-zone-guard",
+    buildStart: () => specifiers.reset(),
+    resolveId: {
+      order: "pre",
+      handler(source, importer, resolveOptions) {
+        return specifiers.resolveId(this, source, importer, resolveOptions)
+      },
+    },
     generateBundle(_options, bundle) {
       const classifier = classifierFor(appRoot, options)
       const importsOf = (id: string): readonly string[] => {
@@ -280,7 +371,9 @@ export function viteServerZoneGuard(options: ServerZoneGuardOptions = {}): LeakG
         if (info === null) return []
         return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])]
       }
-      const graph = completeGraph(fromRollupBundle(bundle, importsOf), this, importsOf)
+      const graph = specifiers.annotate(
+        completeGraph(fromRollupBundle(bundle, importsOf), this, importsOf),
+      )
       const leak = formatServerGraphVerdict(
         verifyServerGraph(graph, {
           classifier,
@@ -465,7 +558,6 @@ export interface AssetUrlGuardPlugin {
   ): Promise<null>
 }
 
-const POSTFIX = /[?#].*$/s
 const URL_SCHEME = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i
 
 /**
@@ -507,7 +599,7 @@ export function viteAssetUrlGuard(options: ServerZoneGuardOptions = {}): AssetUr
     },
     async transform(code, id, transformOptions) {
       if (transformOptions?.ssr === true || !code.includes("import.meta.url")) return null
-      const importer = id.replace(POSTFIX, "")
+      const importer = withoutQuery(id)
       if (!isAbsolute(importer) || importer.includes("/node_modules/") || CSS_FILE.test(importer))
         return null
       let program: unknown
@@ -553,11 +645,11 @@ async function assetUrlFiles(
 ): Promise<string[]> {
   const files = new Set<string>()
   const add = (path: string | undefined): void => {
-    const file = path?.replace(POSTFIX, "")
+    const file = path === undefined ? undefined : withoutQuery(path)
     if (file === undefined || !isAbsolute(file) || file.includes("\0")) return
     if (statSync(file, { throwIfNoEntry: false })?.isFile() === true) files.add(file)
   }
-  if (!url.startsWith("/")) add(resolve(dirname(importer), url.replace(POSTFIX, "")))
+  if (!url.startsWith("/")) add(resolve(dirname(importer), withoutQuery(url)))
   const sources = url.startsWith(".") || url.startsWith("/") ? [url] : [url, `./${url}`]
   for (const source of sources) {
     try {

package/src/plugins/vite-zone-guard.ts

@@ -10,10 +10,12 @@
  *
  * The SSR environment loads the same files legitimately and is never checked here.
  */
-import { existsSync, readFileSync, statSync } from "node:fs"
+import { readFileSync, statSync } from "node:fs"
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { installedManifest } from "../internal/package-entries.ts"
 import { privateEnvDenial } from "../internal/private-env.ts"
+import { withoutQuery } from "../internal/without-query.ts"
 import {
   browserDenial,
   type Classification,
@@ -78,7 +80,6 @@ export interface ViteZoneGuardPlugin {
   fileForUrl(url: string): string | undefined
 }
 
-const stripQuery = (id: string): string => id.replace(/[?#].*$/, "")
 /** Query forms that hand a module's source, or a URL to it, to the browser untransformed. */
 const RAW_QUERY = /(?:^|&)(?:raw|url|inline)(?:[&=]|$)/
 
@@ -136,7 +137,7 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
   const fileForUrl = (url: string): string | undefined => {
     let path: string
     try {
-      path = decodeURIComponent(stripQuery(url))
+      path = decodeURIComponent(withoutQuery(url))
     } catch {
       return undefined
     }
@@ -187,16 +188,17 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
     return context.error(new Error(message))
   }
 
-  /** A bare specifier's package, classified through its manifest so a workspace link is first-party. */
-  const packageClassification = (name: string, importer: string): Classification => {
-    let dir = dirname(importer)
-    for (;;) {
-      const manifest = join(dir, "node_modules", name, "package.json")
-      if (existsSync(manifest)) return classifier.classify(manifest)
-      const parent = dirname(dir)
-      if (parent === dir) return { zone: "library", packageName: name }
-      dir = parent
-    }
+  /** A bare import's package, classified through its manifest so a workspace link is first-party,
+   * and by the entry it names when the package declares a side per entry. */
+  const packageClassification = (
+    name: string,
+    importer: string,
+    specifier: string,
+  ): Classification => {
+    const manifest = installedManifest(dirname(importer), name)
+    return manifest === undefined
+      ? { zone: "library", packageName: name }
+      : classifier.classify(manifest, specifier)
   }
 
   return {
@@ -219,10 +221,10 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
     async resolveId(source, importer, resolveOptions) {
       if (importer === undefined || resolveOptions?.scan === true) return null
       if (!isClient(this, resolveOptions?.ssr)) return null
-      const importerFile = stripQuery(importer)
+      const importerFile = withoutQuery(importer)
       if (!isAbsolute(importerFile)) return null
       if (source.startsWith(".")) {
-        const target = resolve(dirname(importerFile), stripQuery(source))
+        const target = resolve(dirname(importerFile), withoutQuery(source))
         if (isFile(target)) {
           const reason = browserDenial(classifier.classify(target))
           if (reason !== undefined) refuse(this, target, reason, importerFile)
@@ -231,21 +233,21 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
       }
       const name = specifierPackage(source)
       if (name !== undefined) {
-        const reason = browserDenial(packageClassification(name, importerFile), source)
+        const reason = browserDenial(packageClassification(name, importerFile, source), source)
         if (reason !== undefined) refuse(this, source, reason, importerFile)
       }
       // An alias, a tsconfig path or a package export: what the specifier resolves to decides.
       const resolved = await this.resolve(source, importer, { ...resolveOptions, skipSelf: true })
-      const target = resolved === null || resolved.external ? undefined : stripQuery(resolved.id)
+      const target = resolved === null || resolved.external ? undefined : withoutQuery(resolved.id)
       if (target !== undefined && isAbsolute(target) && isFile(target)) {
-        const reason = browserDenial(classifier.classify(target), source)
+        const reason = browserDenial(classifier.classify(target, source), source)
         if (reason !== undefined) refuse(this, target, reason, importerFile)
       }
       return null
     },
     transform(code, id, transformOptions) {
       if (!isClient(this, transformOptions?.ssr)) return null
-      const file = stripQuery(id)
+      const file = withoutQuery(id)
       if (!isAbsolute(file) || !isFile(file)) return null
       // A fresh transform re-resolves every import, so an earlier refusal is stale until it recurs.
       refusals.delete(resolve(file))

package/src/plugins/zone-guard.ts

@@ -10,11 +10,14 @@
 import { statSync } from "node:fs"
 import { dirname, isAbsolute, relative, resolve } from "node:path"
 import type { BunPlugin } from "bun"
+import { installedManifest } from "../internal/package-entries.ts"
 import { privateEnvDenial } from "../internal/private-env.ts"
+import { withoutQuery } from "../internal/without-query.ts"
 import {
   BACKEND_ONLY_MARKER,
   browserDenial,
   createZoneClassifier,
+  specifierPackage,
   type ZoneClassifier,
 } from "../zones.ts"
 
@@ -58,6 +61,40 @@ export interface ZoneGuardOptions {
 /** Zones whose code runs in a browser, so may read only public environment variables. */
 const BROWSER_CODE = new Set<string>(["route-frontend", "frontend", "shared"])
 
+const loaderFor = (file: string): "ts" | "tsx" | "js" | "jsx" | undefined => {
+  const extension = /\.[cm]?([jt]sx?)$/.exec(file)?.[1]
+  return extension === "ts" || extension === "tsx" || extension === "js" || extension === "jsx"
+    ? extension
+    : undefined
+}
+
+/**
+ * Why browser code at `file` may not make one of its package imports: one naming an entry its package
+ * declares backend-only, or one its per-entry map leaves out. A path cannot tell two entries that share
+ * a file apart, so the dev server judges the specifier here, where it is written.
+ */
+function entryDenial(classifier: ZoneClassifier, file: string, source: string): string | undefined {
+  const loader = loaderFor(file)
+  if (loader === undefined) return undefined
+  let imports: ReadonlyArray<{ readonly path: string }>
+  try {
+    imports = new Bun.Transpiler({ loader }).scanImports(source)
+  } catch {
+    // Source Bun cannot read fails its own load with the parse error.
+    return undefined
+  }
+  for (const { path } of imports) {
+    const name = specifierPackage(path)
+    const manifest = name === undefined ? undefined : installedManifest(dirname(file), name)
+    if (manifest === undefined) continue
+    const classification = classifier.classify(manifest, path)
+    if (classification.entry === undefined) continue
+    const reason = browserDenial(classification, path)
+    if (reason !== undefined) return `it imports "${path}": ${reason}`
+  }
+  return undefined
+}
+
 export function zoneGuardPlugin(options: ZoneGuardOptions): BunPlugin {
   const classifier = options.classifier ?? createZoneClassifier(options)
   const display = (file: string): string => {
@@ -86,14 +123,16 @@ export function zoneGuardPlugin(options: ZoneGuardOptions): BunPlugin {
           BROWSER_CODE.has(classification.zone)
         ) {
           const source = await Bun.file(args.path).text()
-          reason = privateEnvDenial(args.path, source, options.publicEnvPrefix ?? "PUBLIC_")
+          reason =
+            privateEnvDenial(args.path, source, options.publicEnvPrefix ?? "PUBLIC_") ??
+            entryDenial(classifier, args.path, source)
         }
         return reason === undefined ? undefined : refuse(args.path, reason)
       })
       build.onResolve({ filter: NON_SOURCE_PATH }, (args) => {
         // An entry point (a dev server's HTML page) is the build's own choice, not an import.
         if (args.importer === "") return undefined
-        const file = resolve(dirname(args.importer), args.path.replace(/[?#].*$/, ""))
+        const file = resolve(dirname(args.importer), withoutQuery(args.path))
         // No such file means an extensionless import of a dotted source name (`./date.utils`): Bun resolves
         // it to the source file, which onLoad judges. Judging the bare path would refuse a file never loaded.
         if (!isFile(file)) return undefined

package/src/prerender.ts

@@ -9,7 +9,7 @@
  * routes are not supported.
  */
 import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname, resolve, sep } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 import { assertNoSecrets, buildEnvironment, type SecretExemption } from "./internal/secret-scan.ts"
 import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
 import { DATA_HEADER, PRERENDERED_GLOBAL, PRERENDERED_LIST_PATH } from "./router.ts"
@@ -70,10 +70,32 @@ function trimTrailingSlashes(path: string): string {
   return path.slice(0, end)
 }
 
-/** Map a route path to its output file: `/` → `index.html`, `/a/b` → `a/b/index.html`. */
+/**
+ * One request-path segment as the file name a static host looks up, which is the segment decoded, or
+ * `undefined` when no file name maps back to it: malformed percent-encoding, `.` or `..`, or a decoded
+ * `/`, `\` or NUL.
+ */
+function fileSegment(segment: string): string | undefined {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(segment)
+  } catch {
+    return undefined
+  }
+  if (decoded === "." || decoded === ".." || /[/\\\0]/.test(decoded)) return undefined
+  return decoded
+}
+
+/**
+ * Map a route path to its output file: `/` → `index.html`, `/a/b` → `a/b/index.html`. Segments are
+ * written decoded (`/caf%C3%A9` → `café/index.html`) because a static host decodes the request path
+ * before it looks for a file; a segment with no such file name stays as written.
+ */
 export function htmlFileFor(pattern: string): string {
   const trimmed = trimTrailingSlashes(pattern.replace(/^\/+/, ""))
-  return trimmed === "" ? "index.html" : `${trimmed}/index.html`
+  if (trimmed === "") return "index.html"
+  const segments = trimmed.split("/").map((segment) => fileSegment(segment) ?? segment)
+  return `${segments.join("/")}/index.html`
 }
 
 // The handover of a page whose prerendered set is served as a list rather than inlined.
@@ -119,6 +141,16 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
   // static (one path) and dynamic (one path per getStaticPaths entry) routes. A failed render is a skip;
   // a credential in the output fails the whole prerender.
   const renderPath = async (path: string): Promise<void> => {
+    // Refused before rendering: a segment no file name maps back to, or a file outside `outDir`.
+    const file = htmlFileFor(path)
+    const segments = trimTrailingSlashes(path.replace(/^\/+/, "")).split("/")
+    const abs = segments.every((s) => s === "" || fileSegment(s) !== undefined)
+      ? outputPath(outRoot, file)
+      : undefined
+    if (abs === undefined) {
+      skipped.push({ path, reason: "unsafe output path" })
+      return
+    }
     const res = await options.app.fetch(new Request(`${origin}${path}`))
     if (!res.ok) {
       // A failed render is a per-route skip, not a build failure - surfaced for the caller to log.
@@ -127,12 +159,6 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
     }
     const html = await res.text()
     listUrl ??= PRERENDERED_LIST_URL.exec(html)?.[1]
-    const file = htmlFileFor(path)
-    const abs = outputPath(outRoot, file)
-    if (abs === undefined) {
-      skipped.push({ path, reason: "unsafe output path" })
-      return
-    }
     assertClean(file, html)
     mkdirSync(dirname(abs), { recursive: true })
     writeFileSync(abs, html)
@@ -150,15 +176,10 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
       !(dataRes.headers.get("content-type") ?? "").includes("application/x-ndjson")
     ) {
       dataFile = dataFileFor(path)
-      const dataAbs = outputPath(outRoot, dataFile)
-      if (dataAbs === undefined) {
-        await dataRes.body?.cancel()
-        dataFile = undefined
-      } else {
-        const data = await dataRes.text()
-        assertClean(dataFile, data)
-        writeFileSync(dataAbs, data)
-      }
+      const data = await dataRes.text()
+      assertClean(dataFile, data)
+      // Beside `index.html`, so inside `outDir` whenever it is.
+      writeFileSync(join(dirname(abs), "_data.json"), data)
     } else {
       await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
     }

package/src/render-seam.ts

@@ -33,6 +33,61 @@ export interface RenderProps {
   readonly boundaries?: BoundaryStates
   /** The rendered chain's module ids and `handle` exports, for the adapter's `useMatches`. */
   readonly matchChain?: MatchChain
+  /** The page's locale, when the app registers its locale routing (`createWebApp`'s `i18n`). Set on
+   * SSR only; the client names it from `path` (see {@link localeOfProps}). */
+  readonly locale?: PageLocale
+}
+
+/** A served locale as a page renders in it: from the app's locale registry. */
+export interface PageLocale {
+  /** The registry key, which is also the URL segment (`ur`). */
+  readonly key: string
+  /** The BCP-47 tag `<html lang>` and `Content-Language` carry (`ur-PK`). */
+  readonly lang: string
+  readonly dir: "ltr" | "rtl"
+}
+
+/** The served locales, handed to the client so it names a page's locale from its path the way the
+ * server does. */
+export interface PageLocales {
+  /** The default locale's key. */
+  readonly default: string
+  /** Every served locale, in registry order. */
+  readonly locales: readonly PageLocale[]
+}
+
+/** The handover global carrying {@link PageLocales}. */
+export const LOCALES_GLOBAL = "__NIFRA_LOCALES__"
+
+/**
+ * The locale a path is in, by the rule `@nifrajs/i18n/routing`'s `localeOf` follows: a first path
+ * segment that names a served locale, ignoring ASCII case, or else the default.
+ */
+export function pageLocaleIn(config: PageLocales, path: string): PageLocale | undefined {
+  // One linear pass: separators, then the segment up to the next separator, query or hash.
+  const first = /^[/\\]*([^/\\?#]*)/.exec(path.replace(/[\t\n\r]/g, ""))?.[1]?.toLowerCase()
+  return (
+    config.locales.find((locale) => first !== "" && locale.key.toLowerCase() === first) ??
+    config.locales.find((locale) => locale.key === config.default)
+  )
+}
+
+const isPageLocales = (value: unknown): value is PageLocales =>
+  typeof value === "object" && value !== null && "locales" in value && Array.isArray(value.locales)
+
+/** The locale of the page at `path`, from the served locales the server handed over; `undefined`
+ * outside a browser page, or when the app registers no locale routing. */
+export function handoverLocale(path: string): PageLocale | undefined {
+  const config: unknown = Reflect.get(globalThis, LOCALES_GLOBAL)
+  return isPageLocales(config) ? pageLocaleIn(config, path) : undefined
+}
+
+/** The locale of the page `props` render: the server's answer on SSR, else the one the client names
+ * from `props.path`. What every adapter's `useLocale` reads. */
+export function localeOfProps(props: RenderProps | undefined): PageLocale | undefined {
+  if (props === undefined) return undefined
+  if (props.locale !== undefined) return props.locale
+  return props.path === undefined ? undefined : handoverLocale(props.path)
 }
 
 /**
@@ -62,10 +117,24 @@ export interface UIMatch {
   readonly handle: unknown
 }
 
+/**
+ * Markup a render produced for outside the app root, which an adapter that sets
+ * {@link RenderAdapter.documentParts} appends to. Each part must be complete before the render
+ * settles: `renderToString` resolving, or `renderToStream` returning its stream.
+ */
+export interface DocumentParts {
+  /** Placed at the end of `<head>`. Svelte's `<svelte:head>` lands here. */
+  head: string
+  /** Placed first in `<body>`, before the app root. Vue's `<Teleport to="body">` lands here. */
+  body: string
+}
+
 /** Per-document options for {@link RenderAdapter.renderToStream}. */
 export interface RenderStreamOptions {
   /** The document's CSP nonce, for every executable `<script>` the framework streams. */
   readonly nonce?: string
+  /** Present only for an adapter that sets {@link RenderAdapter.documentParts}. */
+  readonly parts?: DocumentParts
 }
 
 /**
@@ -84,10 +153,22 @@ export interface RenderAdapter {
     props: RenderProps,
     options?: RenderStreamOptions,
   ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
-  /** Render the chain to a complete HTML string when no content is deferred. */
-  renderToString?(chain: readonly unknown[], props: RenderProps): string | Promise<string>
+  /**
+   * Render the chain to a complete HTML string when no content is deferred. `options.nonce` is the
+   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data).
+   */
+  renderToString?(
+    chain: readonly unknown[],
+    props: RenderProps,
+    options?: RenderStreamOptions,
+  ): string | Promise<string>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
+  /**
+   * Set when a render can produce markup that belongs outside the app root. Every render is then
+   * passed `options.parts` to fill; an adapter without it never is, and pays nothing for the seam.
+   */
+  readonly documentParts?: boolean
 }
 
 /** Loads a module through the dev server's module graph rather than the runtime's resolver. */
@@ -125,5 +206,10 @@ export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 /** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
 export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
 export const COMPONENT_GLOBAL = "__NIFRA_COMPONENTS__"
+/** Locale key -> copy chunk URL, in a production build that split copy tables by locale. The name
+ * `@nifrajs/i18n/copy` reads. */
+export const COPY_CHUNKS_GLOBAL = "__NIFRA_COPY__"
+/** The registry `@nifrajs/i18n/copy` keeps its loaded chunks and definitions in. */
+export const COPY_REALM = "nifra.copy"
 /** Marker attribute used to find a non-default hydration container. */
 export const ROOT_ATTRIBUTE = "data-nifra-root"