@nifrajs/web 5.5.0 → 5.6.0

package/src/fn.ts

@@ -54,6 +54,7 @@ import {
   type StandardSchemaV1,
 } from "@nifrajs/core/server"
 import { guardChannel, outputGuard } from "./internal/output-guard.ts"
+import { SERVER_FN_NAMESPACE } from "./internal/server-boundary.ts"
 
 /** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
 export const SERVER_FN_PREFIX = "/_nifra/fn"
@@ -78,8 +79,9 @@ export interface ServerFnConfig<Input> {
 
 /**
  * A declared server function. Callable directly on the server (the same value your own server-side
- * code can await); on the client, phase 2's build transform replaces this module with typed stubs
- * that POST to the mounted route.
+ * code can await); in a client build, this module becomes typed stubs that POST under its
+ * file's name (`todos.fn.ts` posts under `todos`), so {@link serverFunctions} must mount it
+ * under that name.
  *
  * This is the SERVER declaration type, so context is required. Client builds replace the module with
  * a one-argument {@link ClientServerFn}; UI bindings accept either shape and adapt at that boundary.
@@ -123,8 +125,6 @@ export function serverFn<Input = void, Output = unknown>(
 const isServerFn = (value: unknown): value is ServerFn<unknown, unknown> =>
   typeof value === "function" && SERVER_FN in (value as object)
 
-/** A namespace segment: lowercase, dot/dash separated. Constrained so a mount cannot invent a path. */
-const NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/
 /** An export name that is safe in a URL path without escaping. */
 const EXPORT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
@@ -156,12 +156,13 @@ export type ServerFnModule = Readonly<Record<string, unknown>>
  *
  * The namespace is explicit rather than derived from the file path: a path-derived one would put the
  * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
- * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ * the codebase. The client build's stubs call the namespace named by the module's file (`todos.fn.ts`
+ * calls `todos`), so pass that same word here.
  *
  * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
  */
 export function serverFunctions(namespace: string, module: ServerFnModule): IdentityPlugin {
-  if (!NAMESPACE.test(namespace)) {
+  if (!SERVER_FN_NAMESPACE.test(namespace)) {
     throw new Error(
       `[nifra/fn] invalid server-function namespace ${JSON.stringify(namespace)} - use lowercase dot/dash segments (it becomes a URL path).`,
     )
@@ -213,5 +214,21 @@ export function serverFunctions(namespace: string, module: ServerFnModule): Iden
     }
     return app
   }
-  return defineIdentityPlugin(`nifra:server-fn:${namespace}`, apply)
+  // A plugin name per module: the same module mounted twice stays one mount, while a second module
+  // under a taken namespace mounts too, so its functions are served, or a name both modules export
+  // fails as a duplicate route instead of the second module silently answering nothing.
+  const indexes = MODULE_INDEXES.get(module) ?? new Map<string, number>()
+  MODULE_INDEXES.set(module, indexes)
+  let index = indexes.get(namespace)
+  if (index === undefined) {
+    index = NEXT_MODULE_INDEX.get(namespace) ?? 0
+    NEXT_MODULE_INDEX.set(namespace, index + 1)
+    indexes.set(namespace, index)
+  }
+  const suffix = index === 0 ? "" : `#${index + 1}`
+  return defineIdentityPlugin(`nifra:server-fn:${namespace}${suffix}`, apply)
 }
+
+// Weak, so a module an app no longer uses (a dev reload, a discarded test app) is not held here.
+const MODULE_INDEXES = new WeakMap<ServerFnModule, Map<string, number>>()
+const NEXT_MODULE_INDEX = new Map<string, number>()

package/src/fs.ts

@@ -3,10 +3,11 @@
  * (and the rest of @nifrajs/web) stays fs-free + edge-portable: this runs at build/startup
  * only. It scans a routes dir and feeds the pure `buildManifest`.
  */
-import { readdirSync } from "node:fs"
+import { readdirSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import {
   buildManifest,
+  exportsKeepAlive,
   isMiddlewareFile,
   isRouteBackendFile,
   type Manifest,
@@ -45,12 +46,25 @@ export function discoverRoutes(dir: string, options: DiscoverRoutesOptions = {})
     )
   const query = options.importQuery ? `?${options.importQuery}` : ""
   const load = options.load
-  return buildManifest(files, (file) =>
-    load === undefined
-      ? () => import(`${dir}/${file}${query}`) as Promise<RouteModule>
-      : // No `importQuery` here: an injected loader owns its own invalidation (Vite's module graph
-        // re-evaluates on change), and appending a cache-buster would defeat it by minting a new
-        // module id per request.
-        () => load(join(dir, file)) as Promise<RouteModule>,
+  return buildManifest(
+    files,
+    (file) =>
+      load === undefined
+        ? () => import(`${dir}/${file}${query}`) as Promise<RouteModule>
+        : // No `importQuery` here: an injected loader owns its own invalidation (Vite's module graph
+          // re-evaluates on change), and appending a cache-buster would defeat it by minting a new
+          // module id per request.
+          () => load(join(dir, file)) as Promise<RouteModule>,
+    { keepAlive: files.filter((file) => keepsAlive(join(dir, file))) },
   )
 }
+
+const keepsAlive = (path: string): boolean => {
+  if (isRouteBackendFile(path) || path.slice(path.lastIndexOf("/") + 1).startsWith("_"))
+    return false
+  try {
+    return exportsKeepAlive(readFileSync(path, "utf8"))
+  } catch {
+    return false
+  }
+}

package/src/identity.ts

@@ -0,0 +1,61 @@
+/**
+ * The identity epoch: a value the server rotates whenever a response signs a visitor in or out, so a
+ * page kept mounted for one visitor is never shown to the next. Browser-safe and free of module-level
+ * state, so a client bundle that never calls it carries none of it.
+ */
+
+/** The readable cookie holding the epoch on an `https:` origin. */
+export const EPOCH_COOKIE = "__Host-nifra-epoch"
+/** The same cookie on local `http:` dev, where a `__Host-` cookie cannot be set. */
+export const LOCAL_EPOCH_COOKIE = "nifra-epoch"
+/** The channel every tab of an origin hears a sign-in or sign-out on. */
+export const IDENTITY_CHANNEL = "nifra-identity-v1"
+
+type Listeners = Set<() => void>
+
+// Looked up per call: a module-level `Symbol.for` would be code every client bundle keeps.
+const listenersOf = (): Listeners => {
+  const key = Symbol.for("nifra.identity.listeners")
+  let listeners: unknown = Reflect.get(globalThis, key)
+  if (!(listeners instanceof Set)) {
+    listeners = new Set<() => void>()
+    Reflect.set(globalThis, key, listeners)
+  }
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only this module writes the slot, always a set of listeners
+  return listeners as Listeners
+}
+
+/** The epoch in a `document.cookie` string, or `""` when it carries none. */
+export function epochOf(cookie: string): string {
+  let local = ""
+  for (const part of cookie.split(";")) {
+    const at = part.indexOf("=")
+    if (at === -1) continue
+    const name = part.slice(0, at).trim()
+    if (name === EPOCH_COOKIE) return part.slice(at + 1).trim()
+    if (name === LOCAL_EPOCH_COOKIE) local = part.slice(at + 1).trim()
+  }
+  return local
+}
+
+/** Run `listener` when this document hears that the visitor changed; returns its removal. */
+export function onIdentityChange(listener: () => void): () => void {
+  const listeners = listenersOf()
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+/**
+ * Tell this tab and every other tab of the origin that the visitor signed in or out. Call it at login
+ * and logout when identity lives in client storage (a bearer token) rather than in a cookie, which the
+ * server's epoch cookie already covers: every page kept alive for the previous visitor is dropped.
+ */
+export function identityChanged(): void {
+  for (const listener of [...listenersOf()]) listener()
+  if (typeof BroadcastChannel === "undefined") return
+  const channel = new BroadcastChannel(IDENTITY_CHANNEL)
+  channel.postMessage("changed")
+  channel.close()
+}

package/src/index.ts

@@ -29,6 +29,9 @@ export {
   type PendingBoundary,
   resolveDynamicBoundaries,
   resolveStaticBoundaries,
+  type SharedBoundary,
+  type SharedHoleCtx,
+  type ShellCtx,
   type StaticBoundary,
   type StaticBoundaryCache,
   type StaticBoundaryImportEdge,
@@ -93,8 +96,15 @@ export {
   generateClientEntry,
   generateRouteSearchTypes,
   generateServerManifest,
+  type LiveClientEntry,
 } from "./internal/codegen.ts"
 export { mergeHeads, resolveChainMeta, resolveMeta } from "./internal/head-merge.ts"
+// The server half of the identity epoch that drops kept pages on a sign-in or sign-out.
+export {
+  type IdentityEpochContext,
+  type KeepAliveServerOptions,
+  rotateIdentityEpoch,
+} from "./internal/identity-epoch.ts"
 export type { PrerenderedPages } from "./internal/prerendered-pages.ts"
 export {
   gone,
@@ -104,6 +114,7 @@ export {
   type RenderedPage,
   type RenderPageInput,
   type RenderPageOptions,
+  type RevalidateOptions,
   type RevalidateResult,
   redirect,
   renderPage,
@@ -163,6 +174,8 @@ export {
 // File-based routing manifest - pure + fs-free. `discoverRoutes` (fs) lives in `@nifrajs/web/fs`.
 export {
   type Action,
+  type BoundaryLoaderEntry,
+  type BoundaryLoadersOf,
   buildManifest,
   type ClientAction,
   type ClientActionArgs,
@@ -176,6 +189,7 @@ export {
   filePathToPatterns,
   type GetStaticPaths,
   type InertScriptType,
+  type KeepAliveOptions,
   type LayoutEntry,
   type LinkDescriptor,
   type Loader,
@@ -210,6 +224,7 @@ export {
   type BlockerLocation,
   type BlockerState,
   type BrowserNavigate,
+  closeBoundary,
   getBrowserNavigate,
   IDLE_BLOCKER,
   type NavigateFunction,
@@ -292,11 +307,15 @@ export {
   createClientRouter,
   createMatcher,
   DATA_HEADER,
+  type DataText,
   type Fetcher,
   type FetcherState,
   type FetchRouteData,
+  type Intercepted,
+  type KeptPage,
   type MountRouterOptions,
   NAV_FROM_HEADER,
+  PREFETCH_HEADER,
   REDIRECT_HEADER,
   RETAIN_HEADER,
   REVALIDATE_HEADER,

package/src/internal/cdn/cloudflare.ts

@@ -32,7 +32,8 @@ export interface CloudflareZoneOptions {
 /**
  * A Cloudflare zone proxying the origin. HTML is only cached by a Cache Rule that makes it eligible,
  * and the zone's cache ignores `Vary`: the rule must also bypass the cache when the request carries
- * `x-nifra-data` (soft navigations fetch the page URL with that header). `nifra cdn-check` tests both.
+ * `x-nifra-data` or `x-nifra-swap` (soft navigations and slot swaps fetch the page URL with those
+ * headers). `nifra cdn-check` tests all three.
  */
 export function cloudflareZone(options: CloudflareZoneOptions): CdnProvider {
   if (!/^[a-f0-9]{32}$/.test(options.zoneId)) {

package/src/internal/certified-components.ts

@@ -3,5 +3,5 @@
  * guard and the consumer check read these; `component-certification.test.ts` holds the exact pins
  * in every manifest that runs the pipeline to them, so a range bump cannot drift past the guard.
  */
-export const CERTIFIED_COMPONENT_VITE = "8.2.1"
+export const CERTIFIED_COMPONENT_VITE = "8.3.4"
 export const CERTIFIED_COMPONENT_REACT = "19.3.1"

package/src/internal/codegen.ts

@@ -16,6 +16,7 @@ import {
 } from "../render-seam.ts"
 import { PRERENDERED_GLOBAL } from "../router.ts"
 import { jsStringLiteral, jsValueLiteral } from "./js-string.ts"
+import { keepAliveTable } from "./keep-alive-table.ts"
 
 /** The refusal for a server build given no client entry, shared by the codegen and `buildServer`. */
 export function missingClientEntry(clientEntry: unknown): TypeError {
@@ -53,6 +54,22 @@ export interface GenerateClientEntryOptions {
   /** The build moved copy tables into per-locale chunks: the handover carries the chunk URLs, and a
    * navigation loads the copy of the URL it goes to beside the route's code. */
   readonly copyChunks?: boolean
+  /**
+   * The server runs `createWebApp({ live })`: route loads go through its live load endpoint and the
+   * entry keeps what is on screen fresh (`@nifrajs/web/live-client`). Absent, the entry is exactly the
+   * non-live one.
+   */
+  readonly live?: LiveClientEntry | undefined
+}
+
+// The router as the entry names it: in a keep-alive app, the keep-alive layer over `router`.
+const keepAround = (keep: unknown, router: string): string =>
+  keep === undefined ? `const router = ${router}` : `const router = __keep.attach(${router})`
+
+/** A client entry for a live server: `{}`, or the endpoints when the runtime moves them. */
+export interface LiveClientEntry {
+  readonly path?: string
+  readonly loadPath?: string
 }
 
 /**
@@ -65,11 +82,31 @@ export interface GenerateClientEntryOptions {
  * Bun has no `import.meta.glob`, so file-based routing needs this. Write the result to a file and
  * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
  */
+/** The client modules whose package has a keep-alive mount beside them, at `<package>/keep-alive`. */
+const KEEP_ALIVE_ADAPTERS: readonly string[] = [
+  "@nifrajs/web-react/client",
+  "@nifrajs/web-svelte/client",
+  "@nifrajs/web-preact/client",
+  "@nifrajs/web-solid/client",
+  "@nifrajs/web-vue/client",
+]
+
 export function generateClientEntry(
   manifest: Manifest,
   options: GenerateClientEntryOptions,
 ): string {
-  const { clientModule, resolve } = options
+  const { resolve } = options
+  const keep = keepAliveTable(manifest)
+  if (keep !== undefined && !KEEP_ALIVE_ADAPTERS.includes(options.clientModule)) {
+    throw new Error(
+      `[nifra/web] ${keep.routes.map((id) => `"${id}"`).join(", ")} export keepAlive, which needs the React, Preact, Solid, Svelte or Vue adapter; this app's client module is ${jsStringLiteral(options.clientModule)}. Remove the keepAlive export or switch the adapter.`,
+    )
+  }
+  // A keep-alive app mounts through the adapter's keep-alive module, which re-exports its client.
+  const clientModule =
+    keep === undefined
+      ? options.clientModule
+      : options.clientModule.replace(/\/client$/, "/keep-alive")
 
   const loaderRows: string[] = []
   const patternRows: string[] = []
@@ -165,6 +202,13 @@ export function generateClientEntry(
     )
   }
 
+  const live = options.live
+  const liveFetch =
+    keep !== undefined
+      ? ", fetchData: __keep.fetchData"
+      : live === undefined
+        ? ""
+        : ", fetchData: __live.fetchData"
   return `${[
     // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
     // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
@@ -173,6 +217,8 @@ export function generateClientEntry(
     ...(options.serverComponents
       ? ['import { bindComponentRouter } from "@nifrajs/web/server-components/client"']
       : []),
+    ...(live === undefined ? [] : ['import { liveClient } from "@nifrajs/web/live-client"']),
+    ...(keep === undefined ? [] : ['import { keepAliveClient } from "@nifrajs/web/keep-alive"']),
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
     ...(loadings.length > 0
@@ -235,7 +281,22 @@ export function generateClientEntry(
     "const holds = {}",
     // routeId → the ids and `handle` exports `useMatches` reports (layouts, then the page).
     `const layoutIdsOf = ${jsValueLiteral(layoutIdsOf)}`,
+    ...(live === undefined
+      ? []
+      : [
+          `const __live = liveClient({ ${[
+            "layoutIdsOf",
+            ...(live.path === undefined ? [] : [`path: ${jsStringLiteral(live.path)}`]),
+            ...(live.loadPath === undefined ? [] : [`loadPath: ${jsStringLiteral(live.loadPath)}`]),
+          ].join(", ")} })`,
+        ]),
     "const matchChains = {}",
+    ...(keep === undefined
+      ? []
+      : [
+          `const keepAliveTable = ${jsValueLiteral(keep)}`,
+          `const __keep = keepAliveClient({ table: keepAliveTable, routeHooks, matchChains${live === undefined ? "" : ", fetchData: __live.fetchData"} })`,
+        ]),
     `const ${options.copyChunks === true ? "loadRoute" : "loadModule"} = async (id) => {`,
     "  if (chains[id]) return",
     "  const mods = await loaders[id]()",
@@ -271,7 +332,7 @@ export function generateClientEntry(
     // backend half, which no browser bundle contains.
     "  const boundaryMods = errorRouteIds.has(id) ? mods.slice(0, -1) : mods",
     "  const boundaries = boundaryMods.flatMap((m) => (m.boundaries ?? []).map((b) => ({ name: b.name, mode: b.mode, ...(b.errorId === undefined ? {} : { errorId: b.errorId }) })))",
-    "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
+    `  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, shareData: page.shareData, ${keep === undefined ? "" : "keepAlive: page.keepAlive, "}boundaries }`,
     "  if (page.ssr === false) holds[id] = [...chains[id].slice(0, -1), page.HydrateFallback ?? (() => null)]",
     "}",
     ...(options.copyChunks === true
@@ -334,9 +395,18 @@ export function generateClientEntry(
     ...loadingLines,
     // With `_loading` pages the store is wrapped: a slow navigation then names a loading chain (the
     // shared layouts + the `_loading` component) for the mounted view to render in the meantime.
-    loadings.length > 0
-      ? `const router = withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })`
-      : `const router = createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks })`,
+    keepAround(
+      keep,
+      loadings.length > 0
+        ? `withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks${liveFetch} }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })`
+        : `createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks${liveFetch} })`,
+    ),
+    // Kept pages hold the code they were rendered with: a hot update drops them.
+    ...(keep === undefined
+      ? []
+      : [
+          'if (import.meta.hot) for (const event of ["bun:afterUpdate", "vite:afterUpdate"]) import.meta.hot.on(event, () => router.dropKept("hot-update"))',
+        ]),
     ...(options.serverComponents ? ["bindComponentRouter(router)"] : []),
     "installHistory(router)",
     "installForms(router)",
@@ -392,11 +462,13 @@ export function generateClientEntry(
     "      for (const listener of [...listeners]) listener()",
     "    }, 0)",
     "  }",
-    "  mountRouter({ router: view, routes: chains, searchSchemas, matchChains, container: root })",
+    `  mountRouter({ router: view, routes: chains, searchSchemas, matchChains, container: root${keep === undefined ? "" : ", keepAlive: keepAliveTable"} })`,
     // Run the optional client loader only after the adapter has mounted the SSR tree. The initial
     // server data is already in `window.__NIFRA_DATA__`, so `serverLoader()` reuses it and cannot
     // duplicate the first request.
     "  router.hydrate().catch((error) => console.error('[nifra/web] clientLoader failed:', error))",
+    // Once mounted: the first live load and the socket must not race the hydration.
+    ...(live === undefined ? [] : ["  __live.attach(router)"]),
     // Next frame: the adapter has committed its initial hydration, so handlers are attached. Flip the
     // document to interactive (`data-nifra-hydrated` + `nifra:hydrated`) for apps to gate pre-hydration UI.
     "  requestAnimationFrame(signalHydrated)",
@@ -521,6 +593,13 @@ function moduleSpecifier(resolved: string): string {
 // A route's namespace is not assignable to `RouteModule` under a strict `tsc` (a backend half has no
 // `default`, a typed `meta` narrows its data), so the table holds plain objects and the cast happens at
 // `buildManifest`'s boundary - the same cast `discoverRoutes` applies to its dynamic import.
+// The routes the scan found exporting `keepAlive`, which a disk-less server cannot scan again.
+const keepAliveArg = (manifest: Manifest): string => {
+  const files = [
+    ...new Set(manifest.routes.filter((route) => route.keepAlive).map((route) => route.file)),
+  ]
+  return files.length === 0 ? "" : `, { keepAlive: ${jsValueLiteral(files)} }`
+}
 const LAZY_IMPORTER = "(file) => loaders[file] as () => Promise<RouteModule>"
 const EAGER_IMPORTER = "(file) => () => Promise.resolve(modules[file] as RouteModule)"
 
@@ -604,7 +683,7 @@ export function generateServerManifest(
       cssLoadingLine,
       ...copyChunksLines,
       ...buildAssetsLines,
-      `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER})`,
+      `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER}${keepAliveArg(manifest)})`,
     ].join("\n")}\n`
   }
   // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
@@ -625,6 +704,6 @@ export function generateServerManifest(
     cssLoadingLine,
     ...copyChunksLines,
     ...buildAssetsLines,
-    `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER})`,
+    `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER}${keepAliveArg(manifest)})`,
   ].join("\n")}\n`
 }