@nifrajs/web 4.0.2 → 5.1.0

package/src/internal/parity.ts

@@ -586,6 +586,17 @@ const linkedRepoBoundary = async (packageRoot: string): Promise<string> => {
   return packageRoot
 }
 
+/** Where a real package folder lives when only its files are links: Bun installs a `file:` folder
+ * dependency as a directory of per-file symlinks, so its imports resolve beside the linked files. */
+const fileLinkedDir = async (dir: string): Promise<string | undefined> => {
+  const manifest = join(dir, "package.json")
+  try {
+    return (await lstat(manifest)).isSymbolicLink() ? dirname(await realpath(manifest)) : undefined
+  } catch {
+    return undefined
+  }
+}
+
 const linkedPackageRoots = async (
   importerRoots: readonly string[],
   manifests: readonly Record<string, unknown>[],
@@ -605,8 +616,10 @@ const linkedPackageRoots = async (
       }
       const candidate = join(importerRoot, "node_modules", ...name.split("/"))
       const link = await lstat(candidate).catch(() => undefined)
-      if (link === undefined || !link.isSymbolicLink()) continue
-      const resolved = await realpath(candidate).catch(() => undefined)
+      if (link === undefined) continue
+      const resolved = link.isSymbolicLink()
+        ? await realpath(candidate).catch(() => undefined)
+        : await fileLinkedDir(candidate)
       if (resolved === undefined || pathInside(realScanRoot, resolved)) continue
       found.set(resolved, true)
     }

package/src/internal/private-env.ts

@@ -32,12 +32,12 @@ const BEFORE_EXPRESSION = new Set([
   "instanceof",
 ])
 
-type Token =
+export type Token =
   | { readonly kind: "id" | "punct" | "string"; readonly value: string }
   | { readonly kind: "other" }
 
 /** JavaScript tokens, with strings, template text, comments and regular expressions skipped. */
-function tokenize(code: string): Token[] {
+export function tokenize(code: string): Token[] {
   const tokens: Token[] = []
   // One entry per open `${`: how many `{` are open inside it.
   const templates: number[] = []
@@ -152,24 +152,37 @@ function envReads(tokens: readonly Token[]): EnvRead[] {
     const token = tokens[at]
     return token?.kind === "id" ? token.value : undefined
   }
-  /** A property read after an env object that ends at `at`: `.X` or `["X"]`. */
+  // The tokenizer reads `?.` as `.`, so `?.[` and `?.(` arrive as `.` before the bracket.
+  const open = (at: number, bracket: "[" | "("): number =>
+    is(at, "punct", ".") && is(at + 1, "punct", bracket) ? at + 1 : at
+  /** The string key of `["X"]` (or `?.["X"]`) at `at`, and the index after it. */
+  const keyAt = (at: number): { readonly key: string; readonly next: number } | undefined => {
+    const bracket = open(at, "[")
+    const key =
+      is(bracket, "punct", "[") && is(bracket + 2, "punct", "]") ? stringAt(bracket + 1) : undefined
+    return key === undefined ? undefined : { key, next: bracket + 3 }
+  }
+  /** A property read after an env object that ends at `at`: `.X`, `["X"]` or `?.["X"]`. */
   const member = (base: string, at: number, importMeta: boolean): EnvRead => {
     const property = is(at, "punct", ".") ? idAt(at + 1) : undefined
     if (property !== undefined)
       return { expression: `${base}.${property}`, name: property, importMeta }
-    const key = is(at, "punct", "[") && is(at + 2, "punct", "]") ? stringAt(at + 1) : undefined
+    const key = keyAt(at)?.key
     if (key !== undefined)
       return { expression: `${base}[${JSON.stringify(key)}]`, name: key, importMeta }
     return { expression: base, importMeta }
   }
+  /** The index after `.env`, `["env"]` or `?.["env"]` at `at`, or `-1`. */
+  const envAt = (at: number): number => {
+    if (is(at, "punct", ".") && is(at + 1, "id", "env")) return at + 2
+    const bracket = keyAt(at)
+    return bracket?.key === "env" ? bracket.next : -1
+  }
   for (let i = 0; i < tokens.length; i++) {
     const head = idAt(i)
-    if (
-      (head === "process" || head === "Bun") &&
-      is(i + 1, "punct", ".") &&
-      is(i + 2, "id", "env")
-    ) {
-      reads.push(member(`${head}.env`, i + 3, false))
+    const env = head === "process" || head === "Bun" ? envAt(i + 1) : -1
+    if (env !== -1) {
+      reads.push(member(`${head}.env`, env, false))
     } else if (
       head === "import" &&
       is(i + 1, "punct", ".") &&
@@ -180,12 +193,13 @@ function envReads(tokens: readonly Token[]): EnvRead[] {
       reads.push(member("import.meta.env", i + 5, true))
     } else if (head === "Deno" && is(i + 1, "punct", ".") && is(i + 2, "id", "env")) {
       const method = is(i + 3, "punct", ".") ? idAt(i + 4) : undefined
+      const call = open(i + 5, "(")
       const name =
-        (method === "get" || method === "has") && is(i + 5, "punct", "(")
-          ? stringAt(i + 6)
+        (method === "get" || method === "has") && is(call, "punct", "(")
+          ? stringAt(call + 1)
           : undefined
       reads.push(
-        name !== undefined && is(i + 7, "punct", ")")
+        name !== undefined && is(call + 2, "punct", ")")
           ? { expression: `Deno.env.${method}(${JSON.stringify(name)})`, name, importMeta: false }
           : {
               expression: method === undefined ? "Deno.env" : `Deno.env.${method}()`,

package/src/internal/progressive-cookies.ts

@@ -0,0 +1,60 @@
+import type { CookieOptions } from "@nifrajs/core/server"
+
+export interface ProgressiveCookie {
+  readonly name: string
+  readonly value: string
+  readonly options?: CookieOptions | undefined
+  readonly deleted?: boolean
+}
+
+/** Parent-domain acceptance belongs to the browser's cookie jar and public-suffix policy. A Secure
+ * cookie on a request seen as `http:` does too: behind a TLS terminator only the browser knows its
+ * scheme, so it decides whether the cookie is kept. */
+export function progressiveCookieRedirect(
+  request: Request,
+  changes: readonly ProgressiveCookie[],
+): boolean {
+  const url = new URL(request.url)
+  const host = url.hostname.toLowerCase()
+  return changes.some((change) => {
+    const domain = change.options?.domain?.replace(/^\./, "").toLowerCase()
+    if (domain !== undefined && domain !== host && host.endsWith("." + domain)) return true
+    return secureOnPlainHttp(url, change)
+  })
+}
+
+const secureOnPlainHttp = (url: URL, change: ProgressiveCookie): boolean =>
+  (change.options?.secure ?? !change.deleted) && url.protocol !== "https:"
+
+/** Reauthorize the internal GET with action cookies that are valid for this exact owner URL. */
+export function progressiveCookieHeader(
+  request: Request,
+  changes: readonly ProgressiveCookie[],
+): string {
+  const url = new URL(request.url)
+  let pairs = (request.headers.get("cookie") ?? "")
+    .split(";")
+    .map((part) => part.trim())
+    .filter(Boolean)
+  for (const change of changes) {
+    const options = change.options
+    const domain = options?.domain?.replace(/^\./, "").toLowerCase()
+    // Parent-domain cookies need a browser cookie jar/public-suffix decision; never synthesize them.
+    if (domain !== undefined && domain !== url.hostname.toLowerCase()) continue
+    if (secureOnPlainHttp(url, change)) continue
+    const path = options?.path ?? "/"
+    if (
+      url.pathname !== path &&
+      !(url.pathname.startsWith(path) && (path.endsWith("/") || url.pathname[path.length] === "/"))
+    )
+      continue
+    pairs = pairs.filter((pair) => pair.slice(0, pair.indexOf("=")).trim() !== change.name)
+    const expired =
+      options?.maxAge !== undefined
+        ? options.maxAge <= 0
+        : options?.expires !== undefined && options.expires.getTime() <= Date.now()
+    if (!change.deleted && !expired)
+      pairs.push(change.name + "=" + encodeURIComponent(change.value))
+  }
+  return pairs.join("; ")
+}

package/src/internal/public-env.ts

@@ -0,0 +1,14 @@
+export function publicEnvDefines(
+  prefix: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Record<string, string> {
+  const defines: Record<string, string> = {}
+  if (prefix === "") return defines // opt-out: bake in nothing
+  for (const [name, value] of Object.entries(env)) {
+    // Skip `undefined` (a deleted/unset key can still enumerate) so we never bake in `"undefined"`.
+    if (name.startsWith(prefix) && value !== undefined) {
+      defines[`process.env.${name}`] = JSON.stringify(value)
+    }
+  }
+  return defines
+}

package/src/internal/render-document.ts

@@ -6,15 +6,12 @@ import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../defer
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
 import type {
   Loader as LayoutLoader,
-  LinkDescriptor,
   Meta,
-  MetaDescriptor,
   MetaInput,
   RouteModule,
-  ScriptDescriptor,
   UnsafeScriptDescriptor,
 } from "../manifest.ts"
-import type { MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
+import type { DocumentParts, MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
@@ -76,6 +73,7 @@ export interface RenderedPage {
 }
 
 export interface RenderPageOptions {
+  readonly serverComponents?: import("../server-components/types.ts").ComponentState
   readonly adapter: RenderAdapter
   /** The layout chain to render - outermost layout → page (opaque; the adapter renders it). */
   readonly chain: readonly unknown[]
@@ -200,8 +198,10 @@ export interface RenderPageOptions {
 export interface RenderAssemblyCache {
   /** Shell up to (not including) the deferred-runtime insertion point. */
   shellPre?: string
-  /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
+  /** Shell from after the deferred-runtime insertion point through `<body>`. */
   shellPost?: string
+  /** The open `#root` container. */
+  rootOpen?: string
   /** Tail opener: the handover script open tag + the data member's key. */
   tailPre?: string
   /** Tail from after the per-request handover members (the route id, prerendered paths, the handover
@@ -343,6 +343,10 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     boundarySplit === undefined
       ? ""
       : `,"${BOUNDARY_GLOBAL}":${serializeData(boundarySplit.forClient)}`
+  const componentTail =
+    options.serverComponents === undefined
+      ? ""
+      : `,"__NIFRA_COMPONENTS__":${serializeData(options.serverComponents)}`
   const deferredRuntime =
     allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
   // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
@@ -418,7 +422,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
       : ""
     slot.shellPre = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head, nonce)}${styleLinks}${entryPreloads}`
-    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
+    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body>`
+    slot.rootOpen = `<div id="${escapeAttr(rootId)}"${rootMarker}>`
     // Island bundles load regardless of `hydrate` - a static page (hydrate:false) ships no framework
     // client but can still mount no-framework islands (`@nifrajs/web/islands`).
     let islandTags = ""
@@ -436,14 +441,20 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
   // only when something actually deferred - matching the pre-cache emission exactly.
   const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
-  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`
+  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}${slot.rootOpen}`
+  const parts: DocumentParts | undefined =
+    adapter.documentParts === true ? { head: "", body: "" } : undefined
+  const shellOf = (): string =>
+    parts === undefined || (parts.head === "" && parts.body === "")
+      ? shellHtml
+      : `${slot.shellPre}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
   // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
   // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
   const closeRootHtml = "</div>"
   // Tail - the page-state handover + the client module. Module scripts defer (run after parse), so
   // the handover + every streamed deferred resolution are in the document before the entry hydrates.
   const tailHtml = hydrate
-    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${slot.tailPost}`
+    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${slot.tailPost}`
     : (slot.tailPost as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
   // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
@@ -469,6 +480,9 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     if (policy !== undefined) headers["content-security-policy"] = policy
   }
   const renderProps: RenderProps = {
+    ...(options.serverComponents === undefined
+      ? {}
+      : { serverComponents: options.serverComponents }),
     data: forComponent,
     actionData: actionSplit?.forComponent,
     // `params`/`path` thread the matched route + URL to the adapter's `useParams`/`useLocation` so they
@@ -496,13 +510,22 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
   // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
   if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
-    const out = adapter.renderToString(chain, renderProps)
+    const out =
+      parts !== undefined
+        ? adapter.renderToString(
+            chain,
+            renderProps,
+            nonce === undefined ? { parts } : { nonce, parts },
+          )
+        : nonce === undefined
+          ? adapter.renderToString(chain, renderProps)
+          : adapter.renderToString(chain, renderProps, { nonce })
     return typeof out === "string"
-      ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
+      ? new BufferedRenderedPage(shellOf() + out + closeRootHtml + tailHtml, status, headers)
       : out.then(
           (bodyHtml) =>
             new BufferedRenderedPage(
-              shellHtml + bodyHtml + closeRootHtml + tailHtml,
+              shellOf() + bodyHtml + closeRootHtml + tailHtml,
               status,
               headers,
             ),
@@ -513,7 +536,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     adapter,
     chain,
     renderProps,
-    shellHtml,
+    shellOf,
+    parts,
     closeRootHtml,
     allDeferred,
     tailHtml,
@@ -528,7 +552,8 @@ async function renderStreamedPage(
   adapter: RenderAdapter,
   chain: readonly unknown[],
   renderProps: RenderProps,
-  shellHtml: string,
+  shellOf: () => string,
+  parts: DocumentParts | undefined,
   closeRootHtml: string,
   allDeferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
   tailHtml: string,
@@ -542,13 +567,20 @@ async function renderStreamedPage(
   // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
   // sent. A *mid*-stream failure errors the body instead.
   const enc = TEXT_ENCODER
-  const shell = enc.encode(shellHtml)
   const closeRoot = enc.encode(closeRootHtml)
   const tail = enc.encode(tailHtml)
   const appStream =
-    nonce === undefined
-      ? await adapter.renderToStream(chain, renderProps)
-      : await adapter.renderToStream(chain, renderProps, { nonce })
+    parts !== undefined
+      ? await adapter.renderToStream(
+          chain,
+          renderProps,
+          nonce === undefined ? { parts } : { nonce, parts },
+        )
+      : nonce === undefined
+        ? await adapter.renderToStream(chain, renderProps)
+        : await adapter.renderToStream(chain, renderProps, { nonce })
+  // After the render: an adapter fills its document parts before handing back the stream.
+  const shell = enc.encode(shellOf())
   const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
   return new Response(body, { status, headers })
 }
@@ -616,13 +648,17 @@ function streamDocument(
   enc: TextEncoder,
   nonceAttr: string,
 ): ReadableStream<Uint8Array> {
+  const reader = stream.getReader()
+  // A client that goes away cancels the body: the renderer stops, and nothing more is written.
+  let cancelled = false
+  let released = false
   return new ReadableStream({
     async start(controller) {
-      const reader = stream.getReader()
       try {
         controller.enqueue(shell)
         for (;;) {
           const { done, value } = await reader.read()
+          if (cancelled) return
           if (done) break
           controller.enqueue(value)
         }
@@ -631,34 +667,37 @@ function streamDocument(
         // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
         await Promise.all(
           deferred.map(async (d) => {
+            let script: string
             try {
               const value = serializeData(await d.promise)
               // `serializeData` JSON-serializes the value and escapes `<`, `>`, and Unicode line
               // separators before this framework-owned script is emitted.
-              controller.enqueue(
-                enc.encode(`<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>`), // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
-              )
+              script = `<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>` // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
             } catch (err) {
               // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) - it must
               // not break the whole body. Redact: stream a stable opaque code, never the raw error
               // text; log the real reason server-side.
               console.error("[nifra/web] deferred value rejected:", err)
-              controller.enqueue(
-                enc.encode(
-                  `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`,
-                ),
-              )
+              script = `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
             }
+            if (!cancelled) controller.enqueue(enc.encode(script))
           }),
         )
+        if (cancelled) return
         controller.enqueue(tail)
         controller.close()
       } catch (err) {
-        controller.error(err)
+        if (!cancelled) controller.error(err)
       } finally {
+        released = true
         reader.releaseLock()
       }
     },
+    cancel(reason) {
+      cancelled = true
+      // Once the renderer is drained the reader is released, and there is nothing left to stop.
+      return released ? undefined : reader.cancel(reason)
+    },
   })
 }
 
@@ -1108,68 +1147,6 @@ function headTags(head: Meta | undefined, documentNonce?: string): string {
   return out
 }
 
-/**
- * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
- * engines which URL is authoritative for a page (deduping query-string / tracking variants).
- *
- * ```ts
- * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
- * ```
- */
-export function canonical(href: string): LinkDescriptor {
-  return { rel: "canonical", href }
-}
-
-/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
- * ones become tags. `type` defaults to `"website"`. */
-export interface OpenGraphInput {
-  readonly title?: string
-  readonly description?: string
-  /** Absolute URL of the share image (`og:image`). */
-  readonly image?: string
-  /** Canonical URL of the page (`og:url`). */
-  readonly url?: string
-  /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
-  readonly type?: string
-}
-
-/**
- * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
- * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
- *
- * ```ts
- * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
- * ```
- */
-export function openGraph(input: OpenGraphInput): MetaDescriptor[] {
-  const tags: MetaDescriptor[] = []
-  const add = (property: string, content: string | undefined): void => {
-    if (content !== undefined) tags.push({ property, content })
-  }
-  add("og:title", input.title)
-  add("og:description", input.description)
-  add("og:image", input.image)
-  add("og:url", input.url)
-  // `og:type` always present (the spec's required property) - default "website" when unset.
-  tags.push({ property: "og:type", content: input.type ?? "website" })
-  return tags
-}
-
-/**
- * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
- * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
- * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
- *
- * ```ts
- * export const meta = {
- *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
- * }
- * ```
- */
-export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
-  return { type: "application/ld+json", content: JSON.stringify(data) }
-}
-
 /**
  * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
  * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.

package/src/internal/response-controls.ts

@@ -2,9 +2,15 @@ import {
   type CookieOptions,
   type ResponseResult,
   status as statusResult,
+  writableResponse,
 } from "@nifrajs/core/server"
 import type { LoaderResponseControls } from "../manifest.ts"
 import { DATA_HEADER } from "../router.ts"
+import {
+  type ProgressiveCookie,
+  progressiveCookieHeader,
+  progressiveCookieRedirect,
+} from "./progressive-cookies.ts"
 import { isResponseResult } from "./render-document.ts"
 
 /** The serving app's response controls - the structural subset of a route handler's `c.set` used here. */
@@ -107,19 +113,9 @@ export function privateOutcome(outcome: unknown): unknown {
 
 function privateResponse(response: Response): Response {
   if (response.headers.get(CACHE_CONTROL) === PRIVATE_NO_STORE) return response
-  try {
-    response.headers.set(CACHE_CONTROL, PRIVATE_NO_STORE)
-    return response
-  } catch {
-    // Immutable headers (`Response.redirect()`, a `fetch()` result): answer with a copy.
-    const headers = new Headers(response.headers)
-    headers.set(CACHE_CONTROL, PRIVATE_NO_STORE)
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers,
-    })
-  }
+  const target = writableResponse(response)
+  target.headers.set(CACHE_CONTROL, PRIVATE_NO_STORE)
+  return target
 }
 
 interface WrittenHeaders {
@@ -140,6 +136,7 @@ export class PageResponseControls {
   #written: WrittenHeaders[] | undefined
   #sealed = false
   #personalized = false
+  #cookieChanges: ProgressiveCookie[] | undefined
 
   constructor(c: { readonly set: CoreResponseControls }) {
     this.#c = c
@@ -167,7 +164,27 @@ export class PageResponseControls {
   cookies(member: string): CoreResponseControls {
     this.assertOpen(member)
     this.personalize()
-    return this.#c.set
+    const controls = this.#c.set
+    return {
+      headers: controls.headers,
+      cookie: (name, value, options) => {
+        controls.cookie(name, value, options)
+        this.#cookieChanges ??= []
+        this.#cookieChanges.push({ name, value, options })
+      },
+      deleteCookie: (name, options) => {
+        controls.deleteCookie(name, options)
+        this.#cookieChanges ??= []
+        this.#cookieChanges.push({ name, value: "", options, deleted: true })
+      },
+    }
+  }
+
+  progressiveCookies(request: Request): string {
+    return progressiveCookieHeader(request, this.#cookieChanges ?? [])
+  }
+  progressiveRedirect(request: Request): boolean {
+    return progressiveCookieRedirect(request, this.#cookieChanges ?? [])
   }
 
   /** Mark the response as one visitor's - a queued cookie, or a draft render - so no cache stores it. */

package/src/internal/revive-dates.ts

@@ -0,0 +1,35 @@
+/**
+ * `t.date()` across the wire, browser half: every place the browser parses page data rebuilds the
+ * `{ "__nifra_date": iso }` tags the server's `wireDate()` wrote into `Date`s. Kept apart from
+ * `wire-date.ts` so client bundles never carry the server class.
+ */
+
+export const DATE_TAG = "__nifra_date"
+const TAGGED = `"${DATE_TAG}"`
+
+// A JSON.parse reviver runs leaves first and defines each result as an own property, so a key named
+// `__proto__` never becomes the prototype.
+const revive = (_key: string, value: unknown): unknown => {
+  if (typeof value !== "object" || value === null) return value
+  const tagged: unknown = Reflect.get(value, DATE_TAG)
+  return typeof tagged === "string" && Object.keys(value).length === 1 ? new Date(tagged) : value
+}
+
+/** `JSON.parse` that rebuilds every `{ "__nifra_date": iso }` into a `Date`, when the text has one. */
+export const parsePageData = (text: string): unknown =>
+  text.includes(TAGGED) ? JSON.parse(text, revive) : JSON.parse(text)
+
+/**
+ * {@link parsePageData}'s reviver as source declaring `__nifraDates`, for client code nifra generates rather than
+ * bundles (server-function stubs; `DEFERRED_RUNTIME` carries the same text). A literal with nothing
+ * interpolated: Bun keeps a template that interpolates an import, and with it every string built from
+ * it, in client bundles that never use them.
+ */
+export const REVIVE_DATES_SOURCE = `const __nifraDates = (d) => {
+  if (!d || typeof d !== "object") return d
+  if (Array.isArray(d)) { for (let i = 0; i < d.length; i++) d[i] = __nifraDates(d[i]); return d }
+  const k = Object.keys(d)
+  if (k.length === 1 && k[0] === "__nifra_date" && typeof d.__nifra_date === "string") return new Date(d.__nifra_date)
+  for (const x of k) { const v = __nifraDates(d[x]); if (v !== d[x]) Object.defineProperty(d, x, { value: v, enumerable: true, writable: true, configurable: true }) }
+  return d
+}`

package/src/internal/route-path.ts

@@ -0,0 +1,24 @@
+/**
+ * A route pattern's literal text as a request path spells it. A route file named `café.tsx` is
+ * requested as `/caf%C3%A9`, so the routers, which compare the raw request path, are given the pattern
+ * that way. Only controls, space and non-ASCII are encoded (what a browser encodes in a path), so ASCII
+ * punctuation such as a param constraint keeps its meaning. Runs once per pattern, never per request.
+ */
+export const requestPattern = (pattern: string): string =>
+  pattern.normalize("NFC").replace(/[^!-~]/gu, encodeURIComponent)
+
+// This module also compiles without the DOM lib; at runtime the name is the browser's own global.
+declare const location: { readonly origin: string } | undefined
+
+/**
+ * An app path as a URL `fetch`, `history` and `location` resolve on this document's own origin. A path
+ * starting `//` or `/\` is the path of a page here (`https://shop.example//evil.example/x`), but resolved
+ * as written it is a protocol-relative URL to another host, so it is anchored to this origin.
+ */
+export const appUrl = (path: string): string =>
+  path.charCodeAt(0) === 47 /* / */ &&
+  (path.charCodeAt(1) === 47 || path.charCodeAt(1) === 92) /* / or \ */ &&
+  typeof location !== "undefined" &&
+  location.origin !== "null"
+    ? location.origin + path
+    : path