@nifrajs/web 5.1.0 → 5.3.0

package/src/public-dir.ts

@@ -12,11 +12,12 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
-import { realpath } from "node:fs/promises"
+import { type FileHandle, realpath } from "node:fs/promises"
 import { extname, normalize, resolve, sep } from "node:path"
 import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
+import { isHiddenPublicPath } from "./internal/public-url.ts"
 import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
@@ -96,15 +97,33 @@ export const CONTENT_TYPES: Readonly<Record<string, string>> = {
 }
 
 /**
- * Whether a confined path crosses a dot-segment other than `.well-known`. The build copies `public/`
- * with dotfiles included, so an editor or VCS artifact (`.env`, `.git/`, `.DS_Store`) dropped there
- * would otherwise be downloadable. Checked on the resolved path, so `%2e` encodings are covered.
+ * Whether a confined path crosses a hidden segment ({@link isHiddenPublicPath}). Checked on the
+ * resolved path, so `%2e` encodings are covered, and again on the real target, so a visible name
+ * linking to `.env` is refused too.
  */
 function isHiddenPath(root: string, abs: string): boolean {
-  for (const segment of abs.slice(root.length + 1).split(sep)) {
-    if (segment.startsWith(".") && segment !== ".well-known") return true
+  return abs !== root && isHiddenPublicPath(abs.slice(root.length + 1))
+}
+
+// Up to this many bytes are read whole through the pinned descriptor, which then closes before the
+// response leaves: on Bun a 200 KB asset is served in 0.17 ms against 0.28 ms through a node:fs
+// stream. A larger body streams, so a video holds 64 KiB per request rather than the file.
+const BUFFERED_BODY_MAX = 256 * 1024
+
+/** `length` bytes of `handle` from `start`; fewer when the file shrank since its stat. */
+async function readPinned(
+  handle: FileHandle,
+  start: number,
+  length: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const bytes = new Uint8Array(length)
+  let offset = 0
+  while (offset < length) {
+    const { bytesRead } = await handle.read(bytes, offset, length - offset, start + offset)
+    if (bytesRead === 0) break
+    offset += bytesRead
   }
-  return false
+  return offset === length ? bytes : bytes.subarray(0, offset)
 }
 
 /** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
@@ -194,7 +213,8 @@ export function servePublicDir(
     if (
       resolvedRoot === undefined ||
       resolvedFile === undefined ||
-      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))
+      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep)) ||
+      isHiddenPath(resolvedRoot, resolvedFile)
     ) {
       return undefined
     }
@@ -243,7 +263,8 @@ export function servePublicDir(
         return new Response(null, { status: 304, headers })
       }
 
-      const rangeHeader = request.headers.get("range")
+      // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
+      const rangeHeader = head ? null : request.headers.get("range")
       const range =
         rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
           ? parseByteRange(rangeHeader, size)
@@ -255,7 +276,16 @@ export function servePublicDir(
         return new Response(null, { status: 416, headers })
       }
 
-      const body = (start?: number, end?: number): ReadableStream<Uint8Array> => {
+      const body = async (
+        start: number,
+        end: number,
+      ): Promise<Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>> => {
+        const length = end - start + 1
+        if (length <= BUFFERED_BODY_MAX) {
+          const bytes = await readPinned(handle!, start, length)
+          headers.set("content-length", String(bytes.byteLength))
+          return bytes
+        }
         const stream = handle!.createReadStream({ start, end })
         // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
         handle = undefined
@@ -266,14 +296,14 @@ export function servePublicDir(
         const { start, end } = range.ranges[0]!
         headers.set("content-range", `bytes ${start}-${end}/${size}`)
         headers.set("content-length", String(end - start + 1))
-        return new Response(head ? null : body(start, end), { status: 206, headers })
+        return new Response(head ? null : await body(start, end), { status: 206, headers })
       }
 
       // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
       // disk means buffering the whole representation to serve a request that asked for less of it.
       // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
       headers.set("content-length", String(size))
-      return new Response(head ? null : body(), { headers })
+      return new Response(head || size === 0 ? null : await body(0, size - 1), { headers })
     } finally {
       if (handle !== undefined) {
         try {
@@ -285,3 +315,68 @@ export function servePublicDir(
     }
   }
 }
+
+export interface PrerenderedPageReaderOptions {
+  /** Absolute path of the directory the build wrote the prerendered pages into. */
+  readonly dir: string
+  /** Each page path mapped to its file, relative to `dir`. */
+  readonly files: Readonly<Record<string, string>>
+  /** Bytes of HTML kept in memory once read (default 32 MiB); a page past the budget is read per request. */
+  readonly cacheBytes?: number
+}
+
+/**
+ * Read a self-hosted build's prerendered pages for `createWebApp`'s `prerenderedPages`. Only the build's
+ * own files are reachable, each opened only once its real path is inside `dir`, so a link planted in the
+ * deployed tree cannot point a page elsewhere. A deploy's files do not change while it runs, so a page
+ * is kept after its first read; `undefined` (a missing or refused file) renders the page on demand.
+ */
+export function prerenderedPageReader(
+  options: PrerenderedPageReaderOptions,
+): (pathname: string) => Promise<string | undefined> {
+  const root = resolve(options.dir)
+  const rootReal = realpath(root).catch(() => undefined)
+  const files = new Map(Object.entries(options.files))
+  const budget = options.cacheBytes ?? 32 * 1024 * 1024
+  const cache = new Map<string, string>()
+  let cachedBytes = 0
+  return async (pathname) => {
+    const cached = cache.get(pathname)
+    if (cached !== undefined) return cached
+    const rel = files.get(pathname)
+    if (rel === undefined) return undefined
+    const abs = resolve(root, rel)
+    if (!abs.startsWith(root + sep) || isHiddenPath(root, abs)) return undefined
+    const [resolvedRoot, resolvedFile] = await Promise.all([
+      rootReal,
+      realpath(abs).catch(() => undefined),
+    ])
+    if (
+      resolvedRoot === undefined ||
+      resolvedFile === undefined ||
+      !resolvedFile.startsWith(resolvedRoot + sep)
+    ) {
+      return undefined
+    }
+    let handle: FileHandle
+    try {
+      handle = await openResolved(resolvedFile)
+    } catch {
+      return undefined
+    }
+    try {
+      if (!(await handle.stat()).isFile()) return undefined
+      const bytes = await handle.readFile()
+      const html = bytes.toString("utf8")
+      if (!cache.has(pathname) && cachedBytes + bytes.byteLength <= budget) {
+        cache.set(pathname, html)
+        cachedBytes += bytes.byteLength
+      }
+      return html
+    } catch {
+      return undefined
+    } finally {
+      await handle.close().catch(() => undefined)
+    }
+  }
+}

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)
 }
 
 /**
@@ -100,13 +155,16 @@ export interface RenderAdapter {
   ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
   /**
    * 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).
+   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data); a
+   * document that sends a policy keeps the nonce only when the returned HTML carries it. Return
+   * `undefined` when the render suspended on something only `renderToStream` waits for (React's
+   * `use` or `lazy` inside `<Suspense>`): the page is then streamed instead.
    */
   renderToString?(
     chain: readonly unknown[],
     props: RenderProps,
     options?: RenderStreamOptions,
-  ): string | Promise<string>
+  ): string | undefined | Promise<string | undefined>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
   /**
@@ -151,5 +209,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"

package/src/router.ts

@@ -310,8 +310,9 @@ export interface ClientRouterOptions {
   /** Override the loader-data fetch (tests inject a stub; defaults to a same-origin JSON GET). */
   readonly fetchData?: FetchRouteData
   /** Ensure a route's code chunk is loaded before rendering (code-splitting). Awaited in parallel
-   * with the loader data, so `pending` covers both. Omit when the bundle isn't split. */
-  readonly loadModule?: (routeId: string) => Promise<void>
+   * with the loader data, so `pending` covers both. Omit when the bundle isn't split. `path` is the URL
+   * the route is about to render, for code loaded per URL (a production build's copy chunks). */
+  readonly loadModule?: (routeId: string, path?: string) => Promise<void>
   /** Terminal status → client route id. Generated entries populate this from `_404` and
    * `_<status>` files so soft navigation renders the same boundary as a hard request. */
   readonly statusRoutes?: Readonly<Record<number, string>>
@@ -667,7 +668,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     )
     if (mine !== generation) return
     if (loaded.terminalRouteId !== undefined) {
-      await loadModule?.(loaded.terminalRouteId)
+      await loadModule?.(loaded.terminalRouteId, state.path)
       state = { ...state, routeId: loaded.terminalRouteId, params: {}, data: null }
     } else {
       state = {
@@ -788,7 +789,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         state = { ...state, pendingPath: at }
         emit()
       }
-      await loadModule?.(route.routeId)
+      await loadModule?.(route.routeId, at)
       // Prefetched server data is one-shot; a clientLoader still runs over it without another request.
       const prefetchedData = usePrefetch ? freshPrefetch(at) : undefined
       if (usePrefetch) prefetched.delete(at)
@@ -801,7 +802,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           prefetchedData,
         )
         if (loaded.terminalRouteId !== undefined) {
-          await loadModule?.(loaded.terminalRouteId)
+          await loadModule?.(loaded.terminalRouteId, at)
           if (options.layoutStatusRoutes?.[loaded.terminalRouteId] === true) {
             throw new Error(
               `[nifra/web] ${loaded.terminalRouteId} renders inside layouts; loading ${at} as a document`,
@@ -1215,7 +1216,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         // Unwrapped here, so a prefetched entry is the same shape `navigate` builds state from -
         // otherwise a prefetch hit would publish an envelope where a miss publishes loader data.
         const [, loaded] = await Promise.all([
-          loadModule?.(matched.routeId),
+          loadModule?.(matched.routeId, path),
           loadRouteData(path, matched),
         ])
         prefetched.delete(path) // a stale entry re-enters as the newest

package/src/search.ts

@@ -107,6 +107,7 @@ function encodeValue(value: unknown): string {
 /** The default JSON-first codec. Repeated keys (`?t=a&t=b`) decode to an array; single keys to a value. */
 const jsonCodec: SearchCodec = {
   parse(raw, limits) {
+    if (raw === "" || raw === "?") return {}
     const usp = new URLSearchParams(raw.startsWith("?") ? raw.slice(1) : raw)
     // Two passes instead of the old `Set(keys) + getAll(key)` shape, which rescanned the complete
     // URLSearchParams list once per distinct key (O(keys²)). Admission must be decided BEFORE any

package/src/server-components/typescript.ts

@@ -1,18 +1,10 @@
 import { createRequire } from "node:module"
 import type * as TS from "typescript"
+import { isTypeScriptCompiler } from "../internal/typescript-api.ts"
 
 /** The code of the error a TypeScript without the in-process compiler API raises here. */
 export const UNSUPPORTED_TYPESCRIPT = "NIFRA_TS_UNSUPPORTED"
 
-function isCompiler(value: unknown): value is typeof TS {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "createSourceFile" in value &&
-    typeof value.createSourceFile === "function"
-  )
-}
-
 /**
  * The TypeScript compiler API, resolved from `from` the way `import "typescript"` there would be.
  * TypeScript 7's package ships no in-process compiler API (its root export is only `version`), so
@@ -20,7 +12,7 @@ function isCompiler(value: unknown): value is typeof TS {
  */
 export function loadTypeScript(from: string = import.meta.url): typeof TS {
   const loaded: unknown = createRequire(from)("typescript")
-  if (isCompiler(loaded)) return loaded
+  if (isTypeScriptCompiler(loaded)) return loaded
   const version =
     typeof loaded === "object" &&
     loaded !== null &&