@nifrajs/web 3.3.0 → 4.0.0

package/src/bun-dev-entry.ts

@@ -3,7 +3,7 @@
  *
  * ## Why this file exists at all
  *
- * Bun's dev server bundles an HTML route and rewrites its `<script src="./entry.tsx">` into a
+ * Bun's dev server bundles an HTML route and rewrites its `<script src="./nifra-dev-entry.tsx">` into a
  * content-hashed URL under `/_bun/client/`. That rewrite is the whole point: the hash changes per build,
  * so the URL cannot be predicted or hard-coded.
  *

package/src/cdn.ts

@@ -0,0 +1,216 @@
+/**
+ * `@nifrajs/web/cdn` - put a CDN in front of nifra pages and purge it by tag.
+ *
+ * `withCdn` wraps the app (or a `withISR` handler) and, on every page a shared cache may store, sets
+ * the CDN's tag and TTL headers: the route's `revalidateTags` plus a tag for the page's own path, and
+ * the route's `revalidate` as the CDN's freshness. Browsers get `max-age=0, must-revalidate`, because
+ * a purge reaches the CDN, never a browser. Every other HTML response is marked no-store for the CDN.
+ * `revalidateEndpoint({ cdn })` and `createInvalidator` purge the origin store first, then the CDN.
+ *
+ * Providers: Cloudflare (a proxied zone, or Workers Cache), Vercel and Fastly; `defineCdnProvider`
+ * for any other. Backend-only: a browser build that reaches this module fails.
+ */
+import "@nifrajs/web/backend-only"
+import { isDraftEnabled } from "./draft.ts"
+import type { CdnProvider } from "./internal/cdn/core.ts"
+import { pathTag } from "./internal/cdn/core.ts"
+import {
+  type CacheStore,
+  type CdnPurgeOutcome,
+  type CdnPurgeTarget,
+  ISR_REVALIDATE_HEADER,
+  ISR_REVALIDATE_TAGS_HEADER,
+  type ISRApp,
+  type ISRPlatform,
+  type ISRQuery,
+  isCacheablePage,
+  MAX_REVALIDATE_PATHS,
+  MAX_REVALIDATE_TAGS,
+  normalizeTags,
+  openCacheChannel,
+  tagsFromHeader,
+  urlKeyOf,
+  withoutCacheChannel,
+} from "./isr.ts"
+
+export {
+  type CloudflareWorkersCacheOptions,
+  type CloudflareZoneOptions,
+  cloudflareWorkersCache,
+  cloudflareZone,
+  type WorkersCacheLike,
+} from "./internal/cdn/cloudflare.ts"
+export {
+  type CdnCacheInput,
+  type CdnProvider,
+  type CdnProviderDefinition,
+  type CdnPurgeError,
+  defineCdnProvider,
+  type PurgeAttempt,
+  type PurgeQueueOptions,
+  pathTag,
+} from "./internal/cdn/core.ts"
+export { type FastlyOptions, fastly } from "./internal/cdn/fastly.ts"
+export { type VercelOptions, vercel } from "./internal/cdn/vercel.ts"
+export type { CdnPurgeOutcome, CdnPurgeTarget }
+
+/** What browsers are told about a page the CDN may store: revalidate every time. */
+export const CDN_BROWSER_CACHE_CONTROL = "public, max-age=0, must-revalidate"
+
+type Handler = (req: Request, platform?: ISRPlatform) => Response | Promise<Response>
+
+export interface WithCdnOptions {
+  readonly provider: CdnProvider
+  /**
+   * Seconds the CDN may keep serving a page past its freshness while it refetches. Default: the page's
+   * own freshness window. With `withISR` underneath, a page can be this much older than ISR's own.
+   */
+  readonly staleWhileRevalidate?: number
+  /** Seconds the CDN may serve a page past its freshness while the origin errors. Default: unset. */
+  readonly staleIfError?: number
+  /** The draft secret given to `createWebApp`: a draft render is never stored by the CDN. */
+  readonly draftSecret?: string
+}
+
+const nonNegative = (value: number | undefined, name: string): number | undefined => {
+  if (value === undefined) return undefined
+  if (!Number.isInteger(value) || value < 0) {
+    throw new RangeError(`[nifra/web/cdn] ${name} must be a non-negative integer number of seconds`)
+  }
+  return value
+}
+
+const isHtml = (res: Response): boolean =>
+  (res.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
+
+function withHeaders(res: Response, set: Readonly<Record<string, string>>): Response {
+  try {
+    for (const [name, value] of Object.entries(set)) res.headers.set(name, value)
+    return res
+  } catch {
+    // A `fetch()` response has immutable headers: rebuild it around the same body instead.
+    const headers = new Headers(res.headers)
+    for (const [name, value] of Object.entries(set)) headers.set(name, value)
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+  }
+}
+
+/**
+ * Wrap `app` (a `createWebApp` app or a `withISR` handler) so a CDN stores exactly the pages a shared
+ * cache may serve to anyone, tagged for purging, for as long as the route's `revalidate` allows.
+ * Non-HTML responses (assets, JSON, navigation data) pass through with the app's own headers.
+ */
+export function withCdn(
+  app: ISRApp | Handler,
+  options: WithCdnOptions,
+): (req: Request, platform?: ISRPlatform) => Promise<Response> {
+  const { provider, draftSecret } = options
+  const swr = nonNegative(options.staleWhileRevalidate, "staleWhileRevalidate")
+  const staleIfError = nonNegative(options.staleIfError, "staleIfError")
+  openCacheChannel(app)
+  const fetchOf: Handler =
+    typeof app === "function" ? app : (req, platform) => app.fetch(req, platform)
+  return async (req, platform) => {
+    const res = await fetchOf(req, platform)
+    const advertised = res.headers.get(ISR_REVALIDATE_HEADER)
+    const tags = tagsFromHeader(res.headers.get(ISR_REVALIDATE_TAGS_HEADER))
+    const out = withoutCacheChannel(res)
+    if (!isHtml(out)) return out
+    const seconds = advertised === null ? Number.NaN : Math.floor(Number(advertised))
+    const storable =
+      Number.isFinite(seconds) &&
+      seconds > 0 &&
+      isCacheablePage(req, out) &&
+      !(draftSecret !== undefined && (await isDraftEnabled(req, draftSecret)))
+    if (!storable) return withHeaders(out, provider.noStoreHeaders())
+    const pageTags = [...tags, await pathTag(new URL(req.url).pathname)]
+    return withHeaders(out, {
+      ...provider.cacheHeaders({
+        tags: pageTags.slice(-provider.maxResponseTags),
+        maxAge: seconds,
+        staleWhileRevalidate: swr ?? seconds,
+        staleIfError,
+      }),
+      "cache-control": CDN_BROWSER_CACHE_CONTROL,
+    })
+  }
+}
+
+export interface InvalidatorOptions {
+  /** The ISR store to purge first. */
+  readonly store?: CacheStore
+  /** The CDN to purge after the store. */
+  readonly cdn?: CdnPurgeTarget
+  /**
+   * The site's public origin (`https://example.com`), for the store keys of purged paths under
+   * `withISR`'s default key. Not needed with `key`, or without a store.
+   */
+  readonly origin?: string
+  /** A store key for a path; must match the `withISR` `key`. Return `null` for a path never cached. */
+  readonly key?: (path: string) => string | null
+  /** The `query` policy given to `withISR`. Default `"bypass"`. Ignored with `key`. */
+  readonly query?: ISRQuery
+}
+
+export interface InvalidateResult {
+  readonly origin: "done" | "skipped"
+  readonly cdn: CdnPurgeOutcome["cdn"] | "skipped"
+  readonly retryable: boolean
+  readonly error?: string
+}
+
+/**
+ * Purge pages after a mutation, from app code: `await invalidate({ tags: ["product:42"] })`. The
+ * origin store goes first, so a CDN refetch cannot repopulate from a stale origin entry. At most 32
+ * tags and 100 paths a call.
+ */
+export function createInvalidator(options: InvalidatorOptions): {
+  invalidate(
+    target: { readonly tags?: readonly string[]; readonly paths?: readonly string[] },
+    platform?: ISRPlatform,
+  ): Promise<InvalidateResult>
+} {
+  const { store, cdn } = options
+  let keyOf: ((path: string) => string | null) | undefined = options.key
+  if (keyOf === undefined && store !== undefined) {
+    if (options.origin === undefined) {
+      throw new TypeError(
+        "[nifra/web/cdn] createInvalidator: a store needs `origin` (or `key`) to find a path's entry",
+      )
+    }
+    const origin = new URL(options.origin).origin
+    const urlKey = urlKeyOf(options.query)
+    keyOf = (path) => urlKey(new URL(origin + path))
+  }
+  return {
+    async invalidate(target, platform) {
+      const tags = normalizeTags(target.tags ?? [])
+      const paths = [...new Set(target.paths ?? [])]
+      if (tags.length > MAX_REVALIDATE_TAGS || paths.length > MAX_REVALIDATE_PATHS) {
+        throw new RangeError(
+          "[nifra/web/cdn] invalidate takes at most 32 tags and 100 paths a call",
+        )
+      }
+      for (const path of paths) {
+        if (typeof path !== "string" || !path.startsWith("/")) {
+          throw new TypeError("[nifra/web/cdn] invalidate paths must start with /")
+        }
+      }
+      let origin: InvalidateResult["origin"] = "skipped"
+      if (store !== undefined) {
+        if (tags.length > 0 && store.invalidateTag === undefined) {
+          throw new TypeError("[nifra/web/cdn] this store cannot invalidate by tag")
+        }
+        for (const path of paths) {
+          const key = keyOf?.(path)
+          if (key !== null && key !== undefined) await store.delete(key)
+        }
+        for (const tag of tags) await store.invalidateTag?.(tag)
+        origin = "done"
+      }
+      if (cdn === undefined) return { origin, cdn: "skipped", retryable: false }
+      const outcome = await cdn.purge({ tags, paths }, platform)
+      return { origin, ...outcome }
+    },
+  }
+}

package/src/client.ts

@@ -18,7 +18,20 @@ import {
   setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
-import type { ClientRouter } from "./router.ts"
+import { type ClientRouter, redirectOf } from "./router.ts"
+
+/** Read the nonce carried by the current server-rendered document, if any. */
+export function currentDocumentNonce(): string | undefined {
+  if (typeof document === "undefined") return undefined
+  const documentLike = document as unknown as {
+    querySelector?: (selector: string) => Element | null
+  }
+  const script = documentLike.querySelector?.("script[nonce]")
+  if (script === null || script === undefined) return undefined
+  const property = (script as Element & { readonly nonce?: unknown }).nonce
+  if (typeof property === "string" && property !== "") return property
+  return script.getAttribute("nonce") ?? undefined
+}
 
 /**
  * Everything the generated client entry needs, re-exported here so that entry imports ONE module and
@@ -53,6 +66,146 @@ export interface InstallHistoryOptions {
   readonly fallback?: (path: string) => void
 }
 
+/** Options for {@link waitForStyles}. */
+export interface WaitForStylesOptions {
+  /**
+   * Maximum time to wait for one framework-owned deferred stylesheet before hydrating anyway.
+   * Defaults to 4000 ms and is capped at 30000 ms so a bad value cannot leave the app inert forever.
+   */
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_CSS_WAIT_MS = 4_000
+const MAX_CSS_WAIT_MS = 30_000
+type CssLinkState = "loaded" | "error" | "timeout"
+
+// Per-link promises keep repeated calls idempotent without retaining an entire document after a hard
+// navigation. A WeakMap also lets tests and embedded documents replace `globalThis.document` safely.
+const stylesheetWaits = new WeakMap<HTMLLinkElement, Promise<void>>()
+
+const cssLinkStateOf = (link: HTMLLinkElement): CssLinkState | undefined => {
+  const state = link.getAttribute("data-nifra-css-state")
+  return state === "loaded" || state === "error" || state === "timeout" ? state : undefined
+}
+
+const hasLoadedStylesheet = (link: HTMLLinkElement): boolean => {
+  // Accessing `sheet` is safe for cross-origin stylesheets, but a browser may still throw while it is
+  // tearing down a document. Treat that as "not observed yet"; the load/error listener or the bounded
+  // timer is the authoritative fallback.
+  try {
+    return link.sheet !== null
+  } catch {
+    return false
+  }
+}
+
+const stylesheetLabel = (link: HTMLLinkElement): string =>
+  link.getAttribute("href") ?? link.href ?? "<unknown>"
+
+/**
+ * Wait for one server-emitted deferred stylesheet. The promise ALWAYS settles: a failed or slow CSS
+ * request must not leave the server-rendered page's loader visible forever. `media="all"` is applied on
+ * every terminal state so a late network completion cannot leave a link permanently in print media.
+ */
+const waitForStylesheet = (link: HTMLLinkElement, timeoutMs: number): Promise<void> =>
+  new Promise<void>((resolve) => {
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+
+    const cleanup = (): void => {
+      link.removeEventListener("load", onLoad)
+      link.removeEventListener("error", onError)
+      if (timer !== undefined) clearTimeout(timer)
+    }
+    const finish = (state: CssLinkState): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      link.setAttribute("data-nifra-css-state", state)
+      // Only the coordinator promotes the framework-owned link, after the resource has settled.
+      link.media = "all"
+      resolve()
+    }
+    const onLoad = (): void => finish("loaded")
+    const onError = (): void => {
+      console.error(`[nifra/web] stylesheet failed to load: ${stylesheetLabel(link)}`)
+      finish("error")
+    }
+
+    const prior = cssLinkStateOf(link)
+    if (prior !== undefined) {
+      finish(prior)
+      return
+    }
+    if (hasLoadedStylesheet(link)) {
+      finish("loaded")
+      return
+    }
+
+    // Attach listeners before the second loaded-sheet check: a cached resource can transition between
+    // the first check and listener registration, and the second check closes that small race.
+    link.addEventListener("load", onLoad, { once: true })
+    link.addEventListener("error", onError, { once: true })
+    timer = setTimeout(() => {
+      console.warn(
+        `[nifra/web] stylesheet load timed out after ${timeoutMs}ms: ${stylesheetLabel(link)}`,
+      )
+      finish("timeout")
+    }, timeoutMs)
+    if (hasLoadedStylesheet(link)) finish("loaded")
+  })
+
+const validateCssWaitMs = (value: number): number => {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `[nifra/web] css wait timeout must be a finite positive number, received ${value}`,
+    )
+  }
+  return Math.min(value, MAX_CSS_WAIT_MS)
+}
+
+/**
+ * Wait for the framework-owned deferred stylesheet links in the initial document, then promote them to
+ * `media="all"`. It is safe to call more than once: repeated calls for one document share the same
+ * per-link waits, and duplicate framework links are removed before waiting. Blocking links are not
+ * touched.
+ *
+ * This function lives in the browser-only `@nifrajs/web/client` entry. It is nevertheless defensive
+ * when imported in a non-DOM environment so an accidental import cannot crash a server process.
+ */
+export function waitForStyles(options: WaitForStylesOptions = {}): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve()
+  const timeoutMs = validateCssWaitMs(options.timeoutMs ?? DEFAULT_CSS_WAIT_MS)
+  const links = Array.from(
+    document.querySelectorAll<HTMLLinkElement>('link[data-nifra-css="deferred"]'),
+  ).filter(
+    (link) =>
+      link.getAttribute("data-nifra-css") === "deferred" && link.rel.toLowerCase() === "stylesheet",
+  )
+  const unique: HTMLLinkElement[] = []
+  const seen = new Set<string>()
+  for (const link of links) {
+    const key = stylesheetLabel(link)
+    if (seen.has(key)) {
+      // Only remove a duplicate carrying the framework marker; author-owned links are outside this
+      // selector and cannot be affected. Keeping the first link preserves its event state and cache.
+      link.remove()
+      continue
+    }
+    seen.add(key)
+    unique.push(link)
+  }
+  if (unique.length === 0) return Promise.resolve()
+  const promises = unique.map((link) => {
+    const existing = stylesheetWaits.get(link)
+    if (existing !== undefined) return existing
+    const promise = waitForStylesheet(link, timeoutMs)
+    stylesheetWaits.set(link, promise)
+    return promise
+  })
+  return Promise.all(promises).then(() => undefined)
+}
+
 /**
  * Attach history + link interception to a router. Returns a teardown function that removes the
  * listeners. A data-fetch failure during a client navigation falls back to a full-page load, so
@@ -80,6 +233,8 @@ export function installHistory(
   let index = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
   let here = location.pathname + location.search + (location.hash ?? "")
   let reversing = false
+  // The path the router was last seen loading, so a redirect it follows shows up as a change.
+  let expected: string | undefined
   type Registration = {
     readonly shouldBlock: BlockerFunction
     readonly emit: (blocker: Blocker) => void
@@ -215,11 +370,20 @@ export function installHistory(
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     }
     here = url.pathname + url.search + url.hash
+    expected = routePath
     // The data layer fetches by path+search; the #hash is client-only (never sent to the server).
-    transition(() => router.navigate(routePath).catch(() => fallback(path)))
+    transition(() => router.navigate(routePath).catch((error) => leave(error, path)))
     settle()
   }
 
+  // A redirect out of the app replaces the entry it answered, as the browser's own redirect would; any
+  // other failure loads the page as a document.
+  const leave = (error: unknown, path: string): void => {
+    const to = redirectOf(error)
+    if (to === undefined) fallback(path)
+    else location.replace(to)
+  }
+
   const go = (path: string, mode: "push" | "replace", state?: unknown): void => {
     // Validate before the blocker observes the target. A blocker receives parsed locations, so letting a
     // malformed string reach `locationOf` would make an otherwise no-throw navigate unexpectedly throw.
@@ -244,7 +408,7 @@ export function installHistory(
     }
     go(to, navOptions?.replace === true ? "replace" : "push", navOptions?.state)
   }
-  setBrowserNavigate(navigate)
+  setBrowserNavigate(navigate, router)
 
   // Publish the guard registry through the DOM-free bridge (`@nifrajs/web`'s `registerBlocker`, which an
   // adapter's `useBlocker` calls). One slot, latest registration wins; the unregister clears it only if
@@ -291,12 +455,45 @@ export function installHistory(
     go(href, "push")
   }
 
-  // Hover/focus an in-app link → warm its chunk + data (the store dedupes the spam).
-  const onPrefetch = (event: Event): void => {
-    const href = inAppHref(event.target)
+  // `data-nifra-prefetch` on a link or any ancestor (the nearest wins) says when the link warms its
+  // route's chunk and data: `intent` (the default) on hover or focus, `viewport` once it scrolls into
+  // view, `render` as soon as a page shows it, `none` never.
+  const prefetchModeOf = (el: Element): string | undefined =>
+    (el.closest("[data-nifra-prefetch]") as HTMLElement | null)?.dataset.nifraPrefetch
+
+  // Warm an in-app link's route (the store dedupes the spam). The page on screen has nothing to warm.
+  const warm = (target: EventTarget | null): void => {
+    const href = inAppHref(target)
     if (href === null) return
     const url = new URL(href, location.origin)
-    void router.prefetch(url.pathname + url.search) // warm by path+search; the #hash isn't data
+    const path = url.pathname + url.search // the #hash isn't data
+    if (path !== location.pathname + location.search) void router.prefetch(path)
+  }
+
+  const onPrefetch = (event: Event): void => {
+    const target = event.target
+    if (target instanceof Element && prefetchModeOf(target) !== "none") warm(target)
+  }
+
+  // `viewport` and `render` links are looked for when history is installed (the server-rendered page)
+  // and whenever the router settles (a navigation, a submit's revalidation). A link the page adds in
+  // between warms on intent until the next settle.
+  let inView: IntersectionObserver | undefined
+  const scan = (): void => {
+    inView?.disconnect()
+    for (const anchor of document.querySelectorAll(
+      "a[data-nifra-prefetch],[data-nifra-prefetch] a",
+    )) {
+      const mode = prefetchModeOf(anchor)
+      if (mode === "render") warm(anchor)
+      else if (mode === "viewport") {
+        // Scrolling back into view asks again; the store holds a fresh prefetch, so nothing refetches.
+        inView ??= new IntersectionObserver((entries) => {
+          for (const entry of entries) if (entry.isIntersecting) warm(entry.target)
+        })
+        inView.observe(anchor)
+      }
+    }
   }
 
   // Back/forward: the entry already exists (no push). The URL has ALSO already changed - a popstate can't
@@ -320,9 +517,9 @@ export function installHistory(
     index = newIndex
     here = dest
     pendingScroll = { pos: scrollOf(history.state) }
-    transition(() =>
-      router.navigate(location.pathname + location.search).catch(() => fallback(location.pathname)),
-    )
+    const routePath = location.pathname + location.search
+    expected = routePath
+    transition(() => router.navigate(routePath).catch((error) => leave(error, dest)))
     settle()
   }
 
@@ -344,24 +541,50 @@ export function installHistory(
     event.returnValue = ""
   }
 
+  // The router is loading a page the address bar does not show: a redirect it follows. That replaces the
+  // entry a navigation pushed, or adds one after a form post, as the browser would. A redirect from a
+  // form post back to the page it was on adds nothing.
+  const follow = (path: string): void => {
+    if (path !== location.pathname + location.search) {
+      if (expected === undefined) {
+        history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
+        index += 1
+        history.pushState({ nifraIndex: index }, "", path)
+      } else {
+        history.replaceState(history.state, "", path + location.hash)
+      }
+      here = location.pathname + location.search + location.hash
+      pendingScroll = location.hash !== "" ? { hash: hashId(location.hash) } : { pos: [0, 0] }
+    }
+    expected = path
+  }
+
   // After a navigation settles (content rendered), apply the pending scroll target on the next frame:
   // a fragment's element for a cross-page `#hash`, the saved position for back/forward, else the top.
-  // Skipped for submits (pending).
-  const restoreScroll = (): void => {
-    if (router.snapshot().pending || pendingScroll === null) return
+  // A settle with no navigation (a submit's revalidation) scrolls nothing. Either way the rendered
+  // page is then scanned for links to warm.
+  const settled = (): void => {
+    const { pending, pendingPath } = router.snapshot()
+    if (pending) {
+      if (pendingPath !== undefined && pendingPath !== expected) follow(pendingPath)
+      return
+    }
+    expected = undefined
     const target = pendingScroll
     pendingScroll = null
     requestAnimationFrame(() => {
-      if ("hash" in target) {
+      if (target !== null && "hash" in target) {
         const el = findAnchor(target.hash)
         if (el !== null) el.scrollIntoView()
         else window.scrollTo(0, 0) // fragment not found → top, like a fresh page load
-      } else {
+      } else if (target !== null) {
         window.scrollTo(target.pos[0], target.pos[1])
       }
+      scan()
     })
   }
-  const unsubscribe = router.subscribe(restoreScroll)
+  const unsubscribe = router.subscribe(settled)
+  scan()
 
   document.addEventListener("click", onClick)
   document.addEventListener("pointerover", onPrefetch)
@@ -370,6 +593,7 @@ export function installHistory(
   window.addEventListener("beforeunload", onBeforeUnload)
   return () => {
     unsubscribe()
+    inView?.disconnect()
     setBrowserNavigate(undefined) // stop routing `useNavigate` to a torn-down router
     setBlockerController(undefined) // stop routing `useBlocker` to a torn-down registry
     document.removeEventListener("click", onClick)
@@ -392,6 +616,7 @@ export function installHistory(
  * the first navigation cleanly takes over from the server-rendered head.
  */
 export function applyHead(head: Meta): void {
+  const documentNonce = currentDocumentNonce()
   if (head.title !== undefined) document.title = head.title
   // `<html lang>`/`<html dir>` - applied AUTHORITATIVELY (unlike `title`, which is left alone when the
   // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
@@ -444,6 +669,11 @@ export function applyHead(head: Meta): void {
         `[nifra/web] unsupported executable script type ${JSON.stringify(s.type)}`,
       )
     }
+    if (documentNonce !== undefined && s.nonce !== documentNonce) {
+      throw new TypeError(
+        "[nifra/web] executable head scripts must use the same CSP nonce as the document",
+      )
+    }
     const el = document.createElement("script")
     el.setAttribute("type", s.type)
     el.setAttribute("nonce", s.nonce)
@@ -466,8 +696,11 @@ export function installForms(router: ClientRouter): () => void {
     // `data-nifra-revalidate="false"` opts out of the post-action loader revalidation (the action's
     // actionData drives the update); absent or any other value keeps the default revalidation.
     const revalidate = form.dataset.nifraRevalidate !== "false"
-    router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch(() => {
-      form.submit() // data submit failed - fall back to a full-page POST
+    router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch((error) => {
+      const to = redirectOf(error)
+      // The action ran: load the page that shows its result rather than run it again.
+      if (to !== undefined) location.assign(to)
+      else form.submit() // data submit failed - fall back to a full-page POST
     })
   }
   document.addEventListener("submit", onSubmit)

package/src/conformance.ts

@@ -88,9 +88,10 @@ const readHtml = async (
  * Execute the observable {@link RenderAdapter} interface against a framework-specific fixture.
  *
  * The promise resolves only when the adapter proves all shared invariants: page props reach a
- * page-only render, streams contain byte chunks, layout chains nest outermost-first, optional
- * buffered rendering is byte-for-byte hydration-equivalent to streaming for non-deferred content,
- * and hydration-head output is a stable string. It rejects with
+ * page-only render, streams contain byte chunks, layout chains nest outermost-first, a leaf that
+ * renders nothing leaves its layouts standing, optional buffered rendering is byte-for-byte
+ * hydration-equivalent to streaming for non-deferred content, and hydration-head output is a stable
+ * string. It rejects with
  * {@link RenderAdapterConformanceError} naming the first failed check.
  *
  * Framework semantics outside the interface-Suspense scheduling, compiler plugins, DOM hydration,
@@ -125,6 +126,18 @@ export async function assertRenderAdapterConformance(
     fail("layout order", "expected outer layout → inner layout → page source order")
   }
 
+  // The page slot of an `ssr = false` route with no `HydrateFallback`: a plain function returning
+  // `null`, in every framework. The layouts must render around it and the slot must be empty.
+  const emptyHtml = await readHtml(
+    () => adapter.renderToStream([outerLayout, innerLayout, () => null], props),
+    "empty leaf",
+  )
+  contains(emptyHtml, markers.outer, "empty leaf")
+  contains(emptyHtml, markers.inner, "empty leaf")
+  if (emptyHtml.includes(markers.page)) {
+    fail("empty leaf", "a leaf that renders nothing must leave the page slot empty")
+  }
+
   if (adapter.renderToString !== undefined) {
     let buffered: unknown
     try {