@nifrajs/web 5.5.1 → 5.7.0

package/src/dev.ts

@@ -67,8 +67,15 @@ import {
 import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
 import { formatBuildLog } from "./diagnostic.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEFAULT_DEV_PORT, generateClientEntry, type LiveClientEntry } from "./index.ts"
 import { DEV_ENTRY_FILE } from "./internal/dev-reserved.ts"
+import {
+  type BunUpgradeServer,
+  bunDevWebSocket,
+  isWebSocketUpgrade,
+  type UpgradableApp,
+  upgradeOnBun,
+} from "./internal/dev-websocket.ts"
 import { DEV_HMR_ENV, DEV_ROOT_ENV, DEV_ROUTES_ENV } from "./plugins/kit.ts"
 import { servePublicDir } from "./public-dir.ts"
 
@@ -76,7 +83,7 @@ export type { DevAppHooks } from "./dev-session.ts"
 export { LAST_ERROR_PATH } from "./diagnostic.ts"
 
 /** Minimal app surface the dev server needs - `createWebApp(...)` satisfies it. */
-interface FetchApp {
+interface FetchApp extends UpgradableApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
@@ -169,7 +176,8 @@ interface BunServeOptions {
   readonly hostname: "127.0.0.1"
   readonly development: { readonly hmr: boolean }
   readonly routes: Record<string, HtmlBundle>
-  fetch(request: Request): Promise<Response>
+  fetch(request: Request, server: BunUpgradeServer): Promise<Response | undefined>
+  readonly websocket: typeof bunDevWebSocket
 }
 interface BunServerHandle {
   readonly port: number
@@ -214,6 +222,7 @@ export function devHtml(entryHref: string): string {
 interface WriteDevFilesOptions {
   readonly routesDir: string
   readonly clientModule: string
+  readonly live?: LiveClientEntry | undefined
   readonly entryPath: string
   readonly htmlPath: string
 }
@@ -226,7 +235,7 @@ interface WriteDevFilesOptions {
  * the way the runtime does, so a leading slash there would mean the filesystem root.
  */
 export function writeDevFiles(options: WriteDevFilesOptions): void {
-  const { routesDir, clientModule, entryPath, htmlPath } = options
+  const { routesDir, clientModule, entryPath, htmlPath, live } = options
   mkdirSync(dirname(entryPath), { recursive: true })
   const manifest = discoverRoutes(routesDir)
   const entryDir = dirname(entryPath)
@@ -244,7 +253,10 @@ export function writeDevFiles(options: WriteDevFilesOptions): void {
   // already been passed to createRoot()") and only then does the callback get to reload - trading an
   // accurate warning for a real error. Editing a component-only module never reaches this path: Bun
   // applies React Fast Refresh there and state is preserved.
-  writeIfChanged(entryPath, generateClientEntry(manifest, { clientModule, resolve: toSpecifier }))
+  writeIfChanged(
+    entryPath,
+    generateClientEntry(manifest, { clientModule, resolve: toSpecifier, live }),
+  )
   const entryHref = `./${relative(dirname(htmlPath), entryPath).replaceAll("\\", "/")}`
   writeIfChanged(htmlPath, devHtml(entryHref))
 }
@@ -355,7 +367,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       ? async (): Promise<undefined> => undefined
       : servePublicDir({ dir: resolve(publicDir) })
 
-  writeDevFiles({ routesDir, clientModule, entryPath, htmlPath })
+  writeDevFiles({ routesDir, clientModule, entryPath, htmlPath, live: options.live })
   // Importing the generated HTML is what hands it to Bun's bundler. A runtime-computed path is fine:
   // Bun resolves and bundles the HTML, and everything it references, at import time.
   const htmlModule = (await import(htmlPath)) as { default: HtmlBundle }
@@ -486,7 +498,8 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       development: { hmr: true },
       // The probe route is the ONLY path Bun owns; everything else falls through to nifra's SSR.
       routes: { [PROBE_PATH]: htmlModule.default },
-      fetch: async (req: Request): Promise<Response> => {
+      websocket: bunDevWebSocket,
+      fetch: async (req: Request, bun: BunUpgradeServer): Promise<Response | undefined> => {
         const url = new URL(req.url)
         const host = req.headers.get("host") ?? url.host
         if (!isLoopbackHost(host) && !allowedHosts.has(hostName(host)))
@@ -494,6 +507,14 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
             `[nifra/web/dev] ${hostName(host)} is not a loopback host; add it to allowedHosts if this server should answer it.\n`,
             { status: 403, headers: { "content-type": "text/plain; charset=utf-8" } },
           )
+        if (isWebSocketUpgrade(req)) {
+          const answer = await upgradeOnBun(
+            await appForRequest((await currentEntry()).src),
+            req,
+            bun,
+          )
+          if (answer !== "pass") return answer
+        }
         // The stable client-entry URL. Pages reference THIS; it redirects to whichever hashed chunk Bun
         // is serving at the moment the browser asks. A redirect rather than a proxy so the module's final
         // URL is Bun's own - its HMR client derives its socket and module identity from `import.meta.url`,
@@ -554,7 +575,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       syncWatchedFiles(false)
       session.markChange()
       try {
-        writeDevFiles({ routesDir, clientModule, entryPath, htmlPath })
+        writeDevFiles({ routesDir, clientModule, entryPath, htmlPath, live: options.live })
       } catch (err) {
         // A half-saved file can fail the scan mid-edit; the next change re-runs this.
         console.error("[nifra/web/dev] client entry regeneration failed:", err)

package/src/diagnostic-catalog.ts

@@ -17,6 +17,8 @@ interface CatalogEntry {
   readonly fix: string
   readonly docsAnchor: string
   readonly options?: readonly FixOption[]
+  /** Reported by a console warning, not thrown: the dev feed records the warning as an entry. */
+  readonly console?: true
 }
 
 /**
@@ -191,6 +193,52 @@ export const DIAGNOSTIC_CATALOG: readonly CatalogEntry[] = [
     fix: "Read the reason in the line: a 401 or 403 means the token lacks purge permission for this zone, project or service; a 5xx or network_error is retried on its own.",
     docsAnchor: "errors#cdn-purge-failed",
   },
+  {
+    code: "NIFRA_KEEPALIVE_IDENTITY_COOKIE",
+    match: (_n, m) => m.includes("NIFRA_KEEPALIVE_IDENTITY_COOKIE"),
+    console: true,
+    cause:
+      "The app keeps pages alive, and a response changed an HttpOnly cookie nifra does not know as a sign-in cookie. If that cookie says who is signed in, a sign-in or sign-out through it leaves the previous visitor's kept pages in every tab, and back shows them.",
+    fix: "Name the cookie in createWebApp({ keepAlive: { identityCookies } }) if it carries the session, or in keepAlive.ignoreCookies if it does not.",
+    docsAnchor: "errors#keepalive-identity-cookie",
+    options: [
+      {
+        label: "It is the session cookie",
+        fix: 'Add it to createWebApp({ keepAlive: { identityCookies: ["<name>"] } }): a response that changes or deletes it rotates the identity epoch, and every tab drops its kept pages.',
+      },
+      {
+        label: "It says nothing about the visitor",
+        fix: 'Add it to createWebApp({ keepAlive: { ignoreCookies: ["<name>"] } }) so development stops reporting it.',
+      },
+      {
+        label: "Identity lives in a token",
+        fix: "When the session is a bearer token in client storage, call identityChanged() from @nifrajs/web/client at sign-in and sign-out; it drops kept pages in every tab.",
+      },
+    ],
+  },
+  {
+    code: "NIFRA_KEEPALIVE_DIRECT_CHILD_CSS",
+    match: (_n, m) => m.includes("NIFRA_KEEPALIVE_DIRECT_CHILD_CSS"),
+    console: true,
+    cause:
+      "A keepAlive page renders inside two display:contents wrappers, so a selector that reached its top-level element as a direct child (or by its position among siblings) no longer matches it.",
+    fix: "Rewrite the selector the message names: a descendant combinator, the wrapper as the parent, or a class on the page's root element.",
+    docsAnchor: "errors#keepalive-direct-child-css",
+    options: [
+      {
+        label: "Use a descendant combinator",
+        fix: "Write `main section` instead of `main > section`: the wrappers sit between the two.",
+      },
+      {
+        label: "Target the wrapper",
+        fix: "Write `[data-nifra-page] > section`: the inner wrapper is the page's parent while it is shown.",
+      },
+      {
+        label: "Put a class on the page root",
+        fix: "Give the page's root element a class and select it directly, instead of by its parent or its position.",
+      },
+    ],
+  },
   {
     code: "NIFRA_SCHEMA_PARSE",
     match: (n, m) =>
@@ -215,6 +263,11 @@ const HYDRATION_MESSAGES: readonly RegExp[] = [
   /Minified React error #(?:418|423|425)\b/,
 ]
 
+/** True when a console `message` reports a catalog failure that is only ever logged, never thrown. */
+export function isConsoleDiagnostic(message: string): boolean {
+  return DIAGNOSTIC_CATALOG.some((entry) => entry.console === true && entry.match("", message))
+}
+
 /** True when `message` is a framework's report of a server/browser render mismatch. */
 export function isHydrationMismatch(message: string): boolean {
   return HYDRATION_MESSAGES.some((pattern) => pattern.test(message))

package/src/diagnostic.ts

@@ -20,6 +20,7 @@ export {
   classify,
   DIAGNOSTIC_CATALOG,
   type FixOption,
+  isConsoleDiagnostic,
   isHydrationMismatch,
 } from "./diagnostic-catalog.ts"
 export {

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,25 +96,29 @@ 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,
-  notFound,
   type RedirectOptions,
   type RenderAssemblyCache,
   type RenderedPage,
   type RenderPageInput,
   type RenderPageOptions,
+  type RevalidateOptions,
   type RevalidateResult,
   redirect,
   renderPage,
   renderPageResult,
   revalidate,
-  type StatusPageOptions,
   serializeData,
-  statusPage,
   unsafeInlineScript,
 } from "./internal/render-document.ts"
 export {
@@ -126,6 +133,7 @@ export {
  * stubbed by both build pipelines and waved through by the guard meant to stop it leaking.
  */
 export { SERVER_FN_MODULE } from "./internal/server-boundary.ts"
+export { gone, notFound, type StatusPageOptions, statusPage } from "./internal/status-page.ts"
 export {
   type CreateWebAppOptions,
   createWebApp,
@@ -163,6 +171,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 +186,7 @@ export {
   filePathToPatterns,
   type GetStaticPaths,
   type InertScriptType,
+  type KeepAliveOptions,
   type LayoutEntry,
   type LinkDescriptor,
   type Loader,
@@ -210,6 +221,7 @@ export {
   type BlockerLocation,
   type BlockerState,
   type BrowserNavigate,
+  closeBoundary,
   getBrowserNavigate,
   IDLE_BLOCKER,
   type NavigateFunction,
@@ -292,11 +304,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"