@nifrajs/web 2.10.0 → 2.12.0

package/src/index.ts

@@ -13,7 +13,7 @@ import {
   type BackendMountHandler,
   NIFRA_BACKEND_MOUNT,
 } from "@nifrajs/core/mount"
-import { server, type UrlParts, urlPartsOf } from "@nifrajs/core/server"
+import { type ServerOptions, server, type UrlParts, urlPartsOf } from "@nifrajs/core/server"
 import {
   DEFERRED_ERROR_CODE,
   DEFERRED_RUNTIME,
@@ -25,6 +25,10 @@ import {
 } from "./deferred.ts"
 import { isDraftEnabled } from "./draft.ts"
 import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+// Head resolution/merging. Defined in an internal module so `@nifrajs/web/client` can export the same
+// two functions to the generated client entry without dragging THIS module (and its server code) into
+// the browser graph - see internal/head-merge.ts. Re-exported here so the public API is unchanged.
+import { mergeHeads, resolveMeta } from "./internal/head-merge.ts"
 import { jsStringLiteral } from "./internal/js-string.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "./isr.ts"
@@ -44,6 +48,14 @@ import type {
   ScriptDescriptor,
   UnsafeScriptDescriptor,
 } from "./manifest.ts"
+import type { RenderAdapter, RenderProps } from "./render-seam.ts"
+import {
+  ACTION_GLOBAL,
+  DATA_GLOBAL,
+  LAYOUT_DATA_GLOBAL,
+  ROOT_ATTRIBUTE,
+  ROUTE_GLOBAL,
+} from "./render-seam.ts"
 import {
   createMatcher,
   DATA_HEADER,
@@ -53,7 +65,6 @@ import {
   RETAIN_HEADER,
   REVALIDATE_HEADER,
   STATUS_HEADER,
-  type Submission,
 } from "./router.ts"
 import { searchOf, searchOfChain } from "./search.ts"
 
@@ -113,6 +124,7 @@ export {
   type Manifest,
   type Meta,
   type MetaArgs,
+  type MetaDescriptor,
   type MetaInput,
   type RouteEntry,
   type RouteModule,
@@ -195,7 +207,7 @@ export {
   type SubmitOptions,
 } from "./router.ts"
 // Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
-export { type Deferred, defer }
+export { type Deferred, defer, mergeHeads, resolveMeta }
 
 /** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
  * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
@@ -231,6 +243,18 @@ export {
   RenderAdapterConformanceError,
   type RenderAdapterConformanceFixture,
 } from "./conformance.ts"
+export {
+  ACTION_GLOBAL,
+  DATA_GLOBAL,
+  LAYOUT_DATA_GLOBAL,
+  type RenderAdapter,
+  type RenderProps,
+  ROOT_ATTRIBUTE,
+  ROUTE_GLOBAL,
+  type SsrModuleLoader,
+  setSsrModuleLoader,
+  ssrModuleLoader,
+} from "./render-seam.ts"
 
 // The search-derivation primitive: parse a URL query, validate it against a route's `searchSchema`
 // (fail-closed to defaults), or return the raw parsed query when there is none. Both the server (loader
@@ -238,105 +262,6 @@ export {
 // produce the identical value by construction. An adapter's `useSearch` binding reads its result.
 export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.ts"
 
-/** The data handed to a route component. Opaque to the core. `actionData` is the return of a
- * route `action` after a POST (absent on plain GETs). `pending` + `submission` are client-only
- * (absent on SSR): they drive **optimistic UI** - render from `submission.formData` while `pending`. */
-export interface RenderProps {
-  readonly data: unknown
-  /**
-   * Per-layout loader data, aligned index-for-index with the layout prefix of `chain`.
-   *
-   * Absent when no layout in the chain exports a `loader`, so a page-only app is byte-identical to
-   * before. An adapter that does not read it renders exactly as it did; one that does passes
-   * `layoutData[i]` to `chain[i]`.
-   */
-  readonly layoutData?: readonly unknown[]
-  readonly actionData?: unknown
-  /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
-  readonly pending?: boolean
-  /** The path a client navigation is transitioning TO while `pending` (client-only; absent on SSR and
-   * when idle). Lets an adapter tell a `NavLink` whether its own target is the one loading. */
-  readonly pendingPath?: string
-  /** The in-flight client submit, for optimistic UI (client-only; absent on SSR + when idle). */
-  readonly submission?: Submission
-  /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). Threaded identically on
-   * SSR (from the request match) and on client navigation (from router state) so an adapter's
-   * `useParams` reads the same value on both, with no hydration mismatch. Absent ⇒ no params (`{}`). */
-  readonly params?: Readonly<Record<string, string>>
-  /** The current URL's `pathname + search` (no hash - the hash never reaches the server). Threaded on
-   * SSR and client alike so an adapter's `useLocation`/`useSearchParams` hydrate consistently. Absent
-   * on adapters/callers that don't supply it (treated as `""`). */
-  readonly path?: string
-  /** The route's typed, validated search params (the value the loader also gets as `ctx.search`),
-   * threaded to the adapter's `useSearch`. Derived identically on SSR (from the request) and on client
-   * navigation (adapter mount) via the shared `searchOf`, so a component reading it hydrates with no
-   * drift. Absent ⇒ no search context (`{}`). */
-  readonly search?: Record<string, unknown>
-}
-
-/**
- * The seam every render adapter implements. New adapters should prove these invariants with
- * {@link assertRenderAdapterConformance}; framework-specific behavior remains locally tested.
- */
-export interface RenderAdapter {
-  /**
-   * Server: render a route's layout `chain` (outermost layout → page) to a **stream** of HTML
-   * bytes, including the framework's hydration markers. The page (innermost) receives `props`
-   * (the loader data); each layout wraps the child via its `children`. Returns (or resolves to)
-   * a Web `ReadableStream<Uint8Array>`: a streaming renderer flushes the shell first and streams
-   * Suspense boundaries as they resolve; a non-streaming renderer may return a one-chunk stream.
-   * May be async - e.g. React resolves once the shell is renderable, so a shell-render throw can
-   * still map to an error status before any byte is sent.
-   */
-  renderToStream(
-    chain: readonly unknown[],
-    props: RenderProps,
-  ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
-  /**
-   * Server (optional): render the chain to a complete HTML **string** in one pass, with the same
-   * hydration markers `renderToStream` produces. When provided, `renderPage` uses it for any page
-   * that does **not** `defer()` - buffering the document is faster than the streaming pipeline there,
-   * because the framework's synchronous renderer (React `renderToString`, Solid `renderToString`,
-   * Preact `render`, Vue `renderToString`, Svelte `render`) is markedly cheaper than its streaming
-   * renderer - most visibly on Bun, where React Fizz / Solid `renderToStream` are the heaviest. Pages
-   * that `defer()` keep the streaming path (progressive `<Await>` needs it). Markup MUST be
-   * hydration-equivalent to `renderToStream`; a throw surfaces like the streaming shell-readiness
-   * await (the `_error` boundary maps it to a status). Omit it to always stream.
-   */
-  renderToString?(chain: readonly unknown[], props: RenderProps): string | Promise<string>
-  /**
-   * Server: per-document bootstrap markup injected into `<head>` that the client
-   * `hydrate` requires (Solid: `generateHydrationScript()`). Empty string if none.
-   */
-  hydrationHead(nonce?: string): string
-}
-
-/** Global the server serializes loader data into; the client reads it to hydrate. */
-export const DATA_GLOBAL = "__NIFRA_DATA__"
-/** Per-layout loader data for hydration. Emitted ONLY when some layout in the chain has a loader, so
- * a page-only app's HTML is byte-identical to before layout loaders existed. */
-export const LAYOUT_DATA_GLOBAL = "__NIFRA_LAYOUT_DATA__"
-
-/** Global the server writes the matched route id into; the client uses it to pick the chain. */
-export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
-
-/** Global the server serializes an action's data return into (absent on GETs); the client
- * reads it so hydration after a native form POST matches the server-rendered markup. */
-export const ACTION_GLOBAL = "__NIFRA_ACTION__"
-
-/**
- * Marker attribute on the app container, emitted ONLY when `rootId` is not the default.
- *
- * `rootId` is a per-RENDER option; the client entry is a per-BUILD artifact, so it cannot be
- * generated knowing which id a given render will use. The container therefore announces itself, and
- * the entry finds it by this attribute before falling back to `#root`. It has to be the DOM rather
- * than another `window.__NIFRA_*` global: a second copy of the id can drift from the markup, while
- * this is written by the same expression that writes the id and cannot.
- *
- * Absent on a default render, so an app that never sets `rootId` emits the same bytes it always has.
- */
-export const ROOT_ATTRIBUTE = "data-nifra-root"
-
 /**
  * Pre-hydration form guard - a tiny inline script flushed in `<head>` (it runs in the window between
  * first paint and the island bundle taking over). It neutralizes the one real hydration footgun: a
@@ -987,6 +912,20 @@ function withDuplicateInstanceHint(err: unknown): unknown {
   return augmented
 }
 
+/**
+ * An action's `Response` passes straight through - except a redirect on a client-submit data
+ * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
+ * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the
+ * returned- and thrown-Response paths, so `return redirect()` and `throw redirect()` agree.
+ */
+function actionResponse(response: Response, isDataRequest: boolean): Response {
+  if (isDataRequest && response.status >= 300 && response.status < 400) {
+    const location = response.headers.get("location") ?? "/"
+    return new Response(null, { status: 204, headers: { [REDIRECT_HEADER]: location } })
+  }
+  return response
+}
+
 /** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
 type LoadedLayoutModules = ReadonlyArray<{
   default: unknown
@@ -1287,12 +1226,6 @@ function headTags(head: Meta | undefined): string {
   return out
 }
 
-/** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */
-export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
-  if (meta === undefined) return {}
-  return typeof meta === "function" ? meta(args) : meta
-}
-
 /**
  * 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).
@@ -1379,75 +1312,67 @@ export function unsafeInlineScript(
   }
 }
 
-/**
- * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
- *
- * The head contract (see {@link CreateWebAppOptions} and `LayoutEntry`): a `_layout.tsx` may export
- * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
- * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
- * render chain), and merges:
- *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an
- *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
- *    page `title` keeps it.
- *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag
- *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
- *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
- *
- * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
- * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
- * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
- * content can vary with loader data anyway).
- */
-export function mergeHeads(heads: readonly Meta[]): Meta {
-  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
-  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
-  if (heads.length === 1) return heads[0] as Meta
-  let title: string | undefined
-  let lang: string | undefined
-  let dir: Meta["dir"]
-  const meta: MetaDescriptor[] = []
-  const link: LinkDescriptor[] = []
-  const script: ScriptDescriptor[] = []
-  const unsafeScript: UnsafeScriptDescriptor[] = []
-  for (const h of heads) {
-    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
-    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
-    if (h.dir !== undefined) dir = h.dir
-    if (h.meta !== undefined) meta.push(...h.meta)
-    if (h.link !== undefined) link.push(...h.link)
-    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
-    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
-  }
-  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
-  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
-  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
-  // `undefined`).
-  const merged: {
-    title?: string
-    meta?: Meta["meta"]
-    link?: Meta["link"]
-    script?: Meta["script"]
-    unsafeScript?: Meta["unsafeScript"]
-    lang?: string
-    dir?: Meta["dir"]
-  } = {}
-  if (title !== undefined) merged.title = title
-  if (meta.length > 0) merged.meta = meta
-  if (link.length > 0) merged.link = link
-  if (script.length > 0) merged.script = script
-  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
-  if (lang !== undefined) merged.lang = lang
-  if (dir !== undefined) merged.dir = dir
-  return merged as Meta
-}
-
-export interface CreateWebAppOptions {
+export interface CreateWebAppOptions<Env = unknown> {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
   /** URL of the built client entry (module script) injected into every page. */
   readonly clientEntry: string
   /** Default document title for all pages. */
   readonly title?: string
+  /**
+   * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
+   * the rest of {@link ServerOptions}.
+   *
+   * Needed because the `Server` is constructed in here, so a caller has no other way to reach its
+   * constructor: a page app could set no request timeout and no capacity gate, which are exactly the
+   * two knobs a production readiness check looks for. An SSR app wants them MORE than a backend does -
+   * a render is slow and allocation-heavy, so a burst that a JSON API would absorb is the one that
+   * exhausts the pod.
+   *
+   * Applies to the whole app, {@link mounts} and the {@link api} auto-mount included: the capacity gate
+   * sits at the fetch entry, ahead of the request hooks those are dispatched from.
+   */
+  readonly server?: ServerOptions
+  /**
+   * Runs against the app BEFORE any page route is registered - the seam for `securityHeaders()`,
+   * `requestId()`, `logger()`, a rate limit, or anything else applied with `use`.
+   *
+   * ```ts
+   * createWebApp({
+   *   …,
+   *   use: (app) => {
+   *     app.use(securityHeaders())
+   *     app.use(requestId())
+   *   },
+   * })
+   * ```
+   *
+   * A callback rather than an array because `use` is overloaded - `Middleware`, `IdentityPlugin`,
+   * `ContextPlugin` - and only the real call site instantiates the right overload. The return value
+   * is ignored: this is for cross-cutting concerns, not for declaring routes (declare those on the
+   * returned app, where they get their types).
+   *
+   * **Why the timing matters.** `beforeHandle`, `afterHandle`, `around`, `derive`/`decorate`, and
+   * `onError` are snapshotted into each route AS IT IS DECLARED, and `createWebApp` declares every
+   * page (plus the `/*` catch-all) before it returns - so a caller's `app.use(…)` afterwards binds
+   * them to nothing, silently. `requestId()` is exactly that case: it is a `derive`, so applied late
+   * it leaves every page without `c.requestId`. Route assurance evidence is order-scoped the same
+   * way, so a late `securityHeaders()` leaves the pages unable to PROVE the header to `nifra assure`
+   * even though it does still set it.
+   *
+   * `onRequest`/`onResponse` (and the response header/body hooks) are app-global arrays read at
+   * request time, so those alone DO work when added late. Using this seam for everything avoids
+   * having to remember which is which.
+   *
+   * Runs ahead of the {@link mounts} / {@link api} request hooks, so an `onRequest` middleware guards
+   * a mounted auth handler too.
+   *
+   * A `ContextPlugin` applied here takes runtime effect but cannot widen the declared return type of
+   * this function, so `c.requestId` is not typed on routes you declare afterwards. Named plugins are
+   * idempotent, so `app.use(requestId())` on the returned app recovers the TYPE without applying the
+   * plugin a second time.
+   */
+  readonly use?: (app: ReturnType<typeof server<Env>>) => void
   /** Injected into each loader's `ctx.api` - typically an `inProcessClient(app)` (typed
    * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core.
    *
@@ -1512,6 +1437,11 @@ export interface CreateWebAppOptions {
    * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
    * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
   readonly prerenderedPaths?: readonly string[]
+  /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
+   * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
+   * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
+   * routinely. Turn it on only for a repo whose guidelines you would publish as a page. */
+  readonly publishLocalGuidelines?: boolean
   /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
    * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
    * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
@@ -1600,7 +1530,7 @@ const urlPartsFor = (request: Request): UrlParts => {
  * secure default; validate at the trust boundary before use.
  */
 export function createWebApp<Env = unknown>(
-  options: CreateWebAppOptions,
+  options: CreateWebAppOptions<Env>,
 ): ReturnType<typeof server<Env>> {
   const { adapter, manifest, clientEntry, title, api } = options
   const titleOption = title === undefined ? {} : { title }
@@ -1626,7 +1556,11 @@ export function createWebApp<Env = unknown>(
   // Seed the context with the declared `Env` so `app.fetch(req, { env })` / `toFetchHandler(app)` type
   // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
   // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
-  const app = server<Env>()
+  const app = server<Env>(options.server)
+  // Before the mount hooks and before every page route, so the order-scoped hooks (`derive`,
+  // `beforeHandle`, assurance evidence) actually bind to them - see the `use` option. A caller
+  // cannot do this after the fact: by the time this function returns, the routes are declared.
+  options.use?.(app)
   // Auto-mount the in-process backend over HTTP at `apiPrefix` (default `/api`), BEFORE page routing.
   // `onRequest` runs on the raw request ahead of the router, so this wins over the page wildcard `/*`
   // for every method (POST/GET/PUT/…) - not just the GET page routes - and a backend 404 (`/api/none`)
@@ -2169,6 +2103,13 @@ export function createWebApp<Env = unknown>(
         }
         return renderError(route, errorId, withDuplicateInstanceHint(err))
       }
+      // A loader may RETURN its control-flow signal instead of throwing it - `return redirect(...)`
+      // reads naturally and must not silently serialize the `Response` as loader data. Mirror the
+      // catch above exactly: a status signal renders its boundary, any other `Response` (a
+      // redirect, a hand-rolled response) passes through to core verbatim - so return and throw
+      // are interchangeable.
+      if (isStatusSignal(data)) return renderStatusSignal(c.req, data)
+      if (data instanceof Response) return data
       // Client-side navigation asks (via the X-Nifra-Data header) for just the loader data - no full
       // document, no layout chain. A route with deferred data streams NDJSON (critical data first,
       // then each deferred value as it settles); otherwise one JSON (the fast path). Same loader,
@@ -2275,11 +2216,21 @@ export function createWebApp<Env = unknown>(
         draft,
         search: loaderSearch(mod.searchSchema, c.req),
       }
-      // A gate is an authorization boundary for everything beneath its layout, mutations included.
-      // Run only gates before the action; ordinary layout data loaders run after a native mutation.
-      const layoutModules = await runLayoutGates(route, actionContext)
-      const result = await mod.action(actionContext)
       const isDataRequest = c.req.headers.get(DATA_HEADER) !== null
+      let layoutModules: LoadedLayoutModules
+      let result: unknown
+      try {
+        // A gate is an authorization boundary for everything beneath its layout, mutations included.
+        // Run only gates before the action; ordinary layout data loaders run after a native mutation.
+        layoutModules = await runLayoutGates(route, actionContext)
+        result = await mod.action(actionContext)
+      } catch (err) {
+        // A THROWN Response is the same control-flow signal as a returned one (`throw redirect()`
+        // in a gate or an action) - route it through the same conversion as the returned-Response
+        // branch below, so throw and return are interchangeable on the mutation path too.
+        if (err instanceof Response) return actionResponse(err, isDataRequest)
+        throw err
+      }
       // An action may wrap its data in `revalidate(paths, data)` to declare which routes it changed.
       // Unwrap to the inner data; the paths ride the `X-Nifra-Revalidate` header on the data-mode
       // responses (the client acts on them - a full-page POST re-runs loaders inline, so no header).
@@ -2289,15 +2240,7 @@ export function createWebApp<Env = unknown>(
       const revalidateHeader: Record<string, string> = isRevalidate
         ? { [REVALIDATE_HEADER]: (result as RevalidateResult<unknown>).__nifraRevalidate.join(",") }
         : {}
-      if (actionResult instanceof Response) {
-        // Client submit can't read a 3xx Location (fetch follows it to HTML), so convey the
-        // redirect via a header on a 204 and let the client navigate. Native forms get the 3xx.
-        if (isDataRequest && actionResult.status >= 300 && actionResult.status < 400) {
-          const location = actionResult.headers.get("location") ?? "/"
-          return new Response(null, { status: 204, headers: { [REDIRECT_HEADER]: location } })
-        }
-        return actionResult
-      }
+      if (actionResult instanceof Response) return actionResponse(actionResult, isDataRequest)
       // Client submit wants just the action's data (it revalidates the loader itself); a native
       // form POST re-renders the full page (loader re-runs) with the action data.
       if (isDataRequest) {
@@ -2354,15 +2297,16 @@ export function createWebApp<Env = unknown>(
   }
 
   // Register llms.txt & llms-full.txt
+  const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
   app.register("GET", "/llms.txt", undefined, async () => {
-    const text = await generateLlmsTxt(false, manifest.routes, api)
+    const text = await generateLlmsTxt(false, manifest.routes, api, llmsOptions)
     return new Response(text, {
       headers: { "content-type": "text/plain; charset=utf-8" },
     })
   })
 
   app.register("GET", "/llms-full.txt", undefined, async () => {
-    const text = await generateLlmsTxt(true, manifest.routes, api)
+    const text = await generateLlmsTxt(true, manifest.routes, api, llmsOptions)
     return new Response(text, {
       headers: { "content-type": "text/plain; charset=utf-8" },
     })
@@ -2447,12 +2391,24 @@ export function generateClientEntry(
   }
 
   return `${[
-    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
+    // `/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.
+    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"',
     'import { applyHead, installForms, installHistory, signalHydrated } from "@nifrajs/web/client"',
     // 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.
     `import * as __adapter from ${JSON.stringify(clientModule)}`,
     "const { mountRouter } = __adapter",
+    // The assurance hook is optional: ordinary client entries pay only for the namespace lookup, while
+    // hydration runners get a runtime identity from the exact adapter module that mounted the page. The
+    // registry is token-only and lives on a Symbol.for key so it cannot collide with app data.
+    "const __hydrationHook = __adapter.hydrationAssuranceHook",
+    'if (__hydrationHook && typeof __hydrationHook.runtimeIdentity === "function") {',
+    '  const __runtimeKey = Symbol.for("nifra.hydration.runtime")',
+    "  const __runtimeState = globalThis[__runtimeKey]",
+    "  const __identities = __runtimeState && Array.isArray(__runtimeState.identities) ? __runtimeState.identities : []",
+    "  globalThis[__runtimeKey] = { framework: __hydrationHook.framework, identities: [...__identities, __hydrationHook.runtimeIdentity()] }",
+    "}",
     // The `clientModule` contract is a string specifier, so nothing type-checks that the module it
     // names actually exports `mountRouter`. Without this the miss surfaces as
     // "mountRouter is not a function" from inside a bundled chunk, at first paint, naming neither the
@@ -2464,6 +2420,16 @@ export function generateClientEntry(
         '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
     )})`,
     "const errorBoundary = __adapter.errorBoundary",
+    // A hot update that the framework cannot actually apply must end in a reload, not in nothing.
+    //
+    // Bun's dev server applies React Fast Refresh to JSX modules. For React that patches the component
+    // and preserves state. For Preact it does not - the module still LOOKS Fast-Refresh-able, so the
+    // update is accepted and then swallowed: `bun:beforeUpdate`/`bun:afterUpdate` both fire, the server
+    // logs a rebuild, and the page silently keeps rendering the old code. An edit that appears to do
+    // nothing is the worst failure mode in a dev loop - worse than a reload, because there is no signal
+    // to act on. An adapter that knows its framework is in that position says so, and the entry turns
+    // the swallowed update into an honest full reload.
+    'if (import.meta.hot && __adapter.hotUpdateNeedsReload) import.meta.hot.on("bun:afterUpdate", () => location.reload())',
     `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
     // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when

package/src/internal/head-merge.ts

@@ -0,0 +1,80 @@
+/**
+ * Head resolution + merging, in its own module so the CLIENT can have it without the server.
+ *
+ * These two are pure functions over `Meta`, but they used to live in `index.ts` - the module that also
+ * carries `renderPage`, `createWebApp` and the static-file server. The generated client entry imported
+ * them from `@nifrajs/web`, which under a bundler was harmless (server code tree-shakes away) and under
+ * Vite's dev server was fatal: it serves each module as-is, so pulling `index.ts` into the browser graph
+ * executed `public-dir.ts` and the page died on `Module "node:fs/promises" has been externalized`
+ * before hydrating. Splitting them out means the client entry never names the server module at all,
+ * rather than relying on a bundler to remove it afterwards.
+ *
+ * `index.ts` and `client.ts` both re-export from here, so the public API is unchanged in both places.
+ */
+import type {
+  LinkDescriptor,
+  Meta,
+  MetaArgs,
+  MetaDescriptor,
+  MetaInput,
+  ScriptDescriptor,
+  UnsafeScriptDescriptor,
+} from "../manifest.ts"
+
+/** Resolve a route's `meta` export - a static object, or a function of the route's data/params. */
+export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
+  if (meta === undefined) return {}
+  return typeof meta === "function" ? meta(args) : meta
+}
+
+/**
+ * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and
+ * `meta`/`link`/`script` concatenate in chain order.
+ *
+ * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
+ * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
+ * fine: `headTags`'s memo is keyed on identity, so a per-request merge simply recomputes (its
+ * content can vary with loader data anyway).
+ */
+export function mergeHeads(heads: readonly Meta[]): Meta {
+  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
+  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
+  if (heads.length === 1) return heads[0] as Meta
+  let title: string | undefined
+  let lang: string | undefined
+  let dir: Meta["dir"]
+  const meta: MetaDescriptor[] = []
+  const link: LinkDescriptor[] = []
+  const script: ScriptDescriptor[] = []
+  const unsafeScript: UnsafeScriptDescriptor[] = []
+  for (const h of heads) {
+    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
+    if (h.dir !== undefined) dir = h.dir
+    if (h.meta !== undefined) meta.push(...h.meta)
+    if (h.link !== undefined) link.push(...h.link)
+    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
+    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
+  }
+  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
+  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
+  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
+  // `undefined`).
+  const merged: {
+    title?: string
+    meta?: Meta["meta"]
+    link?: Meta["link"]
+    script?: Meta["script"]
+    unsafeScript?: Meta["unsafeScript"]
+    lang?: string
+    dir?: Meta["dir"]
+  } = {}
+  if (title !== undefined) merged.title = title
+  if (meta.length > 0) merged.meta = meta
+  if (link.length > 0) merged.link = link
+  if (script.length > 0) merged.script = script
+  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
+  if (lang !== undefined) merged.lang = lang
+  if (dir !== undefined) merged.dir = dir
+  return merged as Meta
+}

package/src/internal/server-boundary.ts

@@ -3,8 +3,7 @@
  *
  * The client build must never ship server-only code, or server-only config, to a browser. Three
  * conventions enforce that, and each has to mean the SAME thing in every pipeline that builds the client
- * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`'s refusal
- * (which cannot transform, so it refuses to start instead):
+ * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`:
  *
  *   - `*.server` modules - emptied, so a secret / `node:` / native import subtree never reaches the client.
  *   - `*.fn` modules     - replaced with HTTP stubs, so the function bodies (and their imports) stay server-side.

package/src/isr.ts

@@ -572,7 +572,10 @@ export function withISR(
   }
 
   return async (req, platform) => {
-    const key = req.method === "GET" ? keyOf(req) : null
+    // A data-mode soft-nav GET bypasses the cache entirely: entries are full HTML documents keyed
+    // by URL, and serving one to a loader-data fetch would hand the client HTML where it expects
+    // the loader payload. (The write path already refuses to cache data-mode responses.)
+    const key = req.method === "GET" && req.headers.get("x-nifra-data") === null ? keyOf(req) : null
     if (key === null) return app.fetch(req, platform)
 
     // Draft/preview: an editor (valid signed cookie) always renders fresh and is never cached, so

package/src/llms-txt.ts

@@ -79,35 +79,39 @@ function clientCall(method: string, path: string, schema: unknown): string {
   return `await ${chain}${call}`
 }
 
+/** Read the project's `AGENTS.md`, or `""` if there isn't one (or we're on an edge runtime with no
+ * filesystem). Never throws - a missing file just means no guidelines section. */
+async function readAgentsMd(): Promise<string> {
+  // Edge bundles define this flag and dead-code-eliminate the filesystem branch. Keeping the import
+  // behind a runtime-only `typeof Bun` check is insufficient: Rollup must still emit an unresolved
+  // `node:` dependency, which workerd cannot load.
+  const edgeRuntime = (
+    globalThis as typeof globalThis & { readonly __NIFRA_EDGE_RUNTIME__?: boolean }
+  ).__NIFRA_EDGE_RUNTIME__
+  if (edgeRuntime === true) return ""
+  try {
+    if (typeof Bun !== "undefined") return await Bun.file("AGENTS.md").text()
+    const fs = await import("node:fs/promises")
+    return await fs.readFile("AGENTS.md", "utf-8")
+  } catch {
+    return ""
+  }
+}
+
 export async function generateLlmsTxt(
   full: boolean,
   pageRoutes: ReadonlyArray<{ readonly pattern: string; readonly id: string }>,
   backend: unknown,
+  options: { readonly includeLocalGuidelines?: boolean } = {},
 ): Promise<string> {
   let output = ""
   output += `# Nifra App Context\n\n`
   output += `This is a machine-readable context endpoint describing the API routes, pages, and conventions of this Nifra application.\n\n`
 
-  // 1. Project Guidelines
-  let agentsMd = ""
-  try {
-    // Edge bundles define this flag and dead-code-eliminate the filesystem branch. Keeping the import
-    // behind a runtime-only `typeof Bun` check is insufficient: Rollup must still emit an unresolved
-    // `node:` dependency, which workerd cannot load.
-    const edgeRuntime = (
-      globalThis as typeof globalThis & { readonly __NIFRA_EDGE_RUNTIME__?: boolean }
-    ).__NIFRA_EDGE_RUNTIME__
-    if (edgeRuntime !== true) {
-      if (typeof Bun !== "undefined") {
-        agentsMd = await Bun.file("AGENTS.md").text()
-      } else {
-        const fs = await import("node:fs/promises")
-        agentsMd = await fs.readFile("AGENTS.md", "utf-8")
-      }
-    }
-  } catch {
-    // ignore
-  }
+  // 1. Project Guidelines. Off unless the app opts in: `AGENTS.md` is a repo file written for the
+  //    team, not a page, and this endpoint is public - a note about an unshipped feature or an
+  //    internal hostname in it would be served to anyone who asks.
+  const agentsMd = options.includeLocalGuidelines === true ? await readAgentsMd() : ""
 
   if (agentsMd) {
     output += `## Guidelines & Conventions\n\n`