@nifrajs/web 3.3.0 → 4.0.0

package/src/public-dir.ts

@@ -12,8 +12,10 @@
  * 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 { normalize, resolve, sep } from "node:path"
+import { constants as FS } from "node:fs"
+import { open, 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"
 
@@ -36,8 +38,67 @@ export interface ServePublicDirOptions {
   readonly files?: ReadonlySet<string>
 }
 
-const IMMUTABLE = "public, max-age=31536000, immutable"
-const ONE_DAY = "public, max-age=86400"
+export const IMMUTABLE = "public, max-age=31536000, immutable"
+export const ONE_DAY = "public, max-age=86400"
+
+/**
+ * Media types by extension. A table rather than `Bun.file(path).type`: this handler also runs on the
+ * Node and Deno adapters, where `Bun` does not exist and every hit would throw. Unknown extensions
+ * (and extensionless files such as ACME tokens) are served as `application/octet-stream`, which
+ * together with `nosniff` keeps the browser from guessing a more dangerous type.
+ */
+export const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".cjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".webmanifest": "application/manifest+json",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+  ".xml": "application/xml",
+  ".rss": "application/rss+xml",
+  ".atom": "application/atom+xml",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".bmp": "image/bmp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".wasm": "application/wasm",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".m4a": "audio/mp4",
+  ".vtt": "text/vtt; charset=utf-8",
+}
+
+/**
+ * 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.
+ */
+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 false
+}
 
 /** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
 function seconds(time: number): number {
@@ -117,7 +178,7 @@ export function servePublicDir(
     // A production manifest can reject page routes without touching the filesystem.
     if (options.files !== undefined && !options.files.has(pathname)) return undefined
     const abs = resolvePublicPath(root, pathname)
-    if (abs === undefined) return undefined
+    if (abs === undefined || isHiddenPath(root, abs)) return undefined
     const [resolvedRoot, resolvedFile] = await Promise.all([
       rootReal,
       realpath(abs).catch(() => undefined),
@@ -129,54 +190,79 @@ export function servePublicDir(
     ) {
       return undefined
     }
-    const file = Bun.file(resolvedFile)
-    if (!(await file.exists())) return undefined
-    const size = file.size
-    const headers = new Headers({
-      "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
-      // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
-      // so a video or audio file under `public/` is scrubbable only once this header is present.
-      "accept-ranges": "bytes",
-    })
-    // `new Response(file)` used to infer the media type, which meant HEAD - built from a null body -
-    // silently lost it. Setting it here is what makes the two methods agree.
-    if (file.type !== "") headers.set("content-type", file.type)
-    const lastModified =
-      Number.isFinite(file.lastModified) && file.lastModified > 0 ? file.lastModified : undefined
-    if (lastModified !== undefined) {
-      headers.set("last-modified", new Date(lastModified).toUTCString())
-    }
-    const head = request.method === "HEAD"
+    // Open the canonical path once and stream from that descriptor. Reopening the pathname after
+    // realpath containment checks would let a writable public tree swap a symlink between validation
+    // and the actual read. O_NOFOLLOW also rejects a final-component symlink if one appears before
+    // the open; the descriptor then pins the bytes for the lifetime of the response.
+    let handle: Awaited<ReturnType<typeof open>> | undefined
+    try {
+      handle = await open(resolvedFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+      const stat = await handle.stat()
+      if (!stat.isFile()) return undefined
+      const size = stat.size
+      const headers = new Headers({
+        "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
+        // so a video or audio file under `public/` is scrubbable only once this header is present.
+        "accept-ranges": "bytes",
+        // Never let a client sniff a served file into a more dangerous type (an upload-like `.txt`
+        // rendered as HTML, say). The declared type below is authoritative.
+        "x-content-type-options": "nosniff",
+        // Set explicitly rather than inferred from the body, so HEAD (a null body) carries it too.
+        "content-type":
+          CONTENT_TYPES[extname(resolvedFile).toLowerCase()] ?? "application/octet-stream",
+      })
+      const lastModified =
+        Number.isFinite(stat.mtimeMs) && stat.mtimeMs > 0 ? stat.mtimeMs : undefined
+      if (lastModified !== undefined) {
+        headers.set("last-modified", new Date(lastModified).toUTCString())
+      }
+      const head = request.method === "HEAD"
 
-    if (isNotModified(request, lastModified)) {
-      headers.delete("content-type")
-      return new Response(null, { status: 304, headers })
-    }
+      if (isNotModified(request, lastModified)) {
+        headers.delete("content-type")
+        return new Response(null, { status: 304, headers })
+      }
 
-    const rangeHeader = request.headers.get("range")
-    const range =
-      rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
-        ? parseByteRange(rangeHeader, size)
-        : ({ kind: "none" } as const)
+      const rangeHeader = request.headers.get("range")
+      const range =
+        rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
+          ? parseByteRange(rangeHeader, size)
+          : ({ kind: "none" } as const)
 
-    if (range.kind === "unsatisfiable") {
-      headers.delete("content-type")
-      headers.set("content-range", `bytes */${size}`)
-      return new Response(null, { status: 416, headers })
-    }
+      if (range.kind === "unsatisfiable") {
+        headers.delete("content-type")
+        headers.set("content-range", `bytes */${size}`)
+        return new Response(null, { status: 416, headers })
+      }
 
-    if (range.kind === "satisfiable" && range.ranges.length === 1) {
-      const { start, end } = range.ranges[0]!
-      headers.set("content-range", `bytes ${start}-${end}/${size}`)
-      headers.set("content-length", String(end - start + 1))
-      // `slice` keeps the read lazy: only the selected window is ever pulled off disk.
-      return new Response(head ? null : file.slice(start, end + 1), { status: 206, headers })
-    }
+      const body = (start?: number, end?: number): ReadableStream<Uint8Array> => {
+        const stream = handle!.createReadStream({ start, end })
+        // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
+        handle = undefined
+        return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>
+      }
+
+      if (range.kind === "satisfiable" && range.ranges.length === 1) {
+        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 })
+      }
 
-    // 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.
-    if (head) headers.set("content-length", String(size))
-    return new Response(head ? null : file, { 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 })
+    } finally {
+      if (handle !== undefined) {
+        try {
+          await handle.close()
+        } catch {
+          // Closing a descriptor is best-effort after the response decision is made.
+        }
+      }
+    }
   }
 }

package/src/pwa-manifest.ts

@@ -0,0 +1,226 @@
+/**
+ * `@nifrajs/web/pwa-manifest` - a Web App Manifest builder, the declarative half of PWA next to
+ * `@nifrajs/web/service-worker`'s generated worker. Pure + runtime-agnostic: describe the app and
+ * get the `manifest.json` bytes to serve (typically `app.get("/manifest.webmanifest", ...)` with
+ * `content-type: application/manifest+json`), plus the `<link rel="manifest">` tag for the
+ * document head. Follows the [Web App Manifest spec](https://www.w3.org/TR/appmanifest/) field
+ * names exactly, so MDN is the reference for anything not documented here.
+ *
+ * Invalid input throws loudly at build/startup time (a missing install name, a malformed icon
+ * size, an unknown display mode) - a manifest the browser silently ignores is worse than no
+ * manifest, and these are all developer mistakes, never request input.
+ */
+
+export type ManifestDisplay = "fullscreen" | "standalone" | "minimal-ui" | "browser"
+export type ManifestDir = "ltr" | "rtl" | "auto"
+export type ManifestPurpose = "any" | "maskable" | "monochrome"
+
+export interface ManifestIcon {
+  /** Icon URL, resolved relative to `start_url` by the browser when relative. */
+  readonly src: string
+  /** Space-separated sizes, e.g. `"192x192 512x512"`, or `"any"`. Default `"any"`. */
+  readonly sizes?: string
+  /** MIME type, e.g. `"image/png"`. */
+  readonly type?: string
+  /** Space-separated purposes. Default `"any"`. */
+  readonly purpose?: string
+}
+
+export interface ManifestScreenshot {
+  readonly src: string
+  readonly sizes?: string
+  readonly type?: string
+}
+
+export interface ManifestShortcut {
+  readonly name: string
+  readonly url: string
+  readonly short_name?: string
+  readonly description?: string
+  readonly icons?: readonly ManifestIcon[]
+}
+
+export interface PwaManifestOptions {
+  /** Full install name (`"Nifra News"`). One of `name` / `short_name` is required. */
+  readonly name?: string
+  /** Short install name for launchers (`"News"`). One of `name` / `short_name` is required. */
+  readonly short_name?: string
+  readonly description?: string
+  /** Navigation scope root. Default `"/"`. */
+  readonly start_url?: string
+  /** URL scope the manifest (and its service worker) controls. Default `start_url`'s directory. */
+  readonly scope?: string
+  /** Preferred display mode. Default `"standalone"` (the installable PWA shape). */
+  readonly display?: ManifestDisplay
+  readonly orientation?: string
+  readonly background_color?: string
+  readonly theme_color?: string
+  readonly lang?: string
+  readonly dir?: ManifestDir
+  /** Opaque id distinguishing this install (defaults to `start_url` per spec). */
+  readonly id?: string
+  readonly categories?: readonly string[]
+  readonly icons?: readonly ManifestIcon[]
+  readonly screenshots?: readonly ManifestScreenshot[]
+  readonly shortcuts?: readonly ManifestShortcut[]
+}
+
+const SIZE_LIST = /^(?:any|\d+x\d+)(?:\s+(?:any|\d+x\d+))*$/
+const PURPOSE_TOKENS: ReadonlySet<string> = new Set(["any", "maskable", "monochrome"])
+
+/** The start URL's directory, origin-preserving for absolute URLs. Query strings and hashes
+ * never belong to a scope - it is a URL prefix the browser matches against. */
+function defaultScope(start_url: string): string {
+  if (start_url.startsWith("/")) {
+    const bare = start_url.split(/[?#]/)[0] as string
+    return bare.endsWith("/") ? bare : bare.slice(0, bare.lastIndexOf("/") + 1)
+  }
+  let url: URL
+  try {
+    url = new URL(start_url)
+  } catch {
+    throw new Error(`pwaManifest: start_url ${JSON.stringify(start_url)} is not a path or URL`)
+  }
+  if (url.origin === "null" || (url.protocol !== "http:" && url.protocol !== "https:")) {
+    throw new Error(`pwaManifest: start_url ${JSON.stringify(start_url)} is not a path or URL`)
+  }
+  const dir = url.pathname.endsWith("/")
+    ? url.pathname
+    : url.pathname.slice(0, url.pathname.lastIndexOf("/") + 1)
+  return `${url.origin}${dir}`
+}
+
+function purposeOf(purpose: string | undefined, what: string): string | undefined {
+  if (purpose === undefined) return undefined
+  const tokens = purpose.split(/\s+/).filter((t) => t !== "")
+  if (tokens.length === 0) throw new Error(`pwaManifest: ${what} purpose must not be empty`)
+  for (const token of tokens) {
+    if (!PURPOSE_TOKENS.has(token)) {
+      throw new Error(
+        `pwaManifest: ${what} purpose ${JSON.stringify(token)} must be any/maskable/monochrome`,
+      )
+    }
+  }
+  return tokens.join(" ")
+}
+
+/** Build the manifest document object (pass through `JSON.stringify` to serve it). */
+export function pwaManifest(options: PwaManifestOptions): Record<string, unknown> {
+  const { name, short_name } = options
+  if (name === undefined && short_name === undefined) {
+    throw new Error("pwaManifest: one of name / short_name is required")
+  }
+  if (name !== undefined && name.trim() === "") {
+    throw new Error("pwaManifest: name must not be empty")
+  }
+  if (short_name !== undefined && short_name.trim() === "") {
+    throw new Error("pwaManifest: short_name must not be empty")
+  }
+  const display = options.display ?? "standalone"
+  if (
+    display !== "fullscreen" &&
+    display !== "minimal-ui" &&
+    display !== "browser" &&
+    display !== "standalone"
+  ) {
+    throw new Error(`pwaManifest: unknown display ${JSON.stringify(display)}`)
+  }
+  if (
+    options.dir !== undefined &&
+    options.dir !== "ltr" &&
+    options.dir !== "rtl" &&
+    options.dir !== "auto"
+  ) {
+    throw new Error(`pwaManifest: unknown dir ${JSON.stringify(options.dir)}`)
+  }
+  const start_url = options.start_url ?? "/"
+  if (start_url === "" || start_url.startsWith("//")) {
+    throw new Error("pwaManifest: start_url must be a relative path or absolute URL")
+  }
+  const manifest: Record<string, unknown> = {}
+  if (name !== undefined) manifest.name = name
+  if (short_name !== undefined) manifest.short_name = short_name
+  if (options.description !== undefined) manifest.description = options.description
+  manifest.start_url = start_url
+  // The default scope is the start URL's directory ("https://x.com/app/home" → "…/app/"),
+  // query/hash excluded; a same-origin absolute URL keeps its origin, a relative one stays
+  // relative. Anything unparseable is a developer mistake, and fails loud.
+  manifest.scope = options.scope ?? defaultScope(start_url)
+  manifest.display = display
+  if (options.orientation !== undefined) manifest.orientation = options.orientation
+  if (options.background_color !== undefined) manifest.background_color = options.background_color
+  if (options.theme_color !== undefined) manifest.theme_color = options.theme_color
+  if (options.lang !== undefined) manifest.lang = options.lang
+  if (options.dir !== undefined) manifest.dir = options.dir
+  if (options.id !== undefined) manifest.id = options.id
+  if (options.categories !== undefined) manifest.categories = [...options.categories]
+  if (options.icons !== undefined) {
+    manifest.icons = options.icons.map((icon, i) => {
+      if (icon.src === "") throw new Error(`pwaManifest: icons[${i}].src must not be empty`)
+      const sizes = icon.sizes ?? "any"
+      if (!SIZE_LIST.test(sizes)) {
+        throw new Error(
+          `pwaManifest: icons[${i}].sizes ${JSON.stringify(icon.sizes)} must be "any" or space-separated WxH`,
+        )
+      }
+      const entry: Record<string, unknown> = { src: icon.src, sizes }
+      if (icon.type !== undefined) entry.type = icon.type
+      const purpose = purposeOf(icon.purpose, `icons[${i}]`)
+      if (purpose !== undefined) entry.purpose = purpose
+      return entry
+    })
+  }
+  if (options.screenshots !== undefined) {
+    manifest.screenshots = options.screenshots.map((shot, i) => {
+      if (shot.src === "") throw new Error(`pwaManifest: screenshots[${i}].src must not be empty`)
+      const entry: Record<string, unknown> = { src: shot.src }
+      if (shot.sizes !== undefined) {
+        if (!SIZE_LIST.test(shot.sizes)) {
+          throw new Error(
+            `pwaManifest: screenshots[${i}].sizes ${JSON.stringify(shot.sizes)} must be "any" or space-separated WxH`,
+          )
+        }
+        entry.sizes = shot.sizes
+      }
+      if (shot.type !== undefined) entry.type = shot.type
+      return entry
+    })
+  }
+  if (options.shortcuts !== undefined) {
+    manifest.shortcuts = options.shortcuts.map((cut, i) => {
+      if (cut.name === "") throw new Error(`pwaManifest: shortcuts[${i}].name must not be empty`)
+      if (cut.url === "") throw new Error(`pwaManifest: shortcuts[${i}].url must not be empty`)
+      const entry: Record<string, unknown> = { name: cut.name, url: cut.url }
+      if (cut.short_name !== undefined) entry.short_name = cut.short_name
+      if (cut.description !== undefined) entry.description = cut.description
+      if (cut.icons !== undefined) {
+        entry.icons = cut.icons.map((icon, j) => {
+          if (icon.src === "") {
+            throw new Error(`pwaManifest: shortcuts[${i}].icons[${j}].src must not be empty`)
+          }
+          const sizes = icon.sizes ?? "any"
+          if (!SIZE_LIST.test(sizes)) {
+            throw new Error(
+              `pwaManifest: shortcuts[${i}].icons[${j}].sizes must be "any" or space-separated WxH`,
+            )
+          }
+          return { src: icon.src, sizes }
+        })
+      }
+      return entry
+    })
+  }
+  return manifest
+}
+
+/** Serialize a manifest document to servable JSON (stable key order, no whitespace). */
+export function serializeManifest(manifest: Record<string, unknown>): string {
+  return JSON.stringify(manifest)
+}
+
+/** The `<link rel="manifest">` tag for the document head. */
+export function manifestLink(href = "/manifest.webmanifest"): string {
+  if (href === "") throw new Error("manifestLink: href must not be empty")
+  const quoted = href.replace(/"/g, "&quot;")
+  return `<link rel="manifest" href="${quoted}">`
+}

package/src/query.ts

@@ -642,7 +642,7 @@ export function createMutation<TData, TVariables>(
   let mutationFn = fn
   let cbs = callbacks
   let state = IDLE_MUTATION as MutationState<TData, TVariables>
-  let token = 0
+  let latest = 0
   const listeners = new Set<() => void>()
   const emit = (): void => {
     for (const l of listeners) l()
@@ -665,19 +665,19 @@ export function createMutation<TData, TVariables>(
     },
     reset: () => setState(IDLE_MUTATION as MutationState<TData, TVariables>),
     mutate: async (variables) => {
-      const mine = ++token
+      const mine = ++latest
       setState({ status: "pending", data: undefined, error: undefined, variables })
       // Only await a callback when one is actually supplied - an `await undefined` would insert a
       // needless microtask before the mutationFn runs (and complicates single-flight timing).
       if (cbs.onMutate !== undefined) await cbs.onMutate(variables)
       try {
         const data = await mutationFn(variables)
-        if (mine === token) setState({ status: "success", data, error: undefined, variables })
+        if (mine === latest) setState({ status: "success", data, error: undefined, variables })
         if (cbs.onSuccess !== undefined) await cbs.onSuccess(data, variables)
         if (cbs.onSettled !== undefined) await cbs.onSettled(data, undefined, variables)
         return data
       } catch (error) {
-        if (mine === token) setState({ status: "error", data: undefined, error, variables })
+        if (mine === latest) setState({ status: "error", data: undefined, error, variables })
         if (cbs.onError !== undefined) await cbs.onError(error, variables)
         if (cbs.onSettled !== undefined) await cbs.onSettled(undefined, error, variables)
         throw error

package/src/render-seam.ts

@@ -30,6 +30,41 @@ export interface RenderProps {
   readonly search?: Record<string, unknown>
   /** Neutral named-boundary states; adapters choose how each boundary's `render` UI is mounted. */
   readonly boundaries?: BoundaryStates
+  /** The rendered chain's module ids and `handle` exports, for the adapter's `useMatches`. */
+  readonly matchChain?: MatchChain
+}
+
+/**
+ * The modules a render stacks, as `useMatches` needs them: each one's id and `handle` export,
+ * outermost layout first and the page (or status page) last. Built by the server for SSR and by the
+ * generated client entry per route, from the same manifest, so both sides report the same matches.
+ */
+export interface MatchChain {
+  /** Layout ids (`orgs/[org]/_layout`), then the page's route id. */
+  readonly ids: readonly string[]
+  /** Each module's `handle` export, index-aligned with {@link ids}. */
+  readonly handles: readonly unknown[]
+}
+
+/** One module of the rendered chain, as `useMatches` returns it. */
+export interface UIMatch {
+  /** The module's id: a layout's (`orgs/[org]/_layout`), or the page's route id last. */
+  readonly id: string
+  /** The part of the URL path this module wraps: a layout's directory prefix, the whole path for the
+   * page. Raw, as it appears in the URL. */
+  readonly pathname: string
+  /** The params this module's loader receives: a layout's own, every route param for the page. */
+  readonly params: Readonly<Record<string, string>>
+  /** This module's loader data: `null` for a layout without a loader. */
+  readonly data: unknown
+  /** The module's `handle` export - any value, commonly a breadcrumb label or a render function. */
+  readonly handle: unknown
+}
+
+/** 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
 }
 
 /**
@@ -39,11 +74,14 @@ export interface RenderProps {
 export interface RenderAdapter {
   /**
    * Render a route's layout `chain` (outermost layout → page) to a Web stream of HTML bytes,
-   * including the framework's hydration markers.
+   * including the framework's hydration markers. When `options.nonce` is set, every executable
+   * `<script>` the framework streams (out-of-order Suspense runtimes, serialized resources) must
+   * carry it, or a nonce-based Content-Security-Policy blocks it and the boundary never resolves.
    */
   renderToStream(
     chain: readonly unknown[],
     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>
@@ -67,6 +105,13 @@ export function ssrModuleLoader(): SsrModuleLoader | undefined {
   return loaderSlot[SSR_MODULE_LOADER_SLOT]
 }
 
+/**
+ * `id` of the inert `<script type="application/json">` a hydrating document hands its page state over
+ * in: one JSON object keyed by the `*_GLOBAL` names below, which the client entry assigns onto
+ * `window` before anything reads them. Data the browser never executes needs no CSP nonce or hash.
+ */
+export const HANDOVER_ID = "__nifra-handover"
+
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
 /** Per-layout loader data for hydration. */

package/src/route-manifest.ts

@@ -16,8 +16,19 @@
  * target, and reports what the target cannot honour. Pure and fs-free: it takes an already-built
  * `Manifest` so it runs at build time, in `nifra routes`, and in a test with a hand-built manifest.
  */
+
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import type { Manifest, RouteModule } from "./manifest.ts"
 
+export {
+  formatShadowedPages,
+  normalizeMountPath,
+  type ShadowedPage,
+  shadowedPages,
+} from "./internal/mount-shadow.ts"
+/** Which half of a route each export belongs in: the frontend file or its `x.backend.ts`. */
+export { BACKEND_ROUTE_EXPORTS, FRONTEND_ROUTE_EXPORTS } from "./manifest.ts"
+
 /**
  * How a route produces its HTML.
  *
@@ -115,7 +126,8 @@ export function deriveRouteEntry(
     requires: readonly RouteCapability[]
   } = { id, pattern, mode, hydrate: module.hydrate !== false, requires }
   if (mode === "isr" && module.revalidate !== undefined) entry.revalidate = module.revalidate
-  if (mode === "isr" && module.revalidateTags !== undefined) {
+  // A function's tags exist per request; the manifest records only a fixed list.
+  if (mode === "isr" && Array.isArray(module.revalidateTags)) {
     entry.revalidateTags = module.revalidateTags
   }
   if (prerenderedPaths !== undefined) entry.prerenderedPaths = prerenderedPaths
@@ -134,7 +146,7 @@ const TARGET_CAPABILITIES: Readonly<Record<string, readonly RouteCapability[]>>
   bun: ["server"],
   node: ["server"],
   deno: ["server"],
-  "cf-pages": ["server"],
+  cloudflare: ["server"],
   vercel: ["server"],
   static: [],
 }
@@ -169,7 +181,7 @@ export async function buildRouteManifest(
     const module = (await route.load()) as RouteModule
     entries.push(deriveRouteEntry(route.id, route.pattern, module, options.prerendered?.[route.id]))
   }
-  entries.sort((a, b) => a.pattern.localeCompare(b.pattern))
+  entries.sort((a, b) => codeUnitOrder(a.pattern, b.pattern))
 
   const conflicts: RouteManifestConflict[] = []
   const capabilities =