@nifrajs/web 2.11.0 → 2.12.0

package/src/fonts-google.ts

@@ -30,8 +30,8 @@ import type { LinkDescriptor } from "./manifest.ts"
 export interface GoogleFontOptions {
   /** Family name exactly as Google lists it, e.g. `"Inter"`, `"Open Sans"`, `"Roboto Mono"`. */
   readonly family: string
-  /** Weights to request - numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
-   * keywords `"normal"`/`"bold"`. Defaults to `[400]`. */
+  /** Weights to request - numbers (`400`), numeric strings, a variable range (`"100..900"`, the
+   * CSS-style `"100 900"` also accepted), or the keywords `"normal"`/`"bold"`. Defaults to `[400]`. */
   readonly weights?: readonly (number | string)[]
   /** Styles to request. Defaults to `["normal"]`. */
   readonly styles?: readonly ("normal" | "italic")[]
@@ -144,7 +144,8 @@ function validateFamily(family: string): string {
 }
 
 /** Normalize a weight to the token Google expects: `400`, `"700"`, `normal`→`400`, `bold`→`700`, or a
- * variable range `"100 900"`. Rejects anything else (these land in the request URL). */
+ * variable range as `"100..900"` (also accepted spelled `"100 900"`). Rejects anything else (these
+ * land in the request URL). */
 function normalizeWeight(weight: number | string): string {
   if (typeof weight === "number") {
     if (!Number.isInteger(weight) || weight < 1 || weight > 1000) {
@@ -155,8 +156,16 @@ function normalizeWeight(weight: number | string): string {
   const w = weight.trim()
   if (w === "normal") return "400"
   if (w === "bold") return "700"
-  // A single numeric weight, or a variable range like "100 900".
-  if (/^\d{1,4}$/.test(w) || /^\d{1,4} \d{1,4}$/.test(w)) return w
+  if (/^\d{1,4}$/.test(w)) return w
+  // A variable range - Google's own "100..900" axis syntax or the CSS-style "100 900" spelling.
+  // Either way the URL token must be the DOTTED form; a literal space 400s at the CSS2 endpoint.
+  const range = /^(\d{1,4})(?:\.\.| )(\d{1,4})$/.exec(w)
+  if (range !== null) {
+    if (Number(range[1]) >= Number(range[2])) {
+      throw new Error(`loadGoogleFont: invalid weight range ${JSON.stringify(weight)} (min < max)`)
+    }
+    return `${range[1]}..${range[2]}`
+  }
   throw new Error(`loadGoogleFont: invalid weight ${JSON.stringify(weight)}`)
 }
 

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,
@@ -48,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,
@@ -57,7 +65,6 @@ import {
   RETAIN_HEADER,
   REVALIDATE_HEADER,
   STATUS_HEADER,
-  type Submission,
 } from "./router.ts"
 import { searchOf, searchOfChain } from "./search.ts"
 
@@ -117,6 +124,7 @@ export {
   type Manifest,
   type Meta,
   type MetaArgs,
+  type MetaDescriptor,
   type MetaInput,
   type RouteEntry,
   type RouteModule,
@@ -235,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
@@ -242,142 +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
-}
-
-/**
- * Loads a module through the DEV SERVER'S module graph rather than the runtime's. Takes an absolute
- * file path or a bare specifier; resolution, compilation and caching are the dev server's.
- */
-export type SsrModuleLoader = (id: string) => Promise<unknown>
-
-/* A `globalThis` singleton for the same reason `@nifrajs/web-react`'s router context is one: in dev
- * this module is evaluated twice in one process (the CLI's copy under Bun, and the app's copy), and a
- * module-level `let` would leave the adapter reading a slot the dev server set on the other copy. */
-const SSR_MODULE_LOADER_SLOT = Symbol.for("nifra.web.ssr-module-loader")
-/* Explicitly `| undefined`: clearing the slot is part of the contract (a dev server clears it on
- * stop), and under `exactOptionalPropertyTypes` "absent" and "set to undefined" are separate types. */
-const loaderSlot = globalThis as { [SSR_MODULE_LOADER_SLOT]?: SsrModuleLoader | undefined }
-
-/**
- * Publishes the dev server's SSR module loader. Called by a dev server that owns SSR resolution
- * itself; pass `undefined` to clear it on shutdown.
- */
-export function setSsrModuleLoader(load: SsrModuleLoader | undefined): void {
-  loaderSlot[SSR_MODULE_LOADER_SLOT] = load
-}
-
-/**
- * The dev server's SSR module loader, or `undefined` when nothing owns SSR resolution but the runtime
- * - the Bun dev pipeline, and every production build, where the adapter's assets are compiled ahead
- * of time and a plain `import` is already the right thing.
- *
- * An adapter that must load a COMPILED asset at runtime (a `.svelte` component, say) has to prefer
- * this over a bare `import`, and has to take the framework's SERVER RENDERER from it as well, not
- * just the component. A component compiled by the dev server renders through the renderer the dev
- * server resolved; mixing the two puts two copies of the framework runtime in one component tree,
- * where context written by one half is invisible to the other.
- */
-export function ssrModuleLoader(): SsrModuleLoader | undefined {
-  return loaderSlot[SSR_MODULE_LOADER_SLOT]
-}
-
-/** 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
@@ -1028,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
@@ -1414,13 +1312,67 @@ export function unsafeInlineScript(
   }
 }
 
-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.
    *
@@ -1485,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
@@ -1573,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 }
@@ -1599,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`)
@@ -2142,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,
@@ -2248,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).
@@ -2262,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) {
@@ -2327,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" },
     })
@@ -2428,6 +2399,16 @@ export function generateClientEntry(
     // 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

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`

package/src/manifest.ts

@@ -222,9 +222,11 @@ export interface RouteModule {
    */
   readonly getStaticPaths?: GetStaticPaths
   /**
-   * ISR freshness for this route, in **seconds**. `createWebApp` emits it as an `x-nifra-revalidate`
-   * response header that `withISR` reads to set the page's cache TTL (overriding the wrapper's
-   * default). Older-than-`revalidate` cached pages are served stale while regenerating.
+   * ISR freshness for this route, in **seconds**. `createWebApp` emits it as an
+   * `x-nifra-isr-revalidate` response header that `withISR` reads to set the page's cache TTL
+   * (overriding the wrapper's default). Older-than-`revalidate` cached pages are served stale while
+   * regenerating. (Distinct from the action-revalidation `x-nifra-revalidate` header - a CSV path
+   * list the client parses to refetch - so the two channels never alias.)
    */
   readonly revalidate?: number
   /** Optional bounded tags used by ISR on-demand invalidation (`?tag=...`). */

package/src/navigation.ts

@@ -18,6 +18,13 @@ import { serializeSearch } from "./search.ts"
 export interface NavigateOptions {
   /** Replace the current history entry instead of pushing a new one (like `history.replaceState`). */
   readonly replace?: boolean
+  /**
+   * Opaque per-entry state stored on the created history entry (under `history.state.nifraState`, so
+   * it never collides with the router's own bookkeeping keys). Structured-cloneable only, like
+   * `history.pushState`'s first argument. Read it back via `history.state.nifraState`; the browser
+   * restores it automatically on back/forward. Ignored for history-delta navigations.
+   */
+  readonly state?: unknown
 }
 
 /**
@@ -56,6 +63,7 @@ export interface NavigateTargetInput {
   readonly to: string
   readonly search?: Record<string, unknown>
   readonly replace?: boolean
+  readonly state?: unknown
 }
 
 /**
@@ -71,6 +79,7 @@ export interface NavigateFunction {
     readonly to: To
     readonly search?: NavigateSearchOf<To>
     readonly replace?: boolean
+    readonly state?: unknown
   }): void
 }
 
@@ -86,7 +95,11 @@ export function resolveNavigate(
 ): { readonly to: string | number; readonly options: NavigateOptions | undefined } {
   if (typeof to !== "object") return { to, options }
   const query = to.search !== undefined ? serializeSearch(to.search) : ""
-  return { to: to.to + query, options: to.replace === true ? { replace: true } : options }
+  if (to.replace !== true && to.state === undefined) return { to: to.to + query, options }
+  const resolved: { replace?: boolean; state?: unknown } = { ...options }
+  if (to.replace === true) resolved.replace = true
+  if (to.state !== undefined) resolved.state = to.state
+  return { to: to.to + query, options: resolved }
 }
 
 /**