@nifrajs/web 2.10.0 → 2.12.0

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 }
 }
 
 /**

package/src/plugins/kit.ts

@@ -11,6 +11,16 @@ import type { BunPlugin } from "bun"
 /** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
 
+/**
+ * Re-keys the app-owned imports of a module the SERVER half of a plugin just compiled, so an edit below
+ * a route reaches SSR instead of being served from Bun's import cache. A plugin that claims a file
+ * extension is the only code that ever sees that file's source, so it is the only place its imports can
+ * be versioned - every `generate: "ssr"` loader should return its output through this.
+ *
+ * A no-op on the client half and outside a dev server. See `../dev-ssr-graph.ts` for the whole design.
+ */
+export { rewriteSsrImports } from "../dev-ssr-graph.ts"
+
 const packageRootCache = new Map<string, string>()
 
 /** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root),
@@ -57,6 +67,67 @@ export function hash8(input: string): string {
   return h.toString(16).padStart(8, "0")
 }
 
+/**
+ * Env flag a nifra dev server sets for its own lifetime, so a framework compiler plugin can tell a dev
+ * compile from a `nifra build` one. Exported for the dev server that sets it; plugins ask
+ * {@link devServerCompile} instead of reading it.
+ */
+export const DEV_HMR_ENV = "NIFRA_DEV_HMR"
+
+/**
+ * True while a nifra dev server is running, i.e. the compile may emit HMR wiring (and, where the
+ * framework couples the two, dev-mode runtime output).
+ *
+ * The phase cannot be a plugin constructor argument: an app builds its `clientPlugins` once in
+ * `nifra.config.ts` and the same plugin objects serve both `nifra dev` and `nifra build`. Guarding the
+ * emitted code with `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so
+ * the HMR calls were measured shipping in production client chunks. The dev server announces itself in
+ * the environment instead, and `nifra build` never sets it. Read per compile (not captured at
+ * registration) so the flag is honoured however late the server sets it.
+ */
+export function devServerCompile(): boolean {
+  return process.env[DEV_HMR_ENV] === "1"
+}
+
+/**
+ * The app root and the routes directory of the running dev server, for plugins that need to tell one of
+ * the app's own components from a dependency or a route module. Set alongside {@link DEV_HMR_ENV}; read
+ * through {@link devHotComponent}.
+ */
+export const DEV_ROOT_ENV = "NIFRA_DEV_ROOT"
+export const DEV_ROUTES_ENV = "NIFRA_DEV_ROUTES"
+
+const under = (path: string, dir: string | undefined): boolean =>
+  dir !== undefined &&
+  dir !== "" &&
+  (path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`))
+
+/**
+ * Whether a dev compile of `path` may wrap the module in component-level hot-patching - i.e. whether it
+ * is one of the app's OWN components rather than a dependency or a route module.
+ *
+ * The exclusions are not caution, they are two things such a wrapper cannot survive:
+ *
+ *   - a **dependency**, whose components are the framework's own composition machinery. An adapter folds
+ *     a layout chain through them, so they are entered from a snippet or as a dynamic component - and a
+ *     wrapper there sits between the SSR markup and the component that is supposed to claim it.
+ *   - a **route module**, for the same reason one level down: a route or layout IS a chain member, so it
+ *     is always the dynamic child. It is also the wrong boundary to patch - a route module carries the
+ *     loader and meta the server ran, and re-running those is a navigation, not a patch. Editing one
+ *     finds no accepting module and reloads the page, which is the correct outcome.
+ *
+ * Both cost nothing in practice: the components an edit loop actually touches are the views, and a view
+ * that wants to hot-patch lives outside the routes directory. Where the split is unknown (no dev server,
+ * or a root that was never announced), the answer is `false` - a full reload is always correct, a
+ * mispatched tree is not.
+ */
+export function devHotComponent(path: string): boolean {
+  const root = process.env[DEV_ROOT_ENV]
+  if (!under(path, root)) return false
+  if (path.includes("/node_modules/")) return false
+  return !under(path, process.env[DEV_ROUTES_ENV])
+}
+
 /**
  * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module -
  * the idiom the Vue plugin established (`?vue-css`). Register one per plugin `setup`; call `emit` per

package/src/render-seam.ts

@@ -0,0 +1,76 @@
+/**
+ * Framework-agnostic rendering protocol shared by the web runtime and every render adapter.
+ *
+ * This module is intentionally small and has no runtime dependencies. Keeping the protocol and the
+ * dev SSR-loader singleton here lets adapters and conformance tests depend on the seam directly
+ * without importing the document renderer through the root module. The singleton is stored on
+ * globalThis because the Bun and Vite dev pipelines can evaluate two copies in one process.
+ */
+import type { Submission } from "./router.ts"
+
+/** The data handed to a route component. */
+export interface RenderProps {
+  readonly data: unknown
+  /** Per-layout loader data, aligned index-for-index with the layout prefix of `chain`. */
+  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). */
+  readonly pendingPath?: string
+  /** The in-flight client submit, for optimistic UI (client-only; absent on SSR). */
+  readonly submission?: Submission
+  /** The matched route's decoded path params. */
+  readonly params?: Readonly<Record<string, string>>
+  /** The current URL's `pathname + search` (no hash). */
+  readonly path?: string
+  /** The route's typed, validated search params. */
+  readonly search?: Record<string, unknown>
+}
+
+/**
+ * The seam every render adapter implements. New adapters should prove these invariants with
+ * `assertRenderAdapterConformance`; framework-specific behavior remains locally tested.
+ */
+export interface RenderAdapter {
+  /**
+   * Render a route's layout `chain` (outermost layout → page) to a Web stream of HTML bytes,
+   * including the framework's hydration markers.
+   */
+  renderToStream(
+    chain: readonly unknown[],
+    props: RenderProps,
+  ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
+  /** Render the chain to a complete HTML string when no content is deferred. */
+  renderToString?(chain: readonly unknown[], props: RenderProps): string | Promise<string>
+  /** Per-document bootstrap markup injected into `<head>` for client hydration. */
+  hydrationHead(nonce?: string): string
+}
+
+/** Loads a module through the dev server's module graph rather than the runtime's resolver. */
+export type SsrModuleLoader = (id: string) => Promise<unknown>
+
+const SSR_MODULE_LOADER_SLOT = Symbol.for("nifra.web.ssr-module-loader")
+const loaderSlot = globalThis as { [SSR_MODULE_LOADER_SLOT]?: SsrModuleLoader | undefined }
+
+/** Publish or clear the dev server's SSR module loader. */
+export function setSsrModuleLoader(load: SsrModuleLoader | undefined): void {
+  loaderSlot[SSR_MODULE_LOADER_SLOT] = load
+}
+
+/** Return the dev server's SSR module loader, when one owns SSR resolution. */
+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. */
+export const LAYOUT_DATA_GLOBAL = "__NIFRA_LAYOUT_DATA__"
+/** Global the server writes the matched route id into. */
+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 used to find a non-default hydration container. */
+export const ROOT_ATTRIBUTE = "data-nifra-root"

package/src/vite.ts

@@ -20,9 +20,11 @@ import { relative, resolve as resolvePath } from "node:path"
 import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEFAULT_DEV_PORT, generateClientEntry, setSsrModuleLoader } from "./index.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { importVite } from "./internal/vite-import.ts"
+import { scopedName } from "./plugins/css-modules.ts"
+import { DEV_ROOT_ENV, DEV_ROUTES_ENV, reproduciblePath } from "./plugins/kit.ts"
 import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
 import { viteServerOnlyEmpty } from "./plugins/vite-server-only.ts"
 
@@ -296,6 +298,12 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const routesDir = resolvePath(options.routesDir)
   const port = options.port ?? DEFAULT_DEV_PORT
 
+  // Which files are the app's own components, for framework plugins that hot-patch at component
+  // granularity (`devHotComponent`). Announced in the environment rather than passed, because the
+  // plugin that reads it is constructed by the app, in its own config, before this server exists.
+  process.env[DEV_ROOT_ENV] = root
+  process.env[DEV_ROUTES_ENV] = routesDir
+
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
   const toUrl = (file: string): string => `/${relative(root, `${routesDir}/${file}`)}`
   const writeClientEntry = (): void => {
@@ -442,10 +450,26 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
         externalConditions: ssrConditions,
       },
     },
+    css: {
+      modules: {
+        // Vite ships its own CSS-Modules naming (`_name_<base64>`); the Bun pipeline and every
+        // `nifra build` use `scopedName`. Left alone, one class is called two different things
+        // depending on which pipeline served it, so a selector written against a generated name works
+        // in dev and vanishes in production - and the two dev pipelines disagree with each other. The
+        // name is defined once, in the plugin, and Vite is handed that definition.
+        generateScopedName: (name: string, filename: string): string =>
+          scopedName(reproduciblePath(filename), name),
+      },
+    },
     ...(options.define ? { define: options.define } : {}),
   })
 
   const ssrLoad = (absolutePath: string): Promise<unknown> => vite.ssrLoadModule(absolutePath)
+  // Published so an ADAPTER can reach this graph too. Route modules already load through it; an
+  // adapter that has to load a compiled asset of its own on the server (`@nifrajs/web-svelte` and its
+  // `Chain.svelte`) would otherwise take it from the runtime, which has no compiler for it and no
+  // reason to agree with Vite about which copy of the framework runtime it renders through.
+  setSsrModuleLoader(ssrLoad)
   app = await options.createApp(entryUrl, ssrLoad)
 
   // Re-create the app on change so a hard reload picks up a route ADD/REMOVE (the manifest comes
@@ -486,6 +510,10 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   return {
     port: typeof address === "object" && address !== null ? address.port : port,
     stop: async () => {
+      // Cleared with the server that owns it: the slot is process-global, so a stopped server leaving
+      // its loader behind would hand the next one's adapter a graph that is closed (tests start and
+      // stop several dev servers in one process).
+      setSsrModuleLoader(undefined)
       server.close()
       await vite.close()
     },